from pathlib import Path
from typing import Dict, List, Optional


class NavSpec:
    """
    Parsed representation of `docforge.nav.yml`.

    This object represents *semantic intent* and is independent
    of filesystem structure or MkDocs specifics.
    """

    home: Optional[str]
    groups: Dict[str, List[str]]

    def __init__(
        self,
        home: Optional[str],
        groups: Dict[str, List[str]],
    ) -> None:
        ...

    @classmethod
    def load(cls, path: Path) -> "NavSpec":
        """
        Load and validate a nav specification from YAML.

        Raises:
            FileNotFoundError: if the file does not exist
            ValueError: if the schema is invalid
        """
        ...

    def all_patterns(self) -> List[str]:
        """
        Return all path patterns referenced by the spec
        (including home and group entries).
        """
        ...


def load_nav_spec(path: Path) -> NavSpec: ...