Files
prometeu-studio/tools/documentation/verify.py
T

105 lines
4.3 KiB
Python

#!/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.update((root / "discussion/workflow").rglob("*.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))