from __future__ import annotations from dataclasses import dataclass from pathlib import Path from .media import MARKDOWN_EXTENSIONS, WEBPAGE_EXTENSIONS from .markdown_utils import extract_headings SUPPORTED_DOCUMENT_EXTENSIONS = MARKDOWN_EXTENSIONS | WEBPAGE_EXTENSIONS EXCLUDED_DIR_NAMES = { ".git", "__pycache__", ".pytest_cache", ".mypy_cache", "build", "dist", "logs", "html", "mdhelper_env", "vendor", "venv", ".venv", } @dataclass(frozen=True) class DocumentEntry: path: Path title: str relative_path: str def first_heading(path: Path) -> str | None: if path.suffix.lower() not in {".md", ".markdown"}: return None headings = extract_headings(path) return headings[0].title if headings else None def discover_documents(project_root: Path) -> list[DocumentEntry]: candidates = [ path for path in sorted(project_root.rglob("*")) if path.is_file() and path.suffix.lower() in SUPPORTED_DOCUMENT_EXTENSIONS and not any(part.startswith(".") or part in EXCLUDED_DIR_NAMES for part in path.relative_to(project_root).parts) ] 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