104 lines
4.2 KiB
Python
104 lines
4.2 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.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))
|