loki-mode 9.2.0 → 9.4.0

package/tools/gate-explain.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""Turn a ci-gate verdict into the next command a human should actually run.
+
+WHY THIS EXISTS. ci-gate.py decides correctly and gate-report.py carries that
+decision to the CI run page. Both stop at WHAT happened. Neither says what to
+do about it, and the state that most needs saying is the one nobody knows how
+to act on:
+
+    cost UNEVALUABLE -- cost is UNMEASURED for /ws, no efficiency record
+    carried an observed cost or token count.
+
+An engineer reading that has a blocked merge and no next step. The observed
+response to an unactionable blocker is not to fix it, it is to route around it
+-- delete the flag, add a `|| true`, lower the ceiling until it passes. A gate
+that cannot be acted on gets disabled, and a disabled gate is worse than none
+because the workflow file still claims it runs. So this file's whole job is
+the third column: what it checked, what it found, and the CONCRETE command.
+
+    python3 tools/ci-gate.py <ws> --max-usd 5 --json \
+        | python3 tools/gate-explain.py
+
+THE RULE THAT CONSTRAINS EVERY REMEDY IN THIS FILE:
+
+    NEVER PRINT A COMMAND YOU CANNOT JUSTIFY.
+
+A remedy is a suggestion a tired operator will paste without reading, and then
+trust the result of. A guessed command is therefore worse than silence in both
+directions: it wastes the fix, and it manufactures confidence that the axis was
+addressed. So the remedy table below is keyed on the policy names ci-gate
+actually emits, every flag in it was checked against that tool's own --help,
+and an unrecognised policy prints exactly
+
+    no known remedy for this policy
+
+rather than a plausible-looking guess assembled from the policy's name.
+
+THE THREE STATES STAY THREE. This repo has paid for collapsing them on fifteen
+surfaces. PASS is "we checked and it is fine". FAIL is "we checked and it is
+not". UNEVALUABLE is "we could not check", which is neither -- so it is never
+worded as a failure (that would send an operator to fix a budget that was never
+exceeded) and never worded as a pass (that is the green-leak the whole tool
+line exists to stop). Each has its own sentence and its own remedy.
+
+WHY THE EXIT CODE IS RECONCILED, NOT RELAYED. A shell pipe keeps only the last
+command's status, so ci-gate's 2 is discarded by the `|` and this file must
+re-emit it, exactly as gate-report.py does. Relaying the header's exit_code
+alone is not enough: a body claiming exit_code 0 while carrying an UNEVALUABLE
+row would make this file PRINT "the gate could not check this" and EXIT 0 in
+the same breath -- a green-leak in the one tool whose subject is green-leaks.
+The rows are the evidence and the header is a claim, so the code is the weakest
+link over both, the same rule ci-gate applies.
+
+Empty or malformed stdin is an error with exit 2, never an empty explanation:
+nothing to explain is indistinguishable from a clean run, and an assumed pass
+on unreadable input is the same defect wearing different clothes.
+
+Exit: mirrors the reconciled input verdict (0 pass, 1 failed, 2 unevaluable);
+2 on input this file could not parse; 64 on a usage error.
+"""
+
+import argparse
+import json
+import sys
+
+sys.dont_write_bytecode = True
+
+PASS, FAIL, UNEVALUABLE = 0, 1, 2
+EXIT_USAGE = 64
+
+_EXIT = {"PASS": PASS, "FAIL": FAIL, "UNEVALUABLE": UNEVALUABLE}
+_STATE = {v: k for k, v in _EXIT.items()}
+
+# ponytail: no efficiency record reaches this file. The input is a ci-gate
+# verdict -- policy rows with prose reasons -- so record_is_measured() from
+# autonomy/lib/efficiency_cost.py has nothing here to apply itself to, and
+# importing it to look thorough would be a second cost predicate in disguise.
+# The measured/unmeasured judgement was already made upstream by cost-guard.py
+# and arrives as the row's own words, which this file relays verbatim.
+
+# WHAT EACH STATE MEANS, in one place. Worded so no state can be misread as
+# another: "could not check" never contains pass or fail language.
+_MEANING = {
+    "PASS": "the gate checked this and it passed",
+    "FAIL": "the gate checked this and it failed",
+    "UNEVALUABLE": "the gate could not check this, so it is neither a pass "
+                   "nor a failure -- the axis is unverified",
+}
+
+_NO_REMEDY = "no known remedy for this policy"
+
+# THE REMEDY TABLE. Keyed on the policy names ci-gate.py emits (grep `_run("`
+# there: "cost" and "receipt"). Every flag below was verified against that
+# tool's own --help output before being written down. Adding a row here without
+# running the command it prints is how this file starts lying.
+_REMEDY = {
+    ("cost", "FAIL"):
+        "the run cost more than the ceiling. Inspect the spend, then either "
+        "reduce it or raise the ceiling deliberately:\n"
+        "    python3 tools/cost-guard.py <workspace> --max-usd <ceiling> --json",
+    ("cost", "UNEVALUABLE"):
+        "no iteration recorded an observed cost or token count, so the budget "
+        "question has no data to answer it. Re-run the work so the provider "
+        "writes usage, then confirm a record now carries real numbers:\n"
+        "    ls <workspace>/.loki/metrics/efficiency/iteration-*.json\n"
+        "    python3 tools/cost-guard.py <workspace> --max-usd <ceiling> --json",
+    ("receipt", "FAIL"):
+        "attestation was required and did not hold. Read the attestation's own "
+        "per-axis states before changing anything:\n"
+        "    python3 tools/receipt-attest.py "
+        "<workspace>/.loki/proofs/*/proof.json --json",
+    ("receipt", "UNEVALUABLE"):
+        "the receipt exists but at least one axis could not be checked here. "
+        "The attestation names which axis and why:\n"
+        "    python3 tools/receipt-attest.py "
+        "<workspace>/.loki/proofs/*/proof.json --json",
+}
+
+_PASS_REMEDY = "nothing to do"
+
+# ci-gate's "no policy configured" verdict: an empty policies list. It is a
+# real, actionable finding, not an empty report, so it gets its own row.
+_NO_POLICY = (
+    "the gate ran with no policy configured, so it enforced nothing. A gate "
+    "that checked nothing has no pass to report. Give it at least one policy:\n"
+    "    python3 tools/ci-gate.py <workspace> --max-usd <ceiling> "
+    "--require-receipt --json")
+
+
+def _remedy(policy, state):
+    """The command for this policy, or a refusal. Never a guess."""
+    if state == "PASS":
+        return _PASS_REMEDY
+    return _REMEDY.get((policy, state), _NO_REMEDY)
+
+
+def explain_row(row):
+    """One policy row as (policy, state, found, remedy). Never defaults PASS."""
+    if not isinstance(row, dict):
+        return ("?", "UNEVALUABLE", "malformed policy entry: %r" % (row,),
+                _NO_REMEDY)
+    policy = str(row.get("policy") or "?")
+    state = row.get("state")
+    state = state.upper() if isinstance(state, str) \
+        and state.upper() in _EXIT else None
+    reason = row.get("reason")
+    found = reason.strip() if isinstance(reason, str) and reason.strip() \
+        else "no detail reported"
+    if state is None:
+        # The input carried no verdict this file recognises. Filling that gap
+        # with PASS would be manufacturing evidence.
+        return (policy, "UNEVALUABLE",
+                "the gate reported no recognised state for this policy "
+                "(was %r), so it has not been checked" % (row.get("state"),),
+                _NO_REMEDY)
+    return (policy, state, found, _remedy(policy, state))
+
+
+def explain_rows(verdict):
+    policies = verdict.get("policies")
+    rows = []
+    if isinstance(policies, list):
+        rows = [explain_row(r) for r in policies]
+    if rows:
+        return rows
+    # No policy results arrived. Whatever the header claims, nothing was
+    # checked -- so this is UNEVALUABLE unconditionally, and a top-level PASS
+    # here must not be believed.
+    return [("(none)", "UNEVALUABLE", _overall_reason(verdict), _NO_POLICY)]
+
+
+def _overall_reason(verdict):
+    reason = verdict.get("reason")
+    if isinstance(reason, str) and reason.strip():
+        return reason.strip()
+    return "the gate reported no policy results and no reason"
+
+
+def verdict_state(verdict):
+    """Weakest link over the header's claim and every row's evidence."""
+    claimed = verdict.get("state")
+    claimed = claimed.upper() if isinstance(claimed, str) \
+        and claimed.upper() in _EXIT else "UNEVALUABLE"
+    worst = max([_EXIT[claimed]] + [_EXIT[r[1]] for r in explain_rows(verdict)])
+    return _STATE[worst]
+
+
+def exit_code(verdict):
+    """The input's own exit semantics, reconciled. A pipe drops them.
+
+    A header exit_code of 0 sitting above an UNEVALUABLE row is not a pass, so
+    the code is raised to match the explanation actually printed. The number a
+    CI job branches on can never disagree with the sentences a human just read.
+    """
+    code = verdict.get("exit_code")
+    if isinstance(code, bool) or not isinstance(code, int) \
+            or code not in _STATE:
+        code = UNEVALUABLE
+    return max(code, _EXIT[verdict_state(verdict)])
+
+
+def render_text(verdict):
+    out = []
+    for policy, state, found, remedy in explain_rows(verdict):
+        out.append("POLICY: %s [%s]" % (policy, state))
+        out.append("  CHECKED: %s" % _MEANING[state])
+        out.append("  FOUND:   %s" % _one_line(found))
+        out.append("  NEXT:    %s" % _indent(remedy))
+        out.append("")
+    state = verdict_state(verdict)
+    out.append("GATE: %s -- %s" % (_headline(state), _overall_reason(verdict)))
+    return "\n".join(out)
+
+
+def render_json(verdict):
+    state = verdict_state(verdict)
+    return json.dumps({
+        "state": state,
+        "exit_code": exit_code(verdict),
+        "reason": _overall_reason(verdict),
+        "policies": [
+            {"policy": p, "state": s, "checked": _MEANING[s],
+             "found": _one_line(f), "next_command": r}
+            for p, s, f, r in explain_rows(verdict)],
+    }, indent=2)
+
+
+def _headline(state):
+    if state in ("PASS", "FAIL"):
+        return state
+    # Spelled out on the summary line too: a bare word gets skimmed, and this
+    # is the state a skimming reader most often files under "fine".
+    return "UNEVALUABLE (the gate could not check this -- not a pass)"
+
+
+def _one_line(text):
+    return " ".join(text.split())
+
+
+def _indent(text):
+    return text.replace("\n", "\n           ")
+
+
+class _Parser(argparse.ArgumentParser):
+    # argparse exits 2 on a usage error, and 2 means "could not be checked"
+    # here -- a mistyped flag would read as a blind gate. Overriding error()
+    # rather than parse_args() leaves --help exiting 0.
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        print("%s: error: %s" % (self.prog, message), file=sys.stderr)
+        raise SystemExit(EXIT_USAGE)
+
+
+def main(argv=None):
+    # No positional argument, deliberately: this reads a verdict on stdin, so a
+    # bare path on the command line is a mistake, and treating it as input
+    # would judge the wrong thing. It is rejected as a usage error.
+    ap = _Parser(
+        description="Explain a ci-gate verdict and give the next command.")
+    ap.add_argument("--json", action="store_true", dest="as_json",
+                    help="emit the explanation as JSON")
+    args = ap.parse_args(argv)
+
+    # Parse args BEFORE touching stdin, so --help and a usage error answer
+    # immediately instead of blocking on a terminal that will never send EOF.
+    raw = sys.stdin.read()
+    if not raw.strip():
+        sys.stderr.write("gate-explain: empty stdin -- expected ci-gate JSON. "
+                         "Nothing to explain is not a pass.\n")
+        return UNEVALUABLE
+    try:
+        verdict = json.loads(raw)
+    except ValueError as exc:
+        sys.stderr.write("gate-explain: could not parse the gate verdict: %s "
+                         "-- unreadable input is an error, not a pass.\n" % exc)
+        return UNEVALUABLE
+    if not isinstance(verdict, dict):
+        sys.stderr.write("gate-explain: expected a JSON object from ci-gate, "
+                         "got %s\n" % type(verdict).__name__)
+        return UNEVALUABLE
+
+    # Render fully before printing: a partial explanation reads as the whole
+    # verdict.
+    out = render_json(verdict) if args.as_json else render_text(verdict)
+    code = exit_code(verdict)
+    print(out)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())