#!/usr/bin/env python3
"""Does HANDOFF.md still assert something its own linked doc has retracted?

This has now happened four times: a finding lands in docs/re/ and the page the
port agent actually reads keeps the superseded text. Once it was worse than
stale -- the port was told SE audio was "undecodable from the disc" while three
cues were located and decoding to PCM in the linked file.

For every HANDOFF line that makes a STRONG NEGATIVE claim and links to a doc,
check whether that doc contains retraction language. A hit is not proof the row
is wrong -- docs retract other things too -- it is a row to read.

    handoff_lint.py [docs/port/HANDOFF.md]
"""
import os, re, sys

HANDOFF = sys.argv[1] if len(sys.argv) > 1 else "docs/port/HANDOFF.md"
# Resolve links the way markdown does: relative to the FILE, not to a guessed
# repo root. The first version joined a guessed root and reported every existing
# doc as missing -- which is the tool failing its own control, and is why the
# "missing doc" branch prints rather than being silently skipped.
BASE = os.path.dirname(os.path.abspath(HANDOFF))

NEGATIVE = re.compile(r"undecodable|cannot be|can not be|impossible|no .{0,24}exists|"
                      r"does not exist|not extractable|unreachable", re.I)
RETRACT = re.compile(r"retract|withdraw|was too strong|that was wrong|superseded|"
                     r"refuted\b.{0,40}\bmine|no longer", re.I)
LINK = re.compile(r"\]\(\.\./re/([^)]+)\)")

def main():
    text = open(HANDOFF, encoding="utf-8").read().splitlines()
    flagged = checked = 0
    for n, line in enumerate(text, 1):
        if not NEGATIVE.search(line):
            continue
        for rel in LINK.findall(line):
            doc = os.path.normpath(os.path.join(BASE, "..", "re", rel.split("#")[0]))
            if not os.path.exists(doc):
                print(f"  L{n}: link to a MISSING doc: {rel}")
                flagged += 1
                continue
            checked += 1
            body = open(doc, encoding="utf-8").read()
            hits = sorted({m.group(0).lower() for m in RETRACT.finditer(body)})
            if hits:
                flagged += 1
                claim = NEGATIVE.search(line).group(0)
                print(f"  L{n}: claims {claim!r}; linked {rel} contains {hits}")
    print(f"\n{checked} negative claim(s) with links checked, {flagged} to read")
    return 1 if flagged else 0

if __name__ == "__main__":
    sys.exit(main())