@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/check_finding_dispositions.ts

@@ -24,8 +24,49 @@
  *       self_review_gate --findings-out) into the ledger with an empty
  *       disposition, so validation is red until a human fills it.
  *
- * Exit codes: 0 complete · 1 missing/incomplete dispositions · 2 usage or
- * schema error. Deliberately NOT fail-open: this script never calls a model;
+ * ABSENCE IS NOT EVIDENCE OF ZERO. An absent ledger used to exit 0 for any
+ * version, so a RELEASED version whose findings were never ingested read as
+ * "no findings" — the failure this paragraph exists to stop. When the ledger
+ * file is missing the gate now asks whether the version has SHIPPED:
+ *
+ *   released        a tag for the version exists locally, or the remote says
+ *                   the release exists  ->  an absent ledger is a FAILURE (1)
+ *   unreleased      the local tag list is COMPLETE and lacks it, or the remote
+ *                   says so  ->  normal in-flight state, absent ledger is fine
+ *   undeterminable  the tag list cannot settle it and no remote answered  ->
+ *                   exit 2. Refusing beats passing: a silent green here is the
+ *                   very inversion this split exists to remove
+ *
+ * THE SOURCE IS THE TAG / RELEASE, AND DELIBERATELY NOT `CHANGELOG.md`. The
+ * changelog heading is written by the release PR itself — gh pr diff 1836 shows
+ * "+## [14.16.0](...)" inside the release commit — so on branch release/X the
+ * changelog claims X is released before X exists. Reading it would redden every
+ * in-flight release branch over a file nobody could yet have written, which is
+ * the exact behaviour this split is here to preserve. The tag is created at
+ * publish, after merge, so it cannot make that mistake.
+ *
+ * A local tag MISS is not authoritative on its own: actions/checkout fetches
+ * depth 1 and no tags by default, and the one workflow that runs this gate does
+ * not override either, so in CI the local tag list is EMPTY. See releaseStatus
+ * for the asymmetry and the remote fallback.
+ *
+ * AN EMPTY LEDGER MUST SAY WHY IT IS EMPTY. The released/unreleased split above
+ * closed the missing-file half; it left the other half open, because
+ * `findings: []` still passed while asserting nothing. A writer could satisfy
+ * the gate by creating an empty file, which is the same silence wearing the
+ * shape of a record. `no_findings_reason` is now required whenever the file
+ * exists and the array is empty — see empty_ledger_problem for what the reason
+ * has to distinguish.
+ *
+ * A future reader changing allowEmpty below is the person this is addressed to:
+ * the EMPTY_VALID waiver now covers only an EXPLAINED empty ledger and an
+ * unreleased version. It covers neither a released version with no ledger nor an
+ * empty ledger with no reason.
+ *
+ * Exit codes: 0 complete · 1 missing/incomplete dispositions (an absent ledger
+ * for a RELEASED version and an unexplained empty ledger are both among them) ·
+ * 2 usage error, schema error, or an
+ * undeterminable release status. Deliberately NOT fail-open: this script never calls a model;
  * a broken ledger file is a hard error, not a neutral skip.
  */
 import { spawnSync } from 'node:child_process';
@@ -34,7 +75,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -60,6 +101,8 @@ export interface Ledger {
     schema_version: number;
     release: string;
     findings: LedgerFinding[];
+    /** Why the finding set is empty. Required when it is; see empty_ledger_problem. */
+    no_findings_reason?: string;
 }
 
 /** Mirrors self_review_gate.classifyBlocking — security/claim × critical/high. */
@@ -105,6 +148,154 @@ export function missing_dispositions(findings: readonly LedgerFinding[]): string
     return problems;
 }
 
