@event4u/agent-config 14.17.0 → 14.18.0

package/src/scripts/_lib/tamper_vocabulary.ts

@@ -0,0 +1,242 @@
+/**
+ * The closed vocabulary the verification-tampering detector speaks.
+ *
+ * Declared in its own module, and declared BEFORE the detector, because the
+ * roadmap step that asks for it (`road-to-deterministic-defect-detectors` 1.1)
+ * asks for exactly that ordering: a detector that invents its ids while it is
+ * being written ends up with the ids its implementation found easy, not the
+ * ids the failure classes need. Every id below has a fixture in
+ * `tests/fixtures/tamper-corpus/`, committed one commit earlier.
+ *
+ * WHY THE OUTCOME TYPE EXTENDS `GateOutcome` INSTEAD OF REPLACING IT.
+ *
+ * `_lib/gate_result.ts` already separates "the check ran and found something"
+ * (`violations`) from "the check could not run" (`crashed`) from "the
+ * measurement is void" (`estate_invalid`). That distinction is the one a tamper
+ * detector most needs — a detector that crashed reporting `clean` is precisely
+ * the phantom green it exists to catch — so it is reused verbatim rather than
+ * re-spelled.
+ *
+ * Exactly ONE member is added, and only because `GateOutcome` cannot express
+ * it: `stale_verdict`. A runner that exited 0 before the last edit produces a
+ * green exit code over a tree that no longer exists. `clean` would launder it;
+ * `violations` would claim a finding nobody made; `crashed` would claim the
+ * runner failed when it succeeded — at the wrong time. The state is "it ran,
+ * it passed, and it is not evidence", and none of the four existing members
+ * says that. Adding a fifth member is a smaller change than a second
+ * vocabulary, which is what 1.1 forbids.
+ *
+ * SEVERITY, AND THE ONE CONTESTED CALL.
+ *
+ * Six ids are `block`. `verification-skipped` is `warn`, and that is not a
+ * confidence statement about the detection — an added `it.skip` is as
+ * mechanically certain as an added `.only`. It is a statement about the
+ * ACT: the source this roadmap came from is split on whether adding a skip
+ * on the way to green is tampering or triage, and this repository does not
+ * promote a class to blocking on a split. It ships `warn` with the corpus as
+ * the evidence a later promotion would need.
+ *
+ * THE ESCAPE HATCH IS SCOPED TO ONE ID, DELIBERATELY.
+ *
+ * A blanket `tamper-allow` in a commit message would suppress every detector at
+ * once, which turns one honest exception into a general amnesty. The grammar
+ * therefore names the id: `tamper-allow: <detector-id> — <reason>`. The reason
+ * floor mirrors `check_gate_completeness.MIN_REASON_CHARS` (20) and exists for
+ * the same reason stated there — it rejects `n/a`, and it cannot judge whether
+ * a reason is true, which stays a human read.
+ */
+import type { GateOutcome } from './gate_result.js';
+
+/** Every tampering class the detector can name. Closed set. */
+export type TamperDetectorId =
+    | 'assertion-removed'
+    | 'assertion-weakened'
+    | 'verification-skipped'
+    | 'expectation-rewritten'
+    | 'early-exit-injected'
+    | 'test-file-deleted'
+    | 'subject-mocked-away';
+
+export type TamperSeverity = 'block' | 'warn';
+
+export interface TamperDetectorSpec {
+    id: TamperDetectorId;
+    severity: TamperSeverity;
+    /** What shape in the diff fires this id. */
+    what: string;
+    /** Why that shape is a weakened verification rather than ordinary work. */
+    why: string;
+}
+
+export const TAMPER_DETECTORS: readonly TamperDetectorSpec[] = [
+    {
+        id: 'assertion-removed',
+        severity: 'block',
+        what: 'a removed assertion line with no assertion added in the same hunk',
+        why: 'the check that could fail is gone; what remains passes for a wider set of outputs',
+    },
+    {
+        id: 'assertion-weakened',
+        severity: 'block',
+        what: 'a removed assertion replaced in the same hunk by one lower on the strength ladder',
+        why: 'an exact-value check became an existence check, which passes for the broken output too',
+    },
+    {
+        id: 'verification-skipped',
+        severity: 'warn',
+        what: 'an added skip / xfail / only / ignore marker on a test',
+        why: 'the assertion survives the diff and stops running, which is the same thing at verdict time',
+    },
+    {
+        id: 'expectation-rewritten',
+        severity: 'block',
+        what: 'the same assertion call on both sides of a hunk with a different literal expected value',
+        why: 'the expectation moved onto whatever the code now emits, so the test can no longer disagree with it',
+    },
+    {
+        id: 'early-exit-injected',
+        severity: 'block',
+        what: 'an added unconditional return or exit above surviving assertions in a test body',
+        why: 'the test reports green having executed none of the verification below it',
+    },
+    {
+        id: 'test-file-deleted',
+        severity: 'block',
+        what: 'a test file deleted outright by the diff',
+        why: 'the fastest route to a green suite is the one that verifies nothing',
+    },
+    {
+        id: 'subject-mocked-away',
+        severity: 'block',
+        what: 'an added mock or stub whose target also appears on a removed line of the same file',
+        why: 'the function under test is replaced by a stub, so the test now asserts against its own fixture',
+    },
+] as const;
+
+/** Ids in declaration order — the canonical listing order for output. */
+export const TAMPER_DETECTOR_IDS: readonly TamperDetectorId[] = TAMPER_DETECTORS.map((d) => d.id);
+
+const BY_ID = new Map<string, TamperDetectorSpec>(TAMPER_DETECTORS.map((d) => [d.id, d]));
+
+/** True when `id` is a member of the closed set. */
+export function isTamperDetectorId(id: string): id is TamperDetectorId {
+    return BY_ID.has(id);
+}
+
+export function detectorSpec(id: TamperDetectorId): TamperDetectorSpec {
+    const spec = BY_ID.get(id);
+    /* c8 ignore next 3 -- unreachable while the map is built from the same array */
+    if (spec === undefined) {
+        throw new Error(`unknown tamper detector id: ${id}`);
+    }
+    return spec;
+}
+
+/**
+ * The loop's outcome vocabulary: `GateOutcome` plus the one state it cannot say.
+ *
+ * See the module header for why this is an extension of four members rather
+ * than a parallel set of five.
+ */
+export type LoopOutcome = GateOutcome | 'stale_verdict';
+
+/**
+ * One finding. `file` and `line` are mandatory and are checked at runtime by
+ * {@link assertWellFormed} — a finding without a location is a claim a reader
+ * cannot check, which is the shape of report this tree already refuses.
+ */
+export interface TamperFinding {
+    id: TamperDetectorId;
+    severity: TamperSeverity;
+    /** Repo-relative path as it appears in the diff header. */
+    file: string;
+    /** 1-based line number in the side of the diff the evidence lives on. */
+    line: number;
+    /** Which side `line` indexes — a removal has no post-image line. */
+    side: 'added' | 'removed';
+    /** The offending line, trimmed. Never empty. */
+    evidence: string;
+}
+
+/**
+ * Reject a finding that cannot be located.
+ *
+ * Deliberately a throw and not a filter: a detector that silently drops its own
+ * malformed findings under-reports, and under-reporting is the failure mode the
+ * whole detector exists to close.
+ */
+export function assertWellFormed(finding: TamperFinding): TamperFinding {
+    if (finding.file.trim() === '') {
+        throw new Error(`tamper finding ${finding.id} carries no file`);
+    }
+    if (!Number.isInteger(finding.line) || finding.line < 1) {
+        throw new Error(
+            `tamper finding ${finding.id} in ${finding.file} carries no usable line ` +
+                `(got ${String(finding.line)}); every finding must be locatable as file:line`,
+        );
+    }
+    if (finding.evidence.trim() === '') {
+        throw new Error(`tamper finding ${finding.id} at ${finding.file}:${String(finding.line)} carries no evidence text`);
+    }
+    return finding;
+}
+
+/** `path/to/file.ts:12` — the one location format the detector prints. */
+export function locate(finding: TamperFinding): string {
+    return `${finding.file}:${String(finding.line)}`;
+}
+
+/**
+ * Grammar of the scoped escape hatch, read from a commit message.
+ *
+ * Both an em dash and a plain hyphen are accepted as the separator: the
+ * repository writes em dashes in prose, and a contributor typing this into
+ * `git commit` will reach for `-`. Rejecting the hyphen would make the hatch
+ * fail in the direction that hides a legitimate change.
+ */
+export const TAMPER_ALLOW_RE = /^\s*tamper-allow:\s*([a-z-]+)\s*(?:—|--|-)\s*(.+)$/gim;
+
+/** Mirrors `check_gate_completeness.MIN_REASON_CHARS` — rejects `n/a`, judges nothing. */
+export const MIN_ALLOW_REASON_CHARS = 20;
+
+export interface AllowDeclaration {
+    id: TamperDetectorId;
+    reason: string;
+}
+
+export interface AllowParse {
+    allowed: Set<TamperDetectorId>;
+    /** Declarations that named an unknown id or gave too short a reason. */
+    malformed: string[];
+}
+
+/**
+ * Parse every `tamper-allow:` line out of a commit message.
+ *
+ * A malformed declaration does NOT suppress anything and is reported instead:
+ * a typo'd id that silently allowed nothing would read to its author as an
+ * accepted exception, and a typo'd id that silently allowed everything would be
+ * the amnesty this grammar exists to prevent.
+ */
+export function parseAllowDeclarations(message: string): AllowParse {
+    const allowed = new Set<TamperDetectorId>();
+    const malformed: string[] = [];
+    TAMPER_ALLOW_RE.lastIndex = 0;
+    for (const match of message.matchAll(TAMPER_ALLOW_RE)) {
+        const rawId = (match[1] ?? '').trim();
+        const reason = (match[2] ?? '').trim();
+        if (!isTamperDetectorId(rawId)) {
+            malformed.push(`tamper-allow names an unknown detector id: "${rawId}"`);
+            continue;
+        }
+        if (reason.length < MIN_ALLOW_REASON_CHARS) {
+            malformed.push(
+                `tamper-allow for "${rawId}" gives a ${String(reason.length)}-character reason; ` +
+                    `at least ${String(MIN_ALLOW_REASON_CHARS)} are required`,
+            );
+            continue;
+        }
+        allowed.add(rawId);
+    }
+    return { allowed, malformed };
+}

