@event4u/agent-config 9.21.0 → 9.23.0

package/src/scripts/_lib/gate_result.ts

@@ -0,0 +1,101 @@
+/**
+ * Estate-level result handling — telling "found violations" from "broke".
+ *
+ * A gate exits non-zero for two structurally different reasons, and the exit
+ * code alone cannot separate them:
+ *
+ * - **verdict** — it ran, inspected its corpus, and found violations. The
+ *   estate is being measured correctly; something in the tree is wrong.
+ * - **estate-invalidating** — it could not measure at all: the scan root is
+ *   dead, planned targets went unaccounted, the ratchet's base ref is
+ *   unreachable, the ledger was mis-used. Nothing was certified, and a report
+ *   built from this run is not a report.
+ *
+ * Conflating them costs in both directions. Treated as a verdict, an
+ * invalidated run sends a contributor hunting for a violation that does not
+ * exist. Treated as a crash, a real violation gets triaged as flakiness. This
+ * repository has recorded three traps of the second kind — estate invalidation
+ * misreported as a per-gate red.
+ *
+ * The classification reads the failure's own error name, which the structural
+ * errors already carry, rather than pattern-matching prose. A gate that throws
+ * something else is `crashed`: unknown, non-green, and reported as itself.
+ *
+ * **Gaming risk.** Nothing here can be gamed by a passing gate — the module
+ * only ever downgrades confidence. The real risk is the opposite: a future
+ * error class that IS estate-invalidating but is not listed below reads as a
+ * plain crash. Mitigated by keying on the shared `_lib` error names and by the
+ * fixture that pins each one; the residual is that a new structural error must
+ * be added here deliberately.
+ */
+
+/**
+ * Error names that mean the measurement is void, not that the tree is dirty.
+ *
+ * Sourced from the shared gate primitives: `scan_scope`, `gate_ledger`, and
+ * `ratchet_base_ref`.
+ */
+export const ESTATE_INVALIDATING_ERRORS: readonly string[] = [
+    'DeadScopeError',
+    'UnaccountedTargetsError',
+    'LedgerUsageError',
+    'BaseRefUnavailableError',
+    'ProbeOverflowError',
+];
+
+export type GateOutcome = 'clean' | 'violations' | 'crashed' | 'estate_invalid';
+
+export interface GateRunSignal {
+    /** Process exit code, or `null` when the gate never produced one. */
+    exitCode: number | null;
+    /** Combined stdout + stderr, used only to spot a named structural error. */
+    output: string;
+    /** True when the runner itself could not execute the gate. */
+    spawnFailed?: boolean;
+}
+
+/** True when `output` names one of the structural error classes. */
+export function namesEstateInvalidatingError(output: string): boolean {
+    return ESTATE_INVALIDATING_ERRORS.some((name) => output.includes(name));
+}
+
+/**
+ * Classify one gate run.
+ *
+ * Fail-closed on a null exit code: a gate that produced no verdict was not run,
+ * and a gate that was not run is not a passing gate.
+ */
+export function classifyGateRun(signal: GateRunSignal): GateOutcome {
+    if (signal.spawnFailed === true || signal.exitCode === null) {
+        return 'crashed';
+    }
+    if (namesEstateInvalidatingError(signal.output)) {
+        return 'estate_invalid';
+    }
+    return signal.exitCode === 0 ? 'clean' : 'violations';
+}
+
+/** True when this outcome must never contribute to a green aggregate. */
+export function blocksGreenAggregate(outcome: GateOutcome): boolean {
+    return outcome !== 'clean';
+}
+
+/**
+ * One-line explanation, so the estate report says WHICH kind of failure it is.
+ */
+export function describeOutcome(id: string, outcome: GateOutcome): string {
+    switch (outcome) {
+        case 'clean':
+            return `${id}: clean`;
+        case 'violations':
+            return `${id}: found violations — the measurement is sound, the tree is not`;
+        case 'estate_invalid':
+            return (
+                `${id}: ESTATE INVALID — it could not measure (dead scope, unaccounted targets, ` +
+                'unreachable base ref, or ledger misuse). Nothing was certified by this run, so ' +
+                'no report built on it is a report'
+            );
+        case 'crashed':
+            return `${id}: crashed with no verdict — not run, therefore not passing`;
+    }
+}

package/src/scripts/_lib/gate_self_test.ts

