docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -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))
|
||||
Reference in New Issue
Block a user