felhom.eu/scripts/decoy_coverage_gate.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""decoy_coverage_gate.py — every registered gate ships with a decoy test (R-421).

Usage:  python3 scripts/decoy_coverage_gate.py <repo-root> [<repo-root> ...]
Exit 0 covered-or-registered · 1 a gate has neither a decoy nor an exemption · 2 inconclusive.

WHY THIS EXISTS. Four times in one week a gate turned out to be matching a NAME instead of the thing
it named — R-410 (a `mkdir` turned the release gate green), R-400 (seven debug controls answering
nothing), R-378 (a status word inside a sentence), R-419 (a phrase inside prose, including prose
saying the marker was absent). All four were found by accident. **The gates are the machinery that
enforces everything else here, and they were the one part nothing checked.** The 2026-09-01 sweep
read all 29 and fooled 16 of them.

A survey fixes what it finds once. This makes the next one impossible to add quietly: **a NEW gate
with no decoy fails immediately**, and the gates not yet covered are listed BY NAME below, each with
its row, so the remaining debt is visible and shrinking rather than forgotten in a Python literal.

R-329's shape, deliberately, because this project already trusts it: walk everything, register the
exceptions by name, and let a new one fail rather than slip through.

⚠ COVERAGE IS A DECLARATION, NOT A GREP. Each decoy suite exports `COVERS = {gate: why}` and this
gate AST-parses that literal. Searching the test file for a gate's name would be exactly the
substring-for-fact shape this whole sweep exists to find — the gate that checks for label-matching
must not itself match on a label.
"""
import ast
import io
import os
import sys

# ── EXEMPTIONS — each carries its row and one line saying why it is not covered YET ─────────────
# Dated 2026-09-01. This list is DEBT, not a settled state: R-426 owns it and names every entry.
EXEMPT = {
    # felhom.eu
    # felhom-controller: covered by controller/scripts/test_gate_decoys.py since 2026-10-06 (R-426)
    # felhom-agent and app-catalog: covered by their own scripts/test_gate_decoys.py since 2026-10-06 (R-426)
}

RUNNERS = {
    "felhom.eu": os.path.join("scripts", "repo_gates.py"),
    "felhom-controller": os.path.join("controller", "scripts", "controller_gates.py"),
    "felhom-agent": os.path.join("scripts", "agent_gates.py"),
    "app-catalog-felhom.eu": os.path.join("scripts", "catalog_gates.py"),
}
SUITES = {
    "felhom.eu": os.path.join("scripts", "test_gate_decoys.py"),
    "felhom-controller": os.path.join("controller", "scripts", "test_gate_decoys.py"),
    "felhom-agent": os.path.join("scripts", "test_gate_decoys.py"),
    "app-catalog-felhom.eu": os.path.join("scripts", "test_gate_decoys.py"),
}


def literal_from(path, name):
    """AST-parse a module-level literal assignment. Never imports — importing a test RUNS it."""
    if not os.path.isfile(path):
        return None
    try:
        tree = ast.parse(io.open(path, encoding="utf-8").read())
    except SyntaxError as e:
        return ("ERROR", "%s does not parse: %s" % (path, e))
    for node in tree.body:
        if isinstance(node, ast.Assign):
            for t in node.targets:
                if isinstance(t, ast.Name) and t.id == name:
                    try:
                        return ast.literal_eval(node.value)
                    except Exception:
                        return ("ERROR", "%s in %s is not a literal" % (name, path))
    return None


def gates_of(runner_path):
    """The GATES table's LABELS, AST-read — the runner is never imported and never literal_eval'd.

    Only the label is taken, deliberately. Three of the four runners build their script paths with
    `os.path.join(...)`, so the table as a whole is not a literal — but every label is a plain string
    constant, which is all this gate needs. Evaluating the whole row would make this gate fail on
    three repos for a reason that has nothing to do with coverage.
    """
    if not os.path.isfile(runner_path):
        return None
    try:
        tree = ast.parse(io.open(runner_path, encoding="utf-8").read())
    except SyntaxError:
        return None
    for node in tree.body:
        if not isinstance(node, ast.Assign):
            continue
        if not any(isinstance(t, ast.Name) and t.id == "GATES" for t in node.targets):
            continue
        if not isinstance(node.value, (ast.List, ast.Tuple)):
            return None
        out = []
        for row in node.value.elts:
            if isinstance(row, (ast.Tuple, ast.List)) and row.elts:
                first = row.elts[0]
                if isinstance(first, ast.Constant) and isinstance(first.value, str):
                    out.append(first.value)
        return out
    return None


def main(argv):
    roots = argv[1:] or ["."]
    problems, inconclusive, lines = [], [], []
    total = covered = exempt = 0
    stale = []

    for root in roots:
        root = os.path.abspath(root)
        # ⚠ IDENTIFY THE REPO BY ITS RUNNER, NOT BY ITS DIRECTORY NAME.
        #
        # This gate asked `os.path.basename(root)` and looked the answer up in RUNNERS — a NAME
        # standing in for a FACT, which is the exact class this gate was written to catch. It went
        # INCONCLUSIVE on its first CI run because Gitea's act-runner checks the repo out into a
        # directory called `hostexecutor`. **The gate that hunts label-matching was matching a
        # label.** Measured 2026-09-01, CI job 490. Now: whichever registered runner FILE actually
        # exists under this root is what the repo is.
        name, runner = None, None
        for cand, rel in RUNNERS.items():
            if os.path.isfile(os.path.join(root, rel)):
                name, runner = cand, os.path.join(root, rel)
                break
        if name is None:
            inconclusive.append("no known gate runner found under %s — tried %s"
                                % (root, ", ".join(sorted(RUNNERS.values()))))
            continue
        labels = gates_of(runner)
        if labels is None:
            inconclusive.append("%s: could not read the GATES table from %s" % (name, runner))
            continue
        covers = literal_from(os.path.join(root, SUITES[name]), "COVERS") or {}
        if isinstance(covers, tuple):
            inconclusive.append("%s: %s" % (name, covers[1]))
            covers = {}

        for label in labels:
            total += 1
            if label in covers:
                covered += 1
                lines.append("  COVERED   %-22s %-20s %s" % (name, label, covers[label][:60]))
                # R-426 (2026-10-06): an exemption for a gate that HAS a decoy is a dead entry that keeps
                # the debt list longer than the debt (controller/offbox-rename sat here after R-425 gave it
                # decoys). Named, not convicted: the decoy lands in a sibling repo, and failing THIS repo's
                # push for another repo's good news would couple the two for no safety gain.
                if (name, label) in EXEMPT:
                    stale.append((name, label))
            elif (name, label) in EXEMPT:
                exempt += 1
                lines.append("  exempt    %-22s %-20s %s" % (name, label, EXEMPT[(name, label)][:60]))
            else:
                problems.append((name, label))

    print("decoy-coverage gate — %d registered gate(s): %d with a decoy, %d registered exempt, "
          "%d UNACCOUNTED" % (total, covered, exempt, len(problems)))
    for l in sorted(lines):
        print(l)

    if stale:
        print()
        for repo, label in stale:
            print("  STALE EXEMPTION: %s / %s has a decoy now — delete its EXEMPT entry (R-426)" % (repo, label))

    if inconclusive:
        print()
        for i in inconclusive:
            print("  INCONCLUSIVE: %s" % i)
        if not problems:
            print("\ndecoy-coverage gate INCONCLUSIVE — an undetermined result is never a pass")
            return 2

    if problems:
        print()
        print("CONVICTED — these gates have neither a decoy test nor a registered exemption:")
        for repo, label in problems:
            print("   %s / %s" % (repo, label))
        print()
        print("A gate ships with a decoy test that has been SEEN TO FAIL. Construct the label")
        print("without the fact, run the gate, and assert it convicts — then name the gate in that")
        print("repo's scripts/test_gate_decoys.py COVERS map.")
        print("If no plausible decoy exists, say so: add it to EXEMPT here with a row number and one")
        print("line of reason. An honest exemption is a result; a silent gap is how R-410 happened.")
        return 1

    print("\ndecoy-coverage gate OK — every registered gate has a decoy or a named exemption (R-426)")
    return 0


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