@@ -0,0 +1,129 @@
+/**
+ * Self-test harness — a gate proving, on demand, that its rejections fire.
+ *
+ * WHY. Every gate in this tree has fixtures in `tests/`, and those fixtures run
+ * in CI on the test job. That leaves one gap: nothing proves the gate binary a
+ * contributor actually invokes still rejects anything. A gate whose detection
+ * silently stopped matching — a regex that no longer fires, a scan root that
+ * moved, a suppression that widened — passes its unit tests against imported
+ * functions while the CLI it ships reports clean forever.
+ *
+ * `--self-test` closes that: the gate builds known-bad fixtures in a temporary
+ * directory and invokes ITSELF against them, asserting each rejection fires.
+ *
+ * **The floor is the load-bearing part.** A self-test is itself a checker, so a
+ * truncated case list must fail rather than print success — otherwise deleting
+ * cases is the cheapest way to a green self-test. {@link runSelfTest} refuses
+ * to pass below its declared minimum, and the minimum is a constant in the
+ * gate's own source where a reviewer sees it change.
+ *
+ * **Gaming risk.** The obvious degenerate pass is a case whose `expect` is
+ * `accept` and whose fixture is empty — it asserts nothing and still counts
+ * toward the floor. Mitigated by requiring at least one `reject` case and by
+ * counting reject cases separately in the floor check; the residual is that no
+ * harness can judge whether a fixture is *representative*, which stays a human
+ * read at review time.
+ */
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import process from 'node:process';
+
+/**
+ * Invoke a gate's real CLI against a fixture.
+ *
+ * Deliberately shells out rather than calling `main()` in-process: the thing
+ * under test is the binary a contributor runs, including its argv parsing and
+ * its entry guard. An in-process call would skip exactly the layers that have
+ * silently no-opped in this repository before.
+ */
+export function runGateCli(
+    repoRoot: string,
+    scriptRelPath: string,
+    args: readonly string[],
+    cwd: string,
+): number {
+    const tsx = path.join(
+        repoRoot,
+        'node_modules',
+        '.bin',
+        process.platform === 'win32' ? 'tsx.cmd' : 'tsx',
+    );
+    const res = spawnSync(tsx, [path.join(repoRoot, scriptRelPath), ...args], {
+        cwd,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+        // The child must not recurse into its own self-test.
+        env: { ...process.env, GATE_SELF_TEST_CHILD: '1' },
+    });
+    return res.status ?? 1;
+}
+
+export interface SelfTestCase {
+    /** Short description, printed per case. */
+    name: string;
+    /** `reject` — the gate must fail on this fixture. `accept` — it must pass. */
+    expect: 'reject' | 'accept';
+    /** Runs the fixture and returns the gate's exit code. */
+    run: () => number;
+}
+
+export interface SelfTestOptions {
+    gate: string;
+    cases: readonly SelfTestCase[];
+    /** Minimum total cases. Below this, the run FAILS regardless of results. */
+    minCases: number;
+    /** Minimum `reject` cases. A suite that only proves passes proves nothing. */
+    minRejectCases?: number;
+    write?: (chunk: string) => unknown;
+}
+
+/**
+ * Run a gate's self-test suite.
+ *
+ * @returns process exit code — 0 when every case behaved and the floor held.
+ */
+export function runSelfTest(opts: SelfTestOptions): number {
+    const write = opts.write ?? process.stdout.write.bind(process.stdout);
+    const minReject = opts.minRejectCases ?? 1;
+    const rejectCases = opts.cases.filter((c) => c.expect === 'reject').length;
+
+    if (opts.cases.length < opts.minCases || rejectCases < minReject) {
+        write(
+            `❌  ${opts.gate} --self-test: ${String(opts.cases.length)} case(s) ` +
+                `(${String(rejectCases)} rejecting) is below the declared floor of ` +
+                `${String(opts.minCases)} (${String(minReject)} rejecting). A truncated self-test ` +
+                'must fail rather than print success — deleting cases is otherwise the cheapest ' +
+                'route to a green one.\n',
+        );
+        return 1;
+    }
+
+    let failed = 0;
+    for (const testCase of opts.cases) {
+        let exit: number;
+        try {
+            exit = testCase.run();
+        } catch (e) {
+            write(`❌  ${opts.gate} --self-test: ${testCase.name} — threw: ${String(e)}\n`);
+            failed += 1;
+            continue;
+        }
+        const behaved = testCase.expect === 'reject' ? exit !== 0 : exit === 0;
+        if (behaved) {
+            write(`✅  ${testCase.name} (expected ${testCase.expect}, exit ${String(exit)})\n`);
+        } else {
+            write(
+                `❌  ${testCase.name}: expected the gate to ${testCase.expect} this fixture, ` +
+                    `got exit ${String(exit)}. The gate's detection has stopped firing on a case ` +
+                    'it is supposed to catch.\n',
+            );
+            failed += 1;
+        }
+    }
+
+    write(
+        `\n${opts.gate} --self-test: ${String(opts.cases.length - failed)}/${String(opts.cases.length)} ` +
+            `case(s) behaved (${String(rejectCases)} rejecting, floor ${String(opts.minCases)})\n`,
+    );
+    return failed > 0 ? 1 : 0;
+}

