from __future__ import annotations


class TestMarkdownDocument:
    """Covers MarkdownDocument construction and derived properties."""

    class TestFromRoot:
        """Covers loading markdown documents from a resource root."""

        def test_keys_by_relpath(self) -> None:
            """Ensures from_root returns a mapping keyed by relative path."""

        def test_loads_markdown_only(self) -> None:
            """Ensures from_root includes only markdown resources."""

        def test_preserves_relpaths(self) -> None:
            """Ensures from_root preserves PurePosixPath-style relative paths."""

    class TestFromResource:
        """Covers loading a single markdown document from a resource."""

        def test_reads_utf8(self) -> None:
            """Ensures from_resource reads text using UTF-8."""

        def test_sets_frontmatter(self) -> None:
            """Ensures from_resource stores frontmatter when delimiters exist."""

        def test_none_frontmatter(self) -> None:
            """Ensures from_resource sets frontmatter to None when absent."""

    class TestSkillSlugProperty:
        """Covers skill_slug derivation from document relative paths."""

        def test_returns_slug(self) -> None:
            """Ensures skill_slug returns the slug for valid skills paths."""

        def test_none_for_non_skill(self) -> None:
            """Ensures skill_slug is None for non-skills paths."""

        def test_none_for_incomplete_skill(self) -> None:
            """Ensures skill_slug is None for incomplete skills paths."""


class TestWalkResources:
    """Covers recursive resource walking and markdown filtering behavior."""

    def test_yields_markdown(self) -> None:
        """Ensures walk_resources yields markdown files from nested directories."""

    def test_ignores_other_suffixes(self) -> None:
        """Ensures walk_resources excludes files with non-matching suffixes."""

    def test_sorted_output(self) -> None:
        """Ensures walk_resources yields entries in sorted child-name order."""

    def test_applies_prefix(self) -> None:
        """Ensures walk_resources prepends the provided prefix to relpaths."""


class TestFrontmatterParsing:
    """Covers frontmatter delimiter discovery and raw block extraction."""

    def test_extracts_between_delimiters(self) -> None:
        """Ensures get_raw_frontmatter returns lines between first delimiters."""

    def test_none_without_two_delimiters(self) -> None:
        """Ensures get_raw_frontmatter returns None without two delimiters."""

    def test_allows_leading_whitespace(self) -> None:
        """Ensures delimiter detection accepts lines with leading whitespace."""