from __future__ import annotations from dataclasses import dataclass from pathlib import Path from .markdown_utils import extract_headings @dataclass(frozen=True) class DocumentEntry: path: Path title: str relative_path: str def first_heading(path: Path) -> str | None: headings = extract_headings(path) return headings[0].title if headings else None def discover_documents(project_root: Path) -> list[DocumentEntry]: candidates: list[Path] = [] sample = project_root / "sample.md" if sample.exists(): candidates.append(sample) docs_dir = project_root / "docs" if docs_dir.exists(): candidates.extend(sorted(docs_dir.rglob("*.md"))) entries: list[DocumentEntry] = [] for path in candidates: resolved = path.resolve() title = first_heading(resolved) or resolved.stem.replace("_", " ").title() relative_path = resolved.relative_to(project_root).as_posix() entries.append(DocumentEntry(path=resolved, title=title, relative_path=relative_path)) return entries