Sylpheed/tools/port/check-citations

#!/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 refresh_peer_refs() -> bool:
    """Fetch before judging, so a stale local ref is not reported as a bad path.

    🔴 THIS WAS A FALSE RED IN `check-all`, TWICE. A citation added minutes after
    the other agent pushed the file resolves NOWHERE here, because this scans
    LOCAL refs. The first fix only reworded the failure to suggest fetching --
    which left the suite going red for a correct citation, i.e. it documented the
    cry-wolf instead of removing it.

    Read-only and best-effort: no network, no remote, or no credentials just means
    the scan runs against what is already here, exactly as before.
    """
    try:
        return subprocess.run(
            ["git", "fetch", "--quiet", "origin"],
            capture_output=True, timeout=60).returncode == 0
    except Exception:
        return False


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

    fetched = refresh_peer_refs()
    print("peer refs: %s" % ("fetched" if fetched else
                             "NOT fetched -- offline or no remote; results may be stale"))
    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())