"""Check repository-local Markdown file links and heading anchors.""" from __future__ import annotations import argparse from collections.abc import Iterable from dataclasses import dataclass from pathlib import Path import re import unicodedata from urllib.parse import unquote HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$", re.MULTILINE) LINK_PATTERN = re.compile( r"(? int: arguments = _parser().parse_args() root = arguments.root.resolve() excluded_paths = tuple(_resolve_excluded_path(root, path) for path in arguments.exclude) result = check_markdown(root, excluded_paths) print( f"checked={result.checked} markdown_files={result.markdown_files} " f"errors={len(result.errors)}" ) for error in result.errors: print(error) return 1 if result.errors else 0 def check_markdown(root: Path, excluded_paths: tuple[Path, ...] = ()) -> CheckResult: markdown_files = tuple(_markdown_files(root, excluded_paths)) repository_root = root.parent if root.is_file() else root anchors_by_file: dict[Path, set[str]] = {} errors: list[str] = [] checked = 0 for source in markdown_files: for destination in _destinations(source): if _is_external(destination): continue checked += 1 path_part, _, anchor = destination.partition("#") target = source if not path_part else (source.parent / path_part).resolve() source_name = _display_path(source, repository_root) if not target.is_file(): errors.append(f"{source_name} -> {destination}: missing file") continue if anchor and anchor not in anchors_by_file.setdefault(target, _anchors(target)): errors.append(f"{source_name} -> {destination}: missing anchor") return CheckResult( checked=checked, markdown_files=len(markdown_files), errors=tuple(errors), ) def _parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser( description="Validate relative Markdown file links and heading anchors." ) parser.add_argument("root", type=Path, nargs="?", default=Path(".")) parser.add_argument( "--exclude", type=Path, action="append", default=[], help="Path relative to ROOT that the repository scan must skip; repeatable.", ) return parser def _markdown_files(root: Path, excluded_paths: tuple[Path, ...]) -> Iterable[Path]: if root.is_file(): if root.suffix != ".md": raise ValueError(f"expected a Markdown file or directory, got: {root}") return (root,) return tuple( path for path in sorted(root.rglob("*.md")) if not any(_is_within(path, excluded_path) for excluded_path in excluded_paths) ) def _resolve_excluded_path(root: Path, excluded_path: Path) -> Path: return excluded_path.resolve() if excluded_path.is_absolute() else (root / excluded_path).resolve() def _is_within(path: Path, parent: Path) -> bool: try: path.resolve().relative_to(parent) except ValueError: return False return True def _destinations(source: Path) -> Iterable[str]: body = source.read_text(encoding="utf-8") return ( unquote(match.group(1).strip("<>")) for match in LINK_PATTERN.finditer(body) ) def _is_external(destination: str) -> bool: return destination.startswith(EXTERNAL_PREFIXES) or destination.startswith("/") def _anchors(path: Path) -> set[str]: seen: dict[str, int] = {} anchors: set[str] = set() for match in HEADING_PATTERN.finditer(path.read_text(encoding="utf-8")): base = _slug(match.group(2)) duplicate_number = seen.get(base, 0) seen[base] = duplicate_number + 1 anchors.add(base if duplicate_number == 0 else f"{base}-{duplicate_number}") return anchors def _slug(text: str) -> str: without_links = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text) without_formatting = re.sub(r"[`*_~]", "", without_links).strip().lower() pieces: list[str] = [] for character in without_formatting: if character.isspace(): pieces.append("-") elif character in {"-", "_"} or unicodedata.category(character)[0] in {"L", "N"}: pieces.append(character) return re.sub(r"-+", "-", "".join(pieces)).strip("-") def _display_path(path: Path, root: Path) -> str: try: return str(path.relative_to(root)) except ValueError: return str(path) if __name__ == "__main__": raise SystemExit(main())