+/**
+ * An empty finding set must say why it is empty.
+ *
+ * `findings: []` and a missing file made the same claim to every reader — "nothing
+ * to disposition" — and only one of them is evidence. Worse, they collapse two
+ * states that differ entirely: a review that ran and reported nothing, and a review
+ * that never ran at all. The reason field is what forces the writer to pick one and
+ * makes the pick falsifiable, so a fabricated empty ledger has to assert something
+ * a reader can check rather than merely occupy the path the gate looks at.
+ *
+ * Applies ONLY to a ledger file that exists. An absent ledger on an unreleased
+ * version is the normal in-flight state and has nothing to carry a reason.
+ */
+export function empty_ledger_problem(
+    ledger: Pick<Ledger, 'findings' | 'no_findings_reason'>,
+): string | null {
+    if (ledger.findings.length > 0) {
+        return null;
+    }
+    if ((ledger.no_findings_reason ?? '').trim() !== '') {
+        return null;
+    }
+    return (
+        'the ledger exists with an empty `findings` array and no `no_findings_reason`. '
+        + 'An unexplained empty ledger is indistinguishable from an absent one — state '
+        + 'whether the review ran and reported nothing, or did not run, and how a reader '
+        + 'can check that.'
+    );
+}
+
+export type ReleaseStatus = 'released' | 'unreleased' | 'undeterminable';
+export type RemoteReleaseAnswer = 'released' | 'unreleased' | 'unavailable';
+
+/**
+ * Pure core of the released-vs-unreleased discriminator. Every signal is
+ * INJECTED, so both directions AND the degradation are testable offline. A
+ * red-only test cannot catch the day this starts answering 'unreleased' for
+ * everything, which silently restores the fail-open it exists to replace.
+ *
+ * The asymmetry is the design, and it is the council correction to a first
+ * implementation that read local tags only:
+ *
+ *   a local tag HIT  is authoritative      — the tag exists, the version shipped
+ *   a local tag MISS is NOT authoritative  — unless the tag list is COMPLETE
+ *
+ * A miss means "not in THIS checkout", which is not "never shipped".
+ * tagsComplete is the condition under which a miss IS authoritative: the
+ * repository is not shallow and carries at least one tag. That keeps a normal
+ * full clone offline and deterministic; only an incomplete checkout pays for a
+ * remote lookup.
+ */
+export function releaseStatus(signals: {
+    localTagHit: boolean;
+    tagsComplete: boolean;
+    remote: RemoteReleaseAnswer;
+}): ReleaseStatus {
+    if (signals.localTagHit) {
+        return 'released';
+    }
+    if (signals.tagsComplete) {
+        return 'unreleased';
+    }
+    if (signals.remote === 'released') {
+        return 'released';
+    }
+    if (signals.remote === 'unreleased') {
+        return 'unreleased';
+    }
+    return 'undeterminable';
+}
+
+/** Tag equality, tolerating this repo bare tags and a v prefix. */
+export function localTagHit(release: string, tags: readonly string[]): boolean {
+    const v = release.trim();
+    if (!v) {
+        return false;
+    }
+    return tags.some((t) => {
+        const tt = t.trim();
+        return tt === v || tt === `v${v}`;
+    });
+}
+
+function _git(args: readonly string[]): { ok: boolean; out: string } {
+    const r = spawnSync('git', args as string[], {
+        encoding: 'utf-8',
+        cwd: REPO_ROOT,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
+}
+
+/** This repository tags. A git failure is an empty list, i.e. not complete. */
+export function git_tags(): string[] {
+    const r = _git(['tag', '--list']);
+    return r.ok ? r.out.split('\n').map((l) => l.trim()).filter(Boolean) : [];
+}
+
+/** True when a local tag MISS may be trusted: full clone, and tags present. */
+export function tags_complete(tags: readonly string[]): boolean {
+    if (tags.length === 0) {
+        return false;
+    }
+    const r = _git(['rev-parse', '--is-shallow-repository']);
+    return r.ok && r.out === 'false';
+}
+
+/**
+ * Remote answer, used ONLY when the local tag list cannot settle it. gh first —
+ * this repo publishes tag and GitHub Release together, the Release object is
+ * publication-specific rather than a bare ref push, and --pr mode already shells
+ * out to gh. git ls-remote is the fallback when gh is absent.
+ */
+export function remote_release_status(release: string): RemoteReleaseAnswer {
+    const gh = spawnSync('gh', ['release', 'view', release, '--json', 'tagName'], {
+        encoding: 'utf-8',
+        cwd: REPO_ROOT,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    if (gh.status === 0) {
+        return 'released';
+    }
+    if (gh.status !== null && /release not found|could not find|not found/i.test(gh.stderr ?? '')) {
+        return 'unreleased';
+    }
+    const ls = spawnSync(
+        'git',
+        ['ls-remote', '--tags', 'origin', `refs/tags/${release}`, `refs/tags/v${release}`],
+        { encoding: 'utf-8', cwd: REPO_ROOT, maxBuffer: 8 * 1024 * 1024 },
+    );
+    if (ls.status === 0) {
+        return (ls.stdout ?? '').trim() ? 'released' : 'unreleased';
+    }
+    return 'unavailable';
+}
+
+/** Resolve every signal and decide. Called only when the ledger file is absent. */
+export function resolve_release_status(release: string): ReleaseStatus {
+    const tags = git_tags();
+    const hit = localTagHit(release, tags);
+    const complete = tags_complete(tags);
+    return releaseStatus({
+        localTagHit: hit,
+        tagsComplete: complete,
+        remote: hit || complete ? 'unavailable' : remote_release_status(release),
+    });
+}
+
 /** Findings the gate comment reported but the ledger never ingested. */
 export function unrecorded_findings(
     reported: ReadonlyArray<Pick<LedgerFinding, 'finding_id' | 'severity' | 'kind' | 'title'>>,
@@ -227,6 +418,30 @@ function main(argv: readonly string[]): number {
         return 0;
     }
 
+    if (!fs.existsSync(ledgerPath)) {
+        const status = resolve_release_status(release);
+        if (status === 'released') {
+            process.stderr.write(
+                `❌  ${release} has shipped and carries no findings ledger at `
+                    + `${path.relative(REPO_ROOT, ledgerPath)}.\n`
+                    + '    Absence is not evidence of zero — the release PR\'s self-review may have\n'
+                    + '    reported findings that were never ingested. Recover the machine block and:\n'
+                    + `    ./scripts-run src/scripts/check_finding_dispositions --ingest <findings.json> --release ${release}\n`,
+            );
+            return 1;
+        }
+        if (status === 'undeterminable') {
+            process.stderr.write(
+                `❌  cannot determine whether ${release} has shipped: this checkout tag list is`
+                    + ' incomplete (shallow or tagless) and no remote answered.\n'
+                    + '    Refusing to pass on an absent ledger without knowing — that silent green is\n'
+                    + '    the defect this check replaces. Fetch tags (actions/checkout fetch-tags: true)\n'
+                    + '    or make the gh CLI available.\n',
+            );
+            return 2;
+        }
+    }
+
     let ledger: Ledger = { schema_version: 1, release, findings: [] };
     if (fs.existsSync(ledgerPath)) {
         try {
@@ -237,6 +452,19 @@ function main(argv: readonly string[]): number {
         }
     }
 
+    // An existing ledger that records nothing must say why. Checked here rather
+    // than in the schema because the requirement is conditional on the finding
+    // count, which the repo's Draft-07 subset validator cannot express.
+    if (fs.existsSync(ledgerPath)) {
+        const emptyProblem = empty_ledger_problem(ledger);
+        if (emptyProblem !== null) {
+            process.stderr.write(
+                `❌  ${path.relative(REPO_ROOT, ledgerPath)}: ${emptyProblem}\n`,
+            );
+            return 1;
+        }
+    }
+
     // Scope declaration, not a scope guard. The ledger is written per release by
     // `--ingest`, so "no <release>.json" is the normal state of a release whose
     // self-review reported nothing — the gate's own success line says so. That
@@ -245,7 +473,7 @@ function main(argv: readonly string[]): number {
     // durable trigger for an un-ingested finding is `--pr` mode, which compares
     // the ledger against what the self-review actually reported.
     try {
-        assertScanned({
+        reportScanned({
             gate: 'check_finding_dispositions',
             scanned: ledger.findings.length,
             units: 'recorded finding(s)',
@@ -253,8 +481,13 @@ function main(argv: readonly string[]): number {
             allowEmpty:
                 'EMPTY_VALID: zero recorded findings IS the pass state for a release whose '
                 + 'self-review reported none — the ledger file is created on first --ingest, so a '
-                + 'clean release legitimately has no <version>.json. Un-ingested findings are '
-                + 'caught by --pr (unrecorded_findings), never by this count.',
+                + 'clean release legitimately has no <version>.json. NARROWED TWICE: it no longer '
+                + 'covers a RELEASED version with no ledger, which returns 1 above on the '
+                + 'released/unreleased split, and it no longer covers an empty ledger that does '
+                + 'not say why it is empty, which returns 1 above via empty_ledger_problem. What '
+                + 'remains is an EXPLAINED empty ledger and an unreleased version. Un-ingested '
+                + 'findings on an in-flight release are caught by --pr (unrecorded_findings), '
+                + 'never by this count.',
         });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {

package/src/scripts/check_gate_coverage.ts

@@ -113,6 +113,21 @@ export interface GateSpec {
    * `pending` is reported instead of hidden.
    */
   unavailable_exit?: number;
+  /**
+   * Repo-relative workflow file this row's `argv` is pinned to.
+   *
+   * Rule 2 of this manifest — CI-IDENTICAL INVOCATION — was an instruction to
+   * the author and nothing else: the guard runs whatever `argv` says and never
+   * looked at how CI calls the gate, so a row could drift from its workflow, or
+   * the workflow step could be deleted outright, and this file would keep
+   * reporting healthy coverage for a gate CI no longer runs.
+   *
+   * Opt-in per row, because most gates here have several CI invocations with
+   * different arguments and one `argv` cannot be identical to all of them. Where
+   * a row DOES name a workflow, that workflow must contain an invocation of the
+   * gate whose argument list equals `argv` exactly.
+   */
+  ci_invocation?: string;
   note?: string;
 }
 
@@ -191,6 +206,9 @@ export function load_manifest(file = MANIFEST): GateSpec[] {
       ...(e['unavailable_exit'] === undefined
         ? {}
         : { unavailable_exit: _require_int(e['unavailable_exit'], id, i) }),
+      ...(e['ci_invocation'] === undefined
+        ? {}
+        : { ci_invocation: _require_str(e['ci_invocation'], 'ci_invocation', id, i) }),
       ...(e['note'] === undefined ? {} : { note: String(e['note']) }),
       ...(e['canary'] === undefined ? {} : { canary: _require_canary(e['canary'], id, i) }),
       ...(e['no_canary_reason'] === undefined
@@ -405,6 +423,73 @@ function report_negative_control_inventory(specs: readonly GateSpec[]): void {
   }
 }
 
+/**
+ * Invocations of `src/scripts/<id>` in a workflow, each as its argument list.
+ *
+ * Deliberately a text scan rather than a YAML walk: an invocation lives inside a
+ * `run:` block scalar, so parsing the workflow buys nothing and costs the ability
+ * to see a call split across a line continuation, which is how the release job
+ * writes this very gate. Backslash-newline joins are folded before matching for
+ * that reason.
+ */
+export function ci_invocations(workflowText: string, id: string): string[][] {
+  const folded = workflowText.replace(/\\\n\s*/gu, ' ');
+  const out: string[][] = [];
+  const re = new RegExp(String.raw`src/scripts/${id}(?![A-Za-z0-9_])([^\n]*)`, 'gu');
+  for (const m of folded.matchAll(re)) {
+    out.push(
+      (m[1] ?? '')
+        .trim()
+        .split(/\s+/u)
+        .filter((t) => t !== ''),
+    );
+  }
+  return out;
+}
+
+/**
+ * The row's `argv` must be reproducible from the workflow it pins.
+ *
+ * Both directions are failures and they are different defects: no matching
+ * invocation means the manifest probes the gate in a way CI does not (or CI
+ * stopped calling it at all), which is the drift rule 2 asks for and nothing
+ * enforced.
+ */
+export function ci_invocation_problem(
+  workflowText: string,
+  id: string,
+  argv: readonly string[],
+): string | null {
+  const found = ci_invocations(workflowText, id);
+  if (found.length === 0) {
+    return `no invocation of src/scripts/${id} — the workflow does not call this gate`;
+  }
+  const want = argv.join(' ');
+  if (found.some((a) => a.join(' ') === want)) {
+    return null;
+  }
+  return (
+    `argv [${want}] matches no invocation there; the workflow calls it as ` +
+    found.map((a) => `[${a.join(' ')}]`).join(', ')
+  );
+}
+
+/** Rows whose `ci_invocation` no longer describes their workflow. */
+export function ci_invocation_drift(specs: readonly GateSpec[], repoRoot = REPO_ROOT): string[] {
+  const problems: string[] = [];
+  for (const s of specs) {
+    if (s.ci_invocation === undefined) continue;
+    const file = path.join(repoRoot, s.ci_invocation);
+    if (!fs.existsSync(file)) {
+      problems.push(`${s.id}: ci_invocation ${s.ci_invocation} does not exist`);
+      continue;
+    }
+    const problem = ci_invocation_problem(fs.readFileSync(file, 'utf-8'), s.id, s.argv);
+    if (problem !== null) problems.push(`${s.id}: ${s.ci_invocation} — ${problem}`);
+  }
+  return problems;
+}
+
 export function main(argv: readonly string[]): number {
   const wantJson = argv.includes('--format') && argv[argv.indexOf('--format') + 1] === 'json';
   const listOnly = argv.includes('--list');
@@ -523,12 +608,23 @@ export function main(argv: readonly string[]): number {
     );
   }
   report_negative_control_inventory(specs);
+  const drift = ci_invocation_drift(specs);
+  for (const d of drift) {
+    process.stdout.write(`  ❌ ${d}\n`);
+  }
   const hardening = report_hardening_ratchet();
   const selfTest = report_self_test_ratchet();
   if (failed.length > 0) {
     process.stdout.write(`❌  ${String(failed.length)} gate(s) failed the coverage floor.\n`);
     return 1;
   }
+  if (drift.length > 0) {
+    process.stdout.write(
+      `❌  ${String(drift.length)} row(s) declare a ci_invocation their workflow no longer matches — ` +
+        `the manifest probes the gate differently from CI, or CI stopped calling it.\n`,
+    );
+    return 1;
+  }
   if (hardening !== 0) {
     return hardening;
   }