package/src/scripts/_lib/unified_diff.ts

@@ -0,0 +1,121 @@
+/**
+ * A minimal unified-diff reader.
+ *
+ * Written rather than pulled in: nothing in `src/scripts/_lib/` parses a diff
+ * (`grep -rl "diff --git" src/scripts/_lib/*.ts` returns nothing), and the two
+ * consumers here need three facts a full patch library would surround with
+ * fifty more — which side a line is on, what line number it lands on, and
+ * whether the file was deleted outright.
+ *
+ * Deliberately tolerant in one direction only: an unparseable line is skipped
+ * rather than thrown on, because a diff carrying an unexpected header must not
+ * make the detector crash into a green. Deliberately strict in the other: a
+ * hunk header that does not parse aborts the file, because line numbers that
+ * are wrong are worse than absent — every finding this feeds is a `file:line`
+ * claim a reader will try to open.
+ */
+
+export interface DiffLine {
+    side: 'added' | 'removed' | 'context';
+    /** 1-based line number on the side this line belongs to. */
+    line: number;
+    /** Line content with the leading +/-/space removed. */
+    text: string;
+}
+
+export interface DiffHunk {
+    header: string;
+    lines: DiffLine[];
+}
+
+export interface DiffFile {
+    /** Path as it appears after `b/`, or after `a/` for a deleted file. */
+    path: string;
+    /** True when the diff removes the file outright. */
+    deleted: boolean;
+    /** True when the diff creates the file. */
+    added: boolean;
+    hunks: DiffHunk[];
+}
+
+const HUNK_RE = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const GIT_HEADER_RE = /^diff --git a\/(.+?) b\/(.+)$/;
+
+/** Parse a unified diff into files and hunks. Never throws on content. */
+export function parseUnifiedDiff(text: string): DiffFile[] {
+    const files: DiffFile[] = [];
+    let current: DiffFile | null = null;
+    let hunk: DiffHunk | null = null;
+    let oldNo = 0;
+    let newNo = 0;
+
+    for (const raw of text.split('\n')) {
+        const gitHeader = GIT_HEADER_RE.exec(raw);
+        if (gitHeader !== null) {
+            current = { path: gitHeader[2] ?? '', deleted: false, added: false, hunks: [] };
+            files.push(current);
+            hunk = null;
+            continue;
+        }
+        if (current === null) continue;
+
+        if (raw.startsWith('deleted file mode')) {
+            current.deleted = true;
+            continue;
+        }
+        if (raw.startsWith('new file mode')) {
+            current.added = true;
+            continue;
+        }
+        if (raw.startsWith('+++ ')) {
+            // `+++ /dev/null` is the other spelling of a deletion; some
+            // producers emit it without the `deleted file mode` line.
+            if (raw.slice(4).trim() === '/dev/null') current.deleted = true;
+            continue;
+        }
+        if (raw.startsWith('--- ')) {
+            if (raw.slice(4).trim() === '/dev/null') current.added = true;
+            continue;
+        }
+        if (raw.startsWith('index ') || raw.startsWith('similarity index') || raw.startsWith('rename ')) {
+            continue;
+        }
+
+        const hunkHeader = HUNK_RE.exec(raw);
+        if (hunkHeader !== null) {
+            oldNo = Number(hunkHeader[1]);
+            newNo = Number(hunkHeader[3]);
+            hunk = { header: raw, lines: [] };
+            current.hunks.push(hunk);
+            continue;
+        }
+        if (hunk === null) continue;
+
+        if (raw.startsWith('+')) {
+            hunk.lines.push({ side: 'added', line: newNo, text: raw.slice(1) });
+            newNo += 1;
+        } else if (raw.startsWith('-')) {
+            hunk.lines.push({ side: 'removed', line: oldNo, text: raw.slice(1) });
+            oldNo += 1;
+        } else if (raw.startsWith(' ') || raw === '') {
+            hunk.lines.push({ side: 'context', line: newNo, text: raw.slice(1) });
+            oldNo += 1;
+            newNo += 1;
+        }
+        // `` and anything else: skipped on purpose.
+    }
+    return files;
+}
+
+/** Every added line across the whole diff, with its file. */
+export function addedLines(files: readonly DiffFile[]): Array<{ file: DiffFile; line: DiffLine }> {
+    const out: Array<{ file: DiffFile; line: DiffLine }> = [];
+    for (const file of files) {
+        for (const h of file.hunks) {
+            for (const l of h.lines) {
+                if (l.side === 'added') out.push({ file, line: l });
+            }
+        }
+    }
+    return out;
+}

package/src/scripts/check_finding_dispositions.ts

@@ -24,8 +24,39 @@
  *       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.
+ *
+ * A future reader changing allowEmpty below is the person this is addressed to:
+ * the EMPTY_VALID waiver still covers a ledger that exists and is empty, and an
+ * unreleased version. It no longer covers a released version with no ledger.
+ *
+ * Exit codes: 0 complete · 1 missing/incomplete dispositions (an absent ledger
+ * for a RELEASED version is one of 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';
@@ -105,6 +136,124 @@ export function missing_dispositions(findings: readonly LedgerFinding[]): string
     return problems;
 }
 
+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 +376,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 {
@@ -253,7 +426,10 @@ 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 '
+                + 'clean release legitimately has no <version>.json. NARROWED: this no longer '
+                + 'covers a RELEASED version with no ledger, which returns 1 above on the '
+                + 'released/unreleased split; the waiver now covers an empty-but-present 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) {