Sylpheed/tools/port/peer-head

#!/usr/bin/env python3
"""Is the copy of a file I am reading the newest one anywhere in the repository?

🔴 THE RULE THIS REPLACES IS A MEMORY. Two agents spent days on a shared-state
problem that is really two problems:

  what a peer HOLDS   readable right now, from any topic branch, by anyone who
                      remembers the ref exists -- `git show <ref>:<path>`
  what a peer must be TOLD   still needs a human to merge to `main`

Both were being filed as blocked on the merge. Half never was. The Decoder read
this port's `BLOCKED.md` at a copy 234 commits behind and reported a row as stale
that had been corrected for days -- with the live file one `git show` away, on a
ref already fetched in their checkout. This port read `main`'s 926-line HANDOFF
for two days while the live one sat on a branch it had already been citing by sha.

Same gap, opposite directions, and the fix in both cases costs one command. So
the command exists rather than the intention.

Prints, for each path: the newest commit touching it on ANY ref, how far the
working tree's copy is behind, and the exact `git show` line to read the live one.
"""
import subprocess, sys, os

# The files this port depends on that another agent writes. Named rather than
# globbed: the point is to be explicit about whose head is being tracked.
DEFAULT = [
    "docs/port/HANDOFF.md",
    "docs/game/navigation.md",
    "docs/agents/PROTOCOL.md",
    "docs/port/MISSION.md",
    "docs/port/PORT-MISSION.md",
]


def git(*a):
    return subprocess.run(["git", *a], capture_output=True, text=True).stdout


def main():
    paths = sys.argv[1:] or DEFAULT
    stale = 0
    print(f"  {'path':<30} {'mine':<9} {'newest':<9} {'behind':>6}  where")
    for p in paths:
        newest = git("log", "--all", "--format=%h", "--", p).split()
        mine = git("log", "-1", "--format=%h", "--", p).split()
        if not newest:
            print(f"  {p:<30} {'-':<9} {'-':<9} {'-':>6}  no commit touches this path")
            continue
        n, m = newest[0], (mine[0] if mine else "-")
        # 🔴 `--all --not HEAD` counts commits touching the path that are not in
        # my ancestry. That is a TRUE number and it is NOT staleness: two
        # branches can each carry an unrelated commit to the same file while my
        # copy is still the newest. The first version printed it as "behind" and
        # told me to `git show` MY OWN version of PROTOCOL.md -- a real count
        # with a fabricated label, which is the family this project keeps paying
        # for. What decides staleness is whether the NEWEST commit is reachable
        # from HEAD.
        reachable = subprocess.run(["git", "merge-base", "--is-ancestor", n, "HEAD"],
                                   capture_output=True).returncode == 0
        diverged = len(git("log", "--all", "--not", "HEAD", "--format=%h", "--", p).split())
        behind = 0 if reachable else diverged
        refs = git("for-each-ref", "--format=%(refname:short)", "--contains", n,
                   "refs/remotes", "refs/heads").split()
        where = refs[0] if refs else "?"
        note = ""
        if behind == 0 and diverged:
            note = f"  ({diverged} commit(s) elsewhere, none newer)"
        flag = note if behind == 0 else f"  <- {behind} unread; read it with:"
        print(f"  {p:<30} {m:<9} {n:<9} {behind:>6}{flag}")
        if behind:
            stale += 1
            print(f"  {'':<30} git show {n}:{p}   (on {where})")
    print()
    if stale:
        print(f"  🔴 {stale} file(s) have a newer version than the one in this tree.")
        print("     Reading it needs no merge and no human. Being TOLD about it does.")
    else:
        print("  every tracked file is at its newest version anywhere")
    # Not an error: being behind is the normal state between two topic branches.
    # This reports; the caller decides. Exit 0 unless a path is unknown.
    return 0


sys.exit(main())