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

from docforge.nav.spec import NavSpec


class ResolvedNav:
    """
    Fully-resolved navigation tree.

    - `home` is a semantic, docs-root–relative path (string)
    - `groups` contain resolved filesystem Paths
    - Order is preserved
    """

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

    def __init__(
        self,
        home: str | None,
        groups: Dict[str, List[Path]],
        docs_root: Path | None = None,
    ) -> None:
        self._docs_root = None
        ...

    def all_files(self) -> Iterable[Path]:
        """
        Return all resolved documentation files in nav order.

        Includes the home file (resolved against docs_root)
        followed by all group files.
        """
        ...


def resolve_nav(
    spec: NavSpec,
    docs_root: Path,
) -> ResolvedNav:
    """
    Resolve a NavSpec against a docs directory.

    Expands wildcards, validates existence, and
    resolves filesystem paths relative to docs_root.

    Raises:
        FileNotFoundError: if any referenced file is missing
        ValueError: if resolution fails
    """
    ...