docs: consolidate canonical specs and preserve PBS reference IDs

This commit is contained in:
2026-10-28 15:11:00 +00:00
parent 9504f4694a
commit 3a3417eb44
74 changed files with 3231 additions and 270 deletions
+104
View File
@@ -0,0 +1,104 @@
#!/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))