2d2caccd75
A citation added minutes after the other agent pushed the file it names resolved
NOWHERE, because this scans local refs and the local ref was stale. The citation
was right and the check was wrong. It now says so in the failure text and tells
the reader to fetch before editing.
A check that cries wolf is worse than no check -- and this one had just been
teaching me to distrust a correct citation.
🔴 Separately, my own slip: I ran this as '<check>; git commit' instead of
'<check> && git commit', so the commit landed while the check was red. The guard
was in the command and I had disabled it by punctuation.
114 lines
5.0 KiB
Python
Executable File
114 lines
5.0 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Do the repo paths cited in `docs/port/*.md` actually resolve?
|
|
|
|
tools/port/check-citations # assert
|
|
tools/port/check-citations --selftest # can it fail?
|
|
|
|
`audit-kinds` checks citations in `authored/`. Nothing checked the PROSE, and
|
|
prose is where this port explains itself. A first run found **37 of 91**
|
|
non-resolving, 41 %, in two very different classes:
|
|
|
|
* **19 on the Decoder's topic branch** — real files, not merged here. Not
|
|
errors. A reader in this checkout still cannot follow them, which is worth
|
|
reporting and not worth failing on; the fix is a merge, not an edit.
|
|
* **7 that resolve NOWHERE** — `docs/BLOCKED.md`, `docs/FORMAT.md`,
|
|
`port/manifest.json`, `port/screens/title/*.json`. Left behind by the
|
|
monorepo move and the `export/` rename. Those are simply wrong: a reader
|
|
following one gets nothing, and nothing had ever told anyone.
|
|
|
|
So the two classes are separated and only the second fails. A check that failed
|
|
on the first would be red for a state nobody in this container can fix, which is
|
|
the shape the display guard exists to prevent.
|
|
|
|
⚠️ THE PEER-BRANCH CLASS IS THE OTHER AGENT'S POINT, TURNED ON MYSELF. They
|
|
observed that everything they hand over links into `docs/re/` files that live
|
|
only on their branch, so every link they send is dangling from here. The same is
|
|
true in reverse and neither of us was counting.
|
|
"""
|
|
import os
|
|
import re
|
|
import subprocess
|
|
import sys
|
|
import glob
|
|
|
|
# A repo path with a file extension, optionally in backticks or a markdown link.
|
|
CITE = re.compile(
|
|
r"`?((?:docs|crates|port|tools|authored|export)/[\w./-]+"
|
|
r"\.(?:md|rs|gd|json|txt|py|tsv|csv))`?"
|
|
)
|
|
PEER_REFS = ("origin/auto/frame-blend-draw-path", "origin/main")
|
|
|
|
|
|
def on_a_ref(path: str) -> str | None:
|
|
"""The first ref that carries `path`, or None."""
|
|
for ref in PEER_REFS:
|
|
if subprocess.run(["git", "cat-file", "-e", f"{ref}:{path}"],
|
|
capture_output=True).returncode == 0:
|
|
return ref
|
|
return None
|
|
|
|
|
|
def scan(files):
|
|
resolves, peer, nowhere = 0, {}, {}
|
|
for p in files:
|
|
try:
|
|
text = open(p, encoding="utf-8").read()
|
|
except OSError:
|
|
continue
|
|
for m in sorted(set(CITE.findall(text))):
|
|
if os.path.exists(m):
|
|
resolves += 1
|
|
elif (ref := on_a_ref(m)):
|
|
peer.setdefault(m, (p, ref))
|
|
else:
|
|
nowhere.setdefault(m, p)
|
|
return resolves, peer, nowhere
|
|
|
|
|
|
def main() -> int:
|
|
if "--selftest" in sys.argv:
|
|
# 🔴 A CHECK THAT CANNOT FAIL IS NOT A CHECK. This plants a citation of a
|
|
# path that exists on no ref and requires the scanner to catch it, and a
|
|
# citation of a real file and requires it NOT to. Both directions,
|
|
# because a scanner that flagged everything would also "pass" the first.
|
|
tmp = os.path.join(os.environ.get("TMPDIR", "/tmp"), "check-citations-selftest")
|
|
os.makedirs(tmp, exist_ok=True)
|
|
bad = os.path.join(tmp, "bad.md")
|
|
open(bad, "w").write("see `docs/port/this-file-does-not-exist-anywhere.md`\n")
|
|
good = os.path.join(tmp, "good.md")
|
|
open(good, "w").write("see `docs/port/PORT-MISSION.md`\n")
|
|
_, _, nb = scan([bad])
|
|
r, _, ng = scan([good])
|
|
ok = len(nb) == 1 and len(ng) == 0 and r == 1
|
|
print("selftest: planted dangling caught=%s, real citation passed=%s -> %s"
|
|
% (len(nb) == 1, len(ng) == 0 and r == 1, "ok" if ok else "🔴 BROKEN"))
|
|
return 0 if ok else 2
|
|
|
|
files = sorted(glob.glob("docs/port/*.md"))
|
|
resolves, peer, nowhere = scan(files)
|
|
total = resolves + len(peer) + len(nowhere)
|
|
print("citations of repo paths in docs/port/*.md: %d" % total)
|
|
print(" resolve here : %d" % resolves)
|
|
print(" on a peer branch, not merged: %d (reported, not failed)" % len(peer))
|
|
for m, (src, ref) in sorted(peer.items()):
|
|
print(" %-52s %s <- %s" % (m, ref.split("/")[-1], os.path.basename(src)))
|
|
if nowhere:
|
|
print(" 🔴 resolve NOWHERE : %d" % len(nowhere))
|
|
for m, src in sorted(nowhere.items()):
|
|
print(" %-52s <- %s" % (m, os.path.basename(src)))
|
|
print("\n🔴 a reader following those gets nothing. Fix the path or drop the citation.")
|
|
# 🔴 FALSE RED, HIT 2026-09-02: a peer-branch file cited minutes after it
|
|
# was pushed resolves NOWHERE here, because this scans local refs and the
|
|
# local ref was stale. The citation was correct and the check was wrong.
|
|
# A check that cries wolf is worse than no check, so it now says so.
|
|
print(" ⚠️ If a path was pushed by the other agent recently, this may be")
|
|
print(" a STALE LOCAL REF rather than a bad citation. Run")
|
|
print(" `git fetch origin` and re-run before editing anything.")
|
|
return 1
|
|
print(" 🔴 resolve nowhere : 0")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|