#!/usr/bin/env python3 """Check repository Markdown navigation without fetching or modifying sources. Runtime mirrors keep provider-relative links and exact bytes. Pass --runtime to also check provider links against a local read-only checkout; otherwise those references are reported separately and do not make ordinary builds depend on it. """ import argparse import re import subprocess from pathlib import Path from urllib.parse import unquote def prose(text): """Exclude fenced examples; their sample links are not document navigation.""" lines = [] fence = None for line in text.splitlines(): match = re.match(r"^\s{0,3}(`{3,}|~{3,})", line) if match: marker = match.group(1) if fence is None: fence = marker elif marker[0] == fence[0] and len(marker) >= len(fence): fence = None lines.append("") else: lines.append(line if fence is None else "") return "\n".join(lines) def anchors(text): found = set(re.findall(r'(?:id|name)=["\']([^"\']+)["\']', text)) counts = {} for heading in re.findall(r"^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$", prose(text), re.M): heading = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", heading) heading = re.sub(r"<[^>]+>", "", heading).lower() slug = re.sub(r"[^\w\-\s]", "", heading).replace(" ", "-") count = counts.get(slug, 0) counts[slug] = count + 1 found.add(slug + (f"-{count}" if count else "")) return found def verify(root, runtime): tracked = subprocess.check_output( ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"], cwd=root, text=True).split("\0") files = {root / name for name in tracked if name.endswith(".md")} files.add(root / "AGENTS.md") files = sorted(path for path in files if path.is_file()) mirror_names = {"docs/vm-arch/ARCHITECTURE.md", "docs/vm-arch/ISA_CORE.md"} failures = [] local_count = provider_count = 0 anchor_cache = {} for source in files: relative = source.relative_to(root).as_posix() content = prose(source.read_text()) links = re.findall(r"\]\(([^)\n]+)\)", content) links += re.findall(r"^\s*\[[^\]]+\]:\s*(\S+)", content, re.M) for link in links: link = link.strip().strip("<>") if re.match(r"[a-zA-Z][a-zA-Z\d+.-]*:", link) or link.startswith("//"): continue path, _, fragment = link.partition("#") target = (source.parent / unquote(path)).resolve() if path else source provider = False if relative in mirror_names: provider = True if runtime: target = ((runtime / relative).parent / unquote(path)).resolve() if path else runtime / relative elif target.is_relative_to(root.parent / "runtime"): provider = True if runtime: target = runtime / target.relative_to(root.parent / "runtime") if provider: provider_count += 1 if runtime is None: continue else: local_count += 1 if not target.exists(): failures.append(f"{relative}: missing target {link}") elif fragment and target.suffix == ".md": if target not in anchor_cache: anchor_cache[target] = anchors(target.read_text()) if unquote(fragment) not in anchor_cache[target]: failures.append(f"{relative}: missing anchor {link}") for failure in failures: print(failure) mode = "checked" if runtime else "classified; use --runtime to check" print(f"Markdown: {len(files)} files; {local_count} local links; " f"{provider_count} provider links ({mode}); {len(failures)} failures") return bool(failures) if __name__ == "__main__": parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2]) parser.add_argument("--runtime", type=Path) args = parser.parse_args() raise SystemExit(verify(args.root.resolve(), args.runtime.resolve() if args.runtime else None))