@event4u/agent-config 16.1.0 → 16.2.0

package/src/scripts/check_read_surface_coverage.ts

@@ -0,0 +1,515 @@
+#!/usr/bin/env tsx
+/**
+ * check_read_surface_coverage.ts — generate the sanitize floor's read-surface
+ * table in `docs/contracts/retrieval-read-surfaces.md` from the tree, and fail
+ * when the committed table, the module header, or the structural detector
+ * disagree with what the tree actually says
+ * (road-to-a-sanitize-list-that-is-generated, Phase 1.2 + Phase 3.3).
+ *
+ * THREE CHECKS, ONE REASON
+ * ------------------------
+ * 1. DRIFT — the committed table equals the regenerated one. A new module that
+ *    brings outside bytes in, or a sanitize import added or removed, changes the
+ *    table; leaving the committed copy behind is the failure this gate exists
+ *    for.
+ * 2. SECOND COPY — `retrieval_sanitize.ts`'s header points at the table instead
+ *    of restating it. Two copies of a list is exactly how the first one went
+ *    stale, twice, so a header that names a module path the table also names is
+ *    a finding rather than a nicety.
+ * 3. NO PERCENTAGE — the structural-hiding detector publishes no recall or
+ *    coverage rate. A rate needs a frozen corpus of hiding techniques and none
+ *    exists; a number would be an invented denominator that a later reader
+ *    quotes as measured coverage. Enforced rather than asserted, because a
+ *    prose promise not to publish a number is the weakest control available.
+ *
+ * WHAT A GREEN RUN PROVES, AND WHAT IT DOES NOT
+ * ---------------------------------------------
+ * Green means the published table agrees with the tree's import graph. It
+ * proves nothing about whether any module applies the floor to the right
+ * string. `covered` is "the floor is in scope in this module"; establishing
+ * that it is actually reached needs a read of the module, and this gate does
+ * not pretend otherwise — the table header says so in its own first lines.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import {
+    LOCAL_VCS_EXCLUSION,
+    type ReadSurfaceRow,
+    SCAN_ROOT,
+    renderTable,
+    scanReadSurfaces,
+    tally,
+} from './_lib/read_surface_scan.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const GATE = 'check_read_surface_coverage';
+export const DOC_REL = 'docs/contracts/retrieval-read-surfaces.md';
+export const FLOOR_REL = 'src/scripts/_lib/retrieval_sanitize.ts';
+export const DETECTOR_REL = 'src/scripts/_lib/structural_hiding.ts';
+
+export const BEGIN_MARKER = '<!-- BEGIN read-surface-table (generated) -->';
+export const END_MARKER = '<!-- END read-surface-table -->';
+
+const REGEN_COMMAND = `./scripts-run src/scripts/${GATE} --write`;
+
+function _read(root: string, rel: string): string | null {
+    try {
+        return fs.readFileSync(path.join(root, rel), 'utf-8');
+    } catch {
+        return null;
+    }
+}
+
+/** The leading block comment of a module — its header, and nothing after it. */
+export function leadingBlockComment(src: string): string {
+    const m = /^\s*\/\*\*[\s\S]*?\*\//.exec(src);
+    return m === null ? '' : m[0];
+}
+
+/** Render the full generated region, header prose included. */
+export function renderRegion(rows: readonly ReadSurfaceRow[]): string {
+    return [
+        '> Generated by `' + GATE + '`. Do not edit between the markers — a cell',
+        '> edited by hand is overwritten by the next regeneration and reported by the',
+        '> gate in between. Corrections belong in the tree or in the scanner.',
+        '',
+        '**A row is a claim about imports, not about safety.** `covered` means the',
+        'module imports the sanitize floor, so the floor is in scope there. It does',
+        'not say the floor is applied to the right string or at the right point —',
+        'that needs a read of the module, and no import graph can supply it.',
+        '',
+        '**What is out of scope, said here rather than left to be discovered.** ' +
+            LOCAL_VCS_EXCLUSION,
+        '',
+        'A module reaching the network through a shape in neither the strong nor the',
+        'weak detector set is absent from this table entirely. That residual is the',
+        'reason `unclassified` exists and the reason this paragraph does.',
+        '',
+        renderTable(rows),
+    ].join('\n');
+}
+
+/** Replace the marked region in `doc`, or append one when absent. */
+export function spliceRegion(doc: string, region: string): string {
+    const begin = doc.indexOf(BEGIN_MARKER);
+    const end = doc.indexOf(END_MARKER);
+    if (begin === -1 || end === -1 || end < begin) {
+        return `${doc.trimEnd()}\n\n${BEGIN_MARKER}\n${region}\n${END_MARKER}\n`;
+    }
+    return `${doc.slice(0, begin)}${BEGIN_MARKER}\n${region}\n${doc.slice(end)}`;
+}
+
+/** Extract the marked region's body, or `null` when the markers are missing. */
+export function extractRegion(doc: string): string | null {
+    const begin = doc.indexOf(BEGIN_MARKER);
+    const end = doc.indexOf(END_MARKER);
+    if (begin === -1 || end === -1 || end < begin) return null;
+    return doc.slice(begin + BEGIN_MARKER.length, end).trim();
+}
+
+/**
+ * Module paths the floor's header restates instead of pointing at.
+ *
+ * Matching on the basename keeps the check honest against a header that names
+ * `memory_lookup.ts` without its directory — the shape the previous header
+ * actually used.
+ */
+export function headerSecondCopy(header: string, rows: readonly ReadSurfaceRow[]): string[] {
+    const hits = new Set<string>();
+    for (const r of rows) {
+        const base = r.module.split('/').pop() ?? r.module;
+        if (header.includes(base)) hits.add(base);
+    }
+    return [...hits].sort();
+}
+
+interface Options {
+    root: string;
+    write: boolean;
+    quiet: boolean;
+}
+
+/**
+ * A published rate — `99 %`, `72.33%`, `recall: 0.98`.
+ *
+ * Scoped to the DETECTOR FILE and nothing else, deliberately. The codepoint
+ * floor next door publishes two real, corpus-backed percentages in its own
+ * docblock; a check that swept every citing surface would red on those and be
+ * switched off within a week. The claim this rule defends is narrow — the
+ * STRUCTURAL layer has no frozen corpus, so it has no denominator — and the
+ * check is scoped to exactly that claim.
+ */
+const PERCENTAGE_RE = /\b\d+(?:\.\d+)?\s*%|\brecall\s*[:=]\s*\d/i;
+
+/** The register's exported name, cited by every surface claiming the coverage. */
+export const GAP_REGISTER_SYMBOL = 'STRUCTURAL_HIDING_GAPS';
+
+/**
+ * True when a percentage or recall figure is PUBLISHED in the detector.
+ *
+ * Inline code spans are removed before the test, and that exclusion is the
+ * difference between a rule and a nuisance. The gap register names
+ * `transform: translate(-100%, 0)` as an off-screen hiding technique — a CSS
+ * literal inside backticks, not a claim about this detector's coverage. The
+ * first version of this check red on exactly that and the fix belongs here,
+ * in the predicate, rather than in the register's wording: a gate that makes
+ * honest prose contort around it gets switched off. Both directions are pinned
+ * by self-test cases, because a widened matcher that no longer catches the
+ * thing it was written for fails silently.
+ */
+export function publishesRate(detectorSrc: string): boolean {
+    for (const line of detectorSrc.split('\n')) {
+        // The rule states the prohibition in prose; the prose is not a breach.
+        if (line.includes('PERCENTAGE_RE') || line.includes('no recall or coverage')) continue;
+        const prose = line.replace(/`[^`]*`/g, '');
+        if (PERCENTAGE_RE.test(prose)) return true;
+    }
+    return false;
+}
+
+function parseArgs(argv: readonly string[]): Options {
+    const out: Options = { root: ROOT, write: false, quiet: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--root') {
+            out.root = path.resolve(argv[i + 1] ?? '.');
+            i += 1;
+        } else if (a === '--write') out.write = true;
+        else if (a === '--quiet') out.quiet = true;
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const opts = parseArgs(argv);
+    const say = (s: string): void => {
+        if (!opts.quiet) process.stdout.write(s);
+    };
+
+    const rows = scanReadSurfaces(opts.root);
+    const region = renderRegion(rows);
+
+    if (opts.write) {
+        const existing = _read(opts.root, DOC_REL) ?? `# Retrieval read surfaces\n`;
+        fs.mkdirSync(path.join(opts.root, path.dirname(DOC_REL)), { recursive: true });
+        fs.writeFileSync(path.join(opts.root, DOC_REL), spliceRegion(existing, region), 'utf-8');
+        process.stdout.write(`✍️  ${GATE}: wrote ${String(rows.length)} row(s) to ${DOC_REL}\n`);
+        return 0;
+    }
+
+    const findings: string[] = [];
+
+    // 1. Drift between the tree and the committed table.
+    const doc = _read(opts.root, DOC_REL);
+    if (doc === null) {
+        findings.push(`${DOC_REL} is missing — the generated table has no home.`);
+    } else {
+        const committed = extractRegion(doc);
+        if (committed === null) {
+            findings.push(`${DOC_REL} carries no \`${BEGIN_MARKER}\` … \`${END_MARKER}\` region.`);
+        } else if (committed !== region.trim()) {
+            findings.push(
+                `${DOC_REL} disagrees with the tree. The table is generated; regenerate it.`,
+            );
+        }
+    }
+
+    // 2. The floor's header points at the table rather than restating it.
+    const floor = _read(opts.root, FLOOR_REL);
+    if (floor === null) {
+        findings.push(`${FLOOR_REL} is missing — the floor this table describes is gone.`);
+    } else {
+        const header = leadingBlockComment(floor);
+        if (!header.includes(DOC_REL)) {
+            findings.push(
+                `${FLOOR_REL}'s header does not point at ${DOC_REL}. The coverage list is ` +
+                    'generated; the header carries the pointer, never a second copy.',
+            );
+        }
+        const copies = headerSecondCopy(header, rows);
+        if (copies.length > 0) {
+            findings.push(
+                `${FLOOR_REL}'s header names ${String(copies.length)} module(s) the table also ` +
+                    `names (${copies.join(', ')}). Two copies of this list is how it went stale ` +
+                    'twice; the header points, the table lists.',
+            );
+        }
+    }
+
+    // 3. NO PERCENTAGE, and the gap register travels with the claim.
+    //
+    // This rule was REMOVED once, correctly: it watched a detector file that
+    // did not exist, and both review seats called it dead policy. It returns
+    // here with the detector, written against a file that exists, with its own
+    // rejecting self-test cases. If the detector is absent the rule is silent
+    // rather than red — a missing detector is Phase 3 being open, not a breach.
+    const detector = _read(opts.root, DETECTOR_REL);
+    if (detector !== null) {
+        if (publishesRate(detector)) {
+            findings.push(
+                `${DETECTOR_REL} publishes a recall or coverage figure. A rate needs a frozen ` +
+                    'corpus of hiding techniques and none exists in this tree, so the number ' +
+                    'would be an invented denominator a later reader quotes as measured coverage. ' +
+                    'State the covered-channel list and the gap register instead.',
+            );
+        }
+        if (!detector.includes(GAP_REGISTER_SYMBOL)) {
+            findings.push(
+                `${DETECTOR_REL} does not define ${GAP_REGISTER_SYMBOL}. The register of what the ` +
+                    "detector does NOT catch belongs in the detector's own file — a detector " +
+                    'documented without its gaps is how the coverage claim becomes a false green.',
+            );
+        }
+        for (const [rel, src] of [
+            [FLOOR_REL, floor],
+            [DOC_REL, doc],
+        ] as const) {
+            if (src === null) continue;
+            if (!src.includes('structural_hiding')) continue; // claims nothing
+            if (src.includes(GAP_REGISTER_SYMBOL)) continue;
+            findings.push(
+                `${rel} claims the structural coverage without citing ${GAP_REGISTER_SYMBOL}. ` +
+                    'Every surface that claims this coverage cites the register alongside the ' +
+                    'claim, so the caveat travels with the claim rather than staying in one file.',
+            );
+        }
+    }
+
+    try {
+        reportScanned({
+            gate: GATE,
+            scanned: rows.length,
+            units: 'read surface(s)',
+            roots: [SCAN_ROOT],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stdout.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+
+    if (findings.length > 0) {
+        for (const f of findings) process.stdout.write(`❌  ${GATE}: ${f}\n`);
+        process.stdout.write(`\n${String(findings.length)} finding(s). Regenerate with:\n    ${REGEN_COMMAND}\n`);
+        return 1;
+    }
+    const t = tally(rows);
+    say(
+        `✅  ${GATE}: ${String(rows.length)} read surface(s) in ${DOC_REL} match the tree ` +
+            `(${String(t.covered)} covered, ${String(t.uncovered)} uncovered, ` +
+            `${String(t.unclassified)} unclassified).\n`,
+    );
+    return 0;
+}
+
+/**
+ * One rejecting case per way the three checks can be defeated.
+ *
+ * The empty-root case is the one that matters most here: a gate whose scan root
+ * moved reads zero surfaces and would otherwise certify a table it never
+ * compared. `assertScanned` has to turn that into a refusal, and only a fixture
+ * with no `src/scripts/` at all proves it does.
+ */
+function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'read-surface-'));
+    const floor = _read(ROOT, FLOOR_REL) ?? '';
+
+    /** Plant a fixture root with a one-module scan tree plus the three inputs. */
+    const plant = (
+        name: string,
+        opts: {
+            module?: string;
+            mutateRegion?: (r: string) => string;
+            floorSrc?: string;
+            detectorSrc?: string;
+            noScanRoot?: boolean;
+        },
+    ): string => {
+        const dir = path.join(tmp, name);
+        if (opts.noScanRoot !== true) {
+            fs.mkdirSync(path.join(dir, SCAN_ROOT, '_lib'), { recursive: true });
+            fs.writeFileSync(
+                path.join(dir, SCAN_ROOT, 'seed_surface.ts'),
+                opts.module ??
+                    'export async function pull(u: string): Promise<string> {\n' +
+                        '    const r = await fetch(u);\n' +
+                        '    return await r.text();\n}\n',
+                'utf-8',
+            );
+        } else {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.mkdirSync(path.join(dir, path.dirname(FLOOR_REL)), { recursive: true });
+        fs.mkdirSync(path.join(dir, path.dirname(DOC_REL)), { recursive: true });
+        fs.writeFileSync(path.join(dir, FLOOR_REL), opts.floorSrc ?? floor, 'utf-8');
+        // The detector is planted ONLY where a case needs it. Absent, rule 3 is
+        // silent — which is itself the behaviour the last case below pins.
+        if (opts.detectorSrc !== undefined) {
+            fs.mkdirSync(path.join(dir, path.dirname(DETECTOR_REL)), { recursive: true });
+            fs.writeFileSync(path.join(dir, DETECTOR_REL), opts.detectorSrc, 'utf-8');
+        }
+        const region = renderRegion(scanReadSurfaces(dir));
+        fs.writeFileSync(
+            path.join(dir, DOC_REL),
+            `# fixture\n\n${BEGIN_MARKER}\n${(opts.mutateRegion ?? ((r) => r))(region)}\n${END_MARKER}\n`,
+            'utf-8',
+        );
+        return dir;
+    };
+
+    const run = (root: string): number =>
+        runGateCli(ROOT, `src/scripts/${GATE}.ts`, ['--root', root], root);
+
+    try {
+        return runSelfTest({
+            gate: GATE,
+            minCases: 10,
+            minRejectCases: 7,
+            cases: [
+                {
+                    name: 'an unsanitized fetch-derived emit the committed table does not carry is rejected',
+                    expect: 'reject',
+                    run: () => {
+                        const dir = plant('seeded', {});
+                        fs.writeFileSync(
+                            path.join(dir, SCAN_ROOT, 'seeded_leak.ts'),
+                            'export async function grab(u: string): Promise<void> {\n' +
+                                '    const r = await fetch(u);\n' +
+                                '    writeFileSync("out.md", await r.text());\n}\n',
+                            'utf-8',
+                        );
+                        return run(dir);
+                    },
+                },
+                {
+                    name: 'a hand-flipped coverage cell is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            plant('flipped', {
+                                mutateRegion: (r) => r.replace('**uncovered**', '**covered**'),
+                            }),
+                        ),
+                },
+                {
+                    name: "a header restating a module path the table lists is rejected",
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            plant('second-copy', {
+                                floorSrc: `/**\n * Floor.\n * See ${DOC_REL}.\n * - seed_surface.ts — yes\n */\nexport const x = 1;\n`,
+                            }),
+                        ),
+                },
+                {
+                    name: 'a header with no pointer to the generated table is rejected',
+                    expect: 'reject',
+                    run: () => run(plant('no-pointer', { floorSrc: '/**\n * Floor.\n */\nexport const x = 1;\n' })),
+                },
+                {
+                    name: 'an empty scan root is refused rather than certified',
+                    expect: 'reject',
+                    run: () => run(plant('empty-root', { noScanRoot: true })),
+                },
+                {
+                    name: 'a detector publishing a coverage percentage is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            plant('rate-published', {
+                                floorSrc: `/**\n * Floor. Coverage list: ${DOC_REL}.\n * Gaps: ${GAP_REGISTER_SYMBOL}.\n */\nexport const x = 1;\n`,
+                                detectorSrc:
+                                    `export const ${GAP_REGISTER_SYMBOL} = ['stylesheet-driven hiding'];\n` +
+                                    '/** Measured recall over the channel corpus: 94.2 %. */\n' +
+                                    'export const y = 1;\n',
+                            }),
+                        ),
+                },
+                {
+                    name: 'a detector with no gap register is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            plant('no-register', {
+                                floorSrc: `/**\n * Floor. Coverage list: ${DOC_REL}.\n * Gaps: ${GAP_REGISTER_SYMBOL}.\n */\nexport const x = 1;\n`,
+                                detectorSrc: 'export const y = 1;\n',
+                            }),
+                        ),
+                },
+                {
+                    name: 'a floor claiming the coverage without citing the gap register is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            plant('register-uncited', {
+                                floorSrc: `/**\n * Floor. Coverage list: ${DOC_REL}. Structural: structural_hiding.\n */\nexport const x = 1;\n`,
+                                detectorSrc: `export const ${GAP_REGISTER_SYMBOL} = ['stylesheet-driven hiding'];\n`,
+                            }),
+                        ),
+                },
+                {
+                    name: 'a CSS percentage inside a code span is NOT read as a published rate',
+                    expect: 'accept',
+                    run: () =>
+                        run(
+                            plant('rate-in-code-span', {
+                                floorSrc: `/**\n * Floor. Coverage list: ${DOC_REL}.\n * Gaps: ${GAP_REGISTER_SYMBOL}.\n */\nexport const x = 1;\n`,
+                                detectorSrc:
+                                    `export const ${GAP_REGISTER_SYMBOL} = [\n` +
+                                    "    'off-screen positioning — `transform: translate(-100%, 0)`',\n" +
+                                    '];\n',
+                            }),
+                        ),
+                },
+                {
+                    name: 'a detector that exists, publishes no rate and carries its register passes',
+                    expect: 'accept',
+                    run: () =>
+                        run(
+                            plant('detector-clean', {
+                                floorSrc: `/**\n * Floor. Coverage list: ${DOC_REL}.\n * Gaps: ${GAP_REGISTER_SYMBOL}.\n */\nexport const x = 1;\n`,
+                                detectorSrc: `export const ${GAP_REGISTER_SYMBOL} = ['stylesheet-driven hiding'];\n`,
+                            }),
+                        ),
+                },
+                {
+                    name: 'a regenerated table over an intact tree passes',
+                    expect: 'accept',
+                    run: () =>
+                        run(
+                            plant('good', {
+                                floorSrc: `/**\n * Floor. Coverage list: ${DOC_REL}.\n */\nexport const x = 1;\n`,
+                            }),
+                        ),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/check_release_holds.ts

@@ -45,7 +45,8 @@ const _HERE = fileURLToPath(import.meta.url);
 /**
  * The folders a release question must read.
  *
- * Wider than `lint_roadmap_blockers`' active-only glob on purpose: rule 28's
+ * Wider than `lint_roadmap_blockers`' glob on purpose — that gate reads the
+ * active tree plus `stubs/` and stops there (2026-09-28), while rule 28's
  * per-folder lifecycle says a window does not disappear by moving the file, and
  * a `later/` roadmap still refuses. `archive/` and `skipped/` are included
  * because the move INTO them is refused while a window is open — a file that