from __future__ import annotations


class TestSkillFilesBundle:
    """Covers SkillFilesBundle construction and path-based categorization."""

    class TestFromRoot:
        """Covers bundle creation from resource roots."""

        def test_builds_bundles(self) -> None:
            """Ensures from_root builds bundles from discovered markdown docs."""

        def test_delegates_to_from_docs(self) -> None:
            """Ensures from_root delegates bundle assembly to from_docs."""

    class TestFromDocs:
        """Covers bundle creation from preloaded markdown documents."""

        def test_groups_by_slug(self) -> None:
            """Ensures from_docs groups documents by skill slug."""

        def test_one_bundle_per_slug(self) -> None:
            """Ensures from_docs produces one SkillFilesBundle per slug."""

    class TestFromPaths:
        """Covers classification of skill, reference, and other documents."""

        def test_selects_skill_md(self) -> None:
            """Ensures from_paths selects SKILL.md as the primary document."""

        def test_collects_references(self) -> None:
            """Ensures from_paths captures reference docs under references/."""

        def test_collects_other_docs(self) -> None:
            """Ensures from_paths classifies non-reference docs as other docs."""


class TestGroupSkillPaths:
    """Covers grouping markdown documents by derived skill slug."""

    def test_groups_slugged_docs(self) -> None:
        """Ensures group_skill_paths groups only documents with a slug."""

    def test_excludes_unslugged_docs(self) -> None:
        """Ensures group_skill_paths excludes documents without skill slugs."""

    def test_returns_sets(self) -> None:
        """Ensures group_skill_paths returns sets of docs per slug."""

    def test_stable_grouping(self) -> None:
        """Ensures group_skill_paths behaves consistently after internal sorting."""