package/src/scripts/_lib/measured_render.ts

@@ -0,0 +1,97 @@
+/**
+ * Render-only-measured — a category with no measurement is never a number.
+ *
+ * WHY. The recorded failure: the always-budget report printed a share for a
+ * dimension it counted **zero** artefacts in. `0 / 0` became `0.0%`, and `0.0%`
+ * reads as a measurement that came back low — the most confident possible way
+ * to say nothing. Nobody looking at the page could tell the difference between
+ * "we measured this and it is at zero" and "we never measured this at all".
+ *
+ * The invariant is one line: **an unmeasured category renders as absent or
+ * explicitly "not measured", never as a zero and never as a computed share.**
+ * A zero is a claim; absence of measurement is not.
+ *
+ * The second half is the gap list. A coverage number published alone invites
+ * the reader to assume the remainder is small and boring. Naming the
+ * un-measured artefacts beside the covered count costs one line and removes the
+ * assumption — see {@link renderCoverage}.
+ *
+ * **Gaming risk.** A generator can still bypass this module and interpolate its
+ * own `${(n/d*100).toFixed(1)}%`. Nothing here can stop that; the mitigation is
+ * the paired test assertion (a generator handed an unmeasured dimension must
+ * emit no percentage) plus review. The residual is a generator that neither
+ * imports this nor carries that test, which is why the invariant is written
+ * into the authoring guideline rather than only into this file.
+ */
+
+/** How an unmeasured category is spelled. Exported so tests can pin it. */
+export const NOT_MEASURED = 'not measured';
+
+export interface ShareOptions {
+    /** Decimal places for a real share. Default 1. */
+    precision?: number;
+    /**
+     * Set false when the dimension was not measured at all, even though a
+     * denominator happens to be available. A denominator alone does not prove
+     * the measurement ran.
+     */
+    measured?: boolean;
+}
+
+/**
+ * A percentage, or {@link NOT_MEASURED} when there is nothing to divide.
+ *
+ * Never returns `0.0%` for an empty denominator — that is the whole point.
+ */
+export function renderShare(numerator: number, denominator: number, opts: ShareOptions = {}): string {
+    if (opts.measured === false || denominator <= 0 || !Number.isFinite(denominator)) {
+        return NOT_MEASURED;
+    }
+    if (!Number.isFinite(numerator)) {
+        return NOT_MEASURED;
+    }
+    return `${((numerator / denominator) * 100).toFixed(opts.precision ?? 1)}%`;
+}
+
+/** A count, or {@link NOT_MEASURED} when the category was never measured. */
+export function renderCount(value: number | null | undefined, measured = true): string {
+    if (!measured || value === null || value === undefined || !Number.isFinite(value)) {
+        return NOT_MEASURED;
+    }
+    return String(value);
+}
+
+export interface CoverageLine {
+    label: string;
+    covered: number;
+    total: number;
+    /** The un-covered artefacts, named. Empty array means genuinely none. */
+    gaps: readonly string[];
+    /** Cap on how many gap names are printed inline. Default 8. */
+    maxGaps?: number;
+}
+
+/**
+ * A coverage number WITH its gap list.
+ *
+ * The gap list is not optional formatting. A coverage number published alone
+ * lets the reader assume the remainder is small and boring; naming it removes
+ * the assumption at the cost of one line. When the count is capped for length,
+ * the true remainder is still stated — a silently truncated gap list reads as
+ * "covered everything" exactly like the number it was meant to qualify.
+ */
+export function renderCoverage(line: CoverageLine): string {
+    const share = renderShare(line.covered, line.total);
+    const head = `${line.label}: ${String(line.covered)}/${String(line.total)} (${share})`;
+    if (line.total <= 0) {
+        return `${line.label}: ${NOT_MEASURED} — the population is empty, so there is no coverage to report`;
+    }
+    if (line.gaps.length === 0) {
+        return `${head} — no gaps`;
+    }
+    const cap = line.maxGaps ?? 8;
+    const shown = line.gaps.slice(0, cap);
+    const more = line.gaps.length - shown.length;
+    const tail = more > 0 ? `, … and ${String(more)} more` : '';
+    return `${head} — not covered: ${shown.join(', ')}${tail}`;
+}