@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/build_exit_code_register.ts

@@ -0,0 +1,440 @@
+#!/usr/bin/env tsx
+/**
+ * Generate `docs/contracts/exit-code-register.md` — the exit codes of `init`,
+ * `sync`, `doctor` and `uninstall`, read out of the code that returns them.
+ *
+ * WHAT IS GENERATED AND WHAT IS WRITTEN. The SET of codes each command can
+ * return is scanned from its sources; only the one-line meaning of each code is
+ * written by hand, in {@link COMMANDS}. The two are reconciled on every run: a
+ * code the scan finds with no meaning, or a meaning for a code the scan does
+ * not find, fails the build. So the register cannot list a code the command
+ * stopped returning, and a new code cannot ship undocumented.
+ *
+ * THE SCAN, and its blind spot. A code is counted where it appears as a
+ * literal exit: `return N;`, `return <cond> ? N : M;`, `ArgparseExit(N)`,
+ * `process.exit(N)`, bash `exit N`, or a `return` of an exported `EXIT_*`
+ * constant, resolved to its value. A code passed through a variable
+ * (`return rc;`) is invisible to it — that is what `inherits` is for: a command
+ * that forwards another command's code names the forwarding line, and the
+ * generator asserts the line still exists before it unions the codes.
+ *
+ * `return N;` also matches helpers that return a count; scanning only the
+ * command's own entry files keeps that to the codes {0, 1, 2}, which every
+ * command returns anyway. A helper returning another literal would surface
+ * here as an undocumented code — a false alarm that fails loudly, which is the
+ * acceptable direction.
+ *
+ * Exit: 0 written / up to date · 1 drift under `--check`, or a scan that
+ * disagrees with the declared meanings · 2 usage error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { generatedBy } from './_lib/generated_by.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const OUT_REL = 'docs/contracts/exit-code-register.md';
+
+export interface Inherit {
+    readonly from: string;
+    /** The file and the literal line that forwards `from`'s code. */
+    readonly file: string;
+    readonly fragment: string;
+}
+
+export interface CommandSpec {
+    readonly verb: string;
+    readonly sources: readonly string[];
+    readonly meanings: Readonly<Record<number, string>>;
+    readonly inherits?: readonly Inherit[];
+}
+
+/** One surface's half of a pair: the command, and the code it gives that state. */
+export interface PairSurface {
+    readonly verb: string;
+    readonly code: number;
+}
+
+/**
+ * Two surfaces that report on ONE state, and the test that runs both over one
+ * tree.
+ *
+ * A consumer scripting against two commands needs to know which of their codes
+ * describe the same condition, because a pair that drifts apart is worse than
+ * either code being wrong alone: the install says the tree is stale and the
+ * doctor says it is fine, and the consumer believes whichever they happened to
+ * run. The register names the pair so the agreement is a published contract
+ * rather than a coincidence of two implementations.
+ *
+ * WHAT EACH HALF OF THE CHECK ACTUALLY PROVES, stated narrowly because the
+ * first version of this comment claimed more than the code delivered.
+ *
+ * The TEST is the pin on which code goes with which state: it drives both
+ * surfaces over one tree and asserts each exact code. The GENERATOR cannot
+ * know that — a scan sees that `doctor` returns `1` somewhere, not that it
+ * returns `1` for THIS state — so it checks the two things it can: that the
+ * register still documents each paired code for its verb, and that the named
+ * test still contains the exact assertion literal for each one. The second
+ * check runs over `strip()`ped source, so commenting an assertion out fails
+ * the build rather than passing it.
+ *
+ * What neither half catches, stated in full because a named blind spot is the
+ * only honest form of a check this narrow:
+ *
+ * - a test that is SKIPPED rather than deleted still contains its literals and
+ *   still documents its codes. The vitest run does NOT notice it either — a
+ *   skipped case is reported as skipped and `vitest run` still exits 0. The
+ *   gate that sees it is `check_test_weakening`, which reads the diff rather
+ *   than the tree, so it catches the commit that adds the skip and not a tree
+ *   that already carries one.
+ * - the assertion match is file-wide, so it proves each literal is SOMEWHERE in
+ *   the named file, not that both sit in one `it` driving one tree. Its
+ *   sensitivity rests on each literal being unique in that file, which is a
+ *   property of today's file rather than an invariant.
+ * - the pair reads as symmetric and is not. `init` 3 is state-specific; the
+ *   `doctor` side is the broad "drift or a failing check" 1, so the pair
+ *   licenses "preserved file ⇒ doctor 1" and NOT its converse. The published
+ *   section says so, because a reader of the table would otherwise supply the
+ *   reverse themselves.
+ */
+export interface SurfacePair {
+    /** The single state, in a phrase a consumer would recognise. */
+    readonly state: string;
+    readonly surfaces: readonly [PairSurface, PairSurface];
+    /** The test that exercises both surfaces against one tree. */
+    readonly assertedIn: string;
+    /**
+     * The exact assertion that pins each surface's code in that test, in the
+     * same order as {@link surfaces}. A title would not do: a title survives a
+     * gutted body, and these are the lines that carry the codes.
+     */
+    readonly assertions: readonly [string, string];
+}
+
+export const PAIRS: readonly SurfacePair[] = [
+    {
+        state:
+            'the install preserved a user-modified managed file, so the active installation is stale',
+        surfaces: [
+            { verb: 'init', code: 3 },
+            { verb: 'doctor', code: 1 },
+        ],
+        assertedIn: 'tests/install/ownership_ledger_real_install.test.ts',
+        assertions: ['expect(second.status, second.out).toBe(3)', 'expect(after.status).toBe(1)'],
+    },
+];
+
+export const COMMANDS: readonly CommandSpec[] = [
+    {
+        verb: 'init',
+        sources: ['src/scripts/install', 'src/scripts/install.ts', 'src/install/conflictTracker.ts'],
+        meanings: {
+            0: 'installed, and every written file is current',
+            1: 'the install failed or was refused partway (missing payload, payload sync failed, a write failed, `--scope=project` without dev mode)',
+            2: 'usage error, or a refusal before anything is written (own source checkout, unsupported schema version, rule-layer overlap, no TS runner)',
+            3: 'installed what it could, but preserved at least one user-modified file — the install is stale until the `.agent-config.new` sidecars are resolved',
+        },
+    },
+    {
+        verb: 'sync',
+        sources: ['src/scripts/_cli/cmd_sync.ts'],
+        meanings: {
+            0: 'every tool in the lockfile is present, or was replayed',
+            1: 'no install lockfile to replay, or a replay the installer failed (its `1`, forwarded)',
+            2: 'usage error, or a replay the installer refused (its `2`, forwarded)',
+            3: 'replayed, but the installer preserved a user-modified file (its `3`, forwarded) — stale until resolved',
+        },
+        inherits: [{ from: 'init', file: 'src/scripts/_cli/cmd_sync.ts', fragment: 'return rc;' }],
+    },
+    {
+        verb: 'doctor',
+        sources: ['src/scripts/_cli/cmd_doctor.ts', 'src/scripts/_cli/_doctor_strict.ts'],
+        meanings: {
+            0: 'no manifest drift; under `--ci`, `--check` or `--strict`, also no check at the tripping status',
+            1: 'manifest drift; or, under `--ci`, `--check` or `--strict`, a check at the tripping status',
+            2: 'usage error, unresolvable project root, failed repair, no install in the tree, or `--check` on a check that was skipped',
+        },
+    },
+    {
+        verb: 'uninstall',
+        sources: ['src/scripts/_cli/cmd_uninstall.ts'],
+        meanings: {
+            0: 'removed what it owned, or there was nothing to remove',
+            1: 'no lockfile and no `--force`, or a removal was refused',
+            2: 'usage error',
+        },
+    },
+];
+
+function strip(source: string): string {
+    return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`$])\/\/.*$/gm, '$1');
+}
+
+const LITERAL_RES: readonly RegExp[] = [
+    /\breturn (\d+);/g,
+    /\breturn [^;?\n]+\? (\d+) : (\d+);/g,
+    /\bArgparseExit\((\d+)\)/g,
+    /(?:^|[\s;(])exit (\d+)\b/gm,
+    /\bprocess\.exit\((\d+)\)/g,
+];
+const CONSTANT_RE = /\breturn (?:[^;\n]*\? )?(EXIT_[A-Z0-9_]+)\b/g;
+
+/** `export const EXIT_X = N;` anywhere under `src/`, by name. */
+export function exitConstants(root: string): Map<string, number> {
+    const out = new Map<string, number>();
+    const walk = (dir: string): void => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name !== 'node_modules') walk(full);
+            } else if (e.name.endsWith('.ts') && !e.name.endsWith('.test.ts')) {
+                const text = fs.readFileSync(full, 'utf8');
+                for (const m of text.matchAll(/^export const (EXIT_[A-Z0-9_]+) = (\d+);/gm)) {
+                    out.set(m[1] as string, Number(m[2]));
+                }
+            }
+        }
+    };
+    const src = path.join(root, 'src');
+    if (fs.existsSync(src)) walk(src);
+    return out;
+}
+
+/** The literal exit codes one source returns, each with the files that emit it. */
+export function scanCodes(text: string, constants: ReadonlyMap<string, number>): Set<number> {
+    const s = strip(text);
+    const codes = new Set<number>();
+    for (const re of LITERAL_RES) {
+        for (const m of s.matchAll(re)) {
+            for (const g of m.slice(1)) if (g !== undefined) codes.add(Number(g));
+        }
+    }
+    for (const m of s.matchAll(CONSTANT_RE)) {
+        const v = constants.get(m[1] as string);
+        if (v !== undefined) codes.add(v);
+    }
+    return codes;
+}
+
+export interface Row {
+    readonly code: number;
+    readonly meaning: string;
+    readonly emittedIn: readonly string[];
+}
+
+export interface Register {
+    readonly rows: ReadonlyMap<string, readonly Row[]>;
+    readonly pairs: readonly SurfacePair[];
+    readonly errors: readonly string[];
+}
+
+/**
+ * Check each pair against what the scan found and against the test that
+ * asserts it. Errors, never silence: a pair whose halves have drifted is the
+ * condition the section exists to catch.
+ */
+export function checkPairs(
+    root: string,
+    rows: ReadonlyMap<string, readonly Row[]>,
+    pairs: readonly SurfacePair[],
+): string[] {
+    const errors: string[] = [];
+    for (const pair of pairs) {
+        for (const s of pair.surfaces) {
+            const codes = rows.get(s.verb);
+            if (codes === undefined) {
+                errors.push(`pair "${pair.state}": names \`${s.verb}\`, which the register does not cover`);
+            } else if (!codes.some((r) => r.code === s.code)) {
+                errors.push(`pair "${pair.state}": \`${s.verb}\` no longer returns ${s.code}`);
+            }
+        }
+        const abs = path.join(root, pair.assertedIn);
+        if (!fs.existsSync(abs)) {
+            errors.push(`pair "${pair.state}": asserted in ${pair.assertedIn}, which does not exist`);
+            continue;
+        }
+        // Stripped, like the `inherits` fragment check below: an assertion that
+        // survives only inside a comment is an assertion nobody runs, and the
+        // raw text would have called that intact.
+        const body = strip(fs.readFileSync(abs, 'utf8'));
+        pair.assertions.forEach((assertion, i) => {
+            if (!body.includes(assertion)) {
+                const verb = pair.surfaces[i]?.verb ?? '?';
+                errors.push(
+                    `pair "${pair.state}": ${pair.assertedIn} no longer asserts the \`${verb}\` side — ` +
+                        `\`${assertion}\` is gone`,
+                );
+            }
+        });
+    }
+    return errors;
+}
+
+/**
+ * `pairs` defaults to the production set, unconditionally.
+ *
+ * A fixture caller passing its own `commands` must also pass `pairs: []`, and
+ * the cost of forgetting is an error about a file the fixture never claimed to
+ * have — loud, and in the wrong place, but loud.
+ *
+ * That is deliberate, and it is the second answer to this question. The first
+ * scoped the default with `commands === COMMANDS ? PAIRS : []`, which spared
+ * fixture callers the confusing error and introduced a worse failure: a caller
+ * holding a non-identical array — `[...COMMANDS]`, a filtered set, a future
+ * `--only <verb>` — would have lost the pair check silently, with no error and
+ * no red case. A gate that disables itself on reference identity is fail-open,
+ * and a confusing error beats a silent one. `main`'s path keeping the check is
+ * pinned by a test rather than left to this default.
+ */
+export function build(
+    root: string,
+    commands: readonly CommandSpec[] = COMMANDS,
+    pairs: readonly SurfacePair[] = PAIRS,
+): Register {
+    const constants = exitConstants(root);
+    const errors: string[] = [];
+    const own = new Map<string, Map<number, string[]>>();
+    for (const cmd of commands) {
+        const byCode = new Map<number, string[]>();
+        for (const rel of cmd.sources) {
+            const abs = path.join(root, rel);
+            if (!fs.existsSync(abs)) {
+                errors.push(`${cmd.verb}: source ${rel} does not exist`);
+                continue;
+            }
+            for (const c of scanCodes(fs.readFileSync(abs, 'utf8'), constants)) {
+                byCode.set(c, [...(byCode.get(c) ?? []), rel]);
+            }
+        }
+        own.set(cmd.verb, byCode);
+    }
+    const rows = new Map<string, Row[]>();
+    for (const cmd of commands) {
+        const byCode = new Map(own.get(cmd.verb));
+        for (const inh of cmd.inherits ?? []) {
+            const abs = path.join(root, inh.file);
+            if (!fs.existsSync(abs) || !strip(fs.readFileSync(abs, 'utf8')).includes(inh.fragment)) {
+                errors.push(`${cmd.verb}: inherits ${inh.from} through \`${inh.fragment}\` in ${inh.file}, which is no longer there`);
+                continue;
+            }
+            for (const c of own.get(inh.from)?.keys() ?? []) {
+                if (!byCode.has(c)) byCode.set(c, [`via ${inh.from}`]);
+            }
+        }
+        const declared = new Set(Object.keys(cmd.meanings).map(Number));
+        for (const c of byCode.keys()) {
+            if (!declared.has(c)) {
+                errors.push(`${cmd.verb}: returns ${c} (${(byCode.get(c) ?? []).join(', ')}) but the register gives it no meaning`);
+            }
+        }
+        for (const c of declared) {
+            if (!byCode.has(c)) errors.push(`${cmd.verb}: the register documents ${c}, which no scanned source returns`);
+        }
+        rows.set(
+            cmd.verb,
+            [...declared]
+                .filter((c) => byCode.has(c))
+                .sort((a, b) => a - b)
+                .map((code) => ({ code, meaning: cmd.meanings[code] as string, emittedIn: byCode.get(code) ?? [] })),
+        );
+    }
+    errors.push(...checkPairs(root, rows, pairs));
+    return { rows, pairs, errors };
+}
+
+export function render(reg: Register): string {
+    const out: string[] = [
+        '---',
+        'stability: beta',
+        'keep-beta-until: 2027-01-14',
+        '---',
+        '',
+        `<!-- ${generatedBy('build_exit_code_register')} -->`,
+        '',
+        '# Exit-code register',
+        '',
+        '> The exit codes a consumer can script against for `init`, `sync`, `doctor` and',
+        '> `uninstall`. The set of codes is scanned from the code that returns them and',
+        '> reconciled against the meanings on every regeneration, so a code listed here',
+        '> is one the command returns today. Regenerate with',
+        '> `./scripts-run src/scripts/build_exit_code_register`; the drift check is',
+        '> `tests/scripts/build_exit_code_register.test.ts`.',
+        '',
+    ];
+    for (const [verb, rows] of reg.rows) {
+        out.push(`## \`${verb}\``, '', '| Code | Meaning | Emitted in |', '|---|---|---|');
+        for (const r of rows) {
+            out.push(`| \`${r.code}\` | ${r.meaning} | ${r.emittedIn.map((e) => (e.startsWith('via ') ? e : `\`${e}\``)).join(', ')} |`);
+        }
+        out.push('');
+    }
+    if (reg.pairs.length > 0) {
+        out.push(
+            '## Pairs that must agree',
+            '',
+            '> Two surfaces reporting on one state. The named test pins each exact',
+            '> code by driving both surfaces over one tree; this generator checks',
+            '> that the register still documents each paired code and that the test',
+            '> still carries each assertion, so deleting or commenting one out fails',
+            '> the build.',
+            '',
+            '> **Read each row one way only.** The pair licenses "this state ⇒ these',
+            '> codes", never the converse. A code may have other causes — `doctor` 1',
+            '> is "drift OR a failing check", and a tree can be at 1 for a reason the',
+            '> pair says nothing about.',
+            '',
+            '> **What the generator does not catch:** a test skipped rather than',
+            '> deleted (`vitest run` exits 0 on a skip; the diff gate',
+            '> `check_test_weakening` is what sees one being added), and an assertion',
+            '> that moved to another case in the same file, because the match is',
+            '> file-wide.',
+            '',
+            '| State | Surfaces | Asserted in |',
+            '|---|---|---|',
+        );
+        for (const p of reg.pairs) {
+            const surfaces = p.surfaces.map((s) => `\`${s.verb}\` → \`${s.code}\``).join(' · ');
+            out.push(`| ${p.state} | ${surfaces} | \`${p.assertedIn}\` |`);
+        }
+        out.push('');
+    }
+    return `${out.join('\n').trimEnd()}\n`;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), root: string = REPO): number {
+    const check = argv.includes('--check');
+    const unknown = argv.filter((a) => a !== '--check');
+    if (unknown.length > 0) {
+        process.stderr.write(`build_exit_code_register: unknown argument(s): ${unknown.join(' ')}\n`);
+        return 2;
+    }
+    const reg = build(root);
+    if (reg.errors.length > 0) {
+        process.stderr.write(`❌  build_exit_code_register: the scan and the register disagree:\n`);
+        for (const e of reg.errors) process.stderr.write(`    ${e}\n`);
+        return 1;
+    }
+    const text = render(reg);
+    const target = path.join(root, OUT_REL);
+    const current = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+    if (check) {
+        if (current !== text) {
+            process.stderr.write(
+                `❌  ${OUT_REL} is stale — run ./scripts-run src/scripts/build_exit_code_register\n`,
+            );
+            return 1;
+        }
+        return 0;
+    }
+    if (current !== text) fs.writeFileSync(target, text);
+    process.stdout.write(`✅  ${OUT_REL} ${current === text ? 'up to date' : 'written'}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}

package/src/scripts/build_proof.ts

@@ -229,6 +229,26 @@ function render(): string {
         L.push(`| ${e.claim.replace(/\|/g, '\\|').slice(0, 110)} | ${why} |`);
     }
     L.push('');
+    // A finished in-repo reading of a consumer-facing mechanism is neither in
+    // the backed total above nor in the debt below; listing it with the
+    // evidence that would promote it keeps it from reading as either.
+    const measuredInRepo = entries.filter((e) => e.status === 'measured-in-repo');
+    if (measuredInRepo.length > 0) {
+        L.push('### Measured in this repository, not yet where the consumer stands');
+        L.push('');
+        L.push(`**${measuredInRepo.length}** claim(s) about what a shipped install does rest on a finished`);
+        L.push("measurement taken in the maintainer tree. They are not counted as backed: nothing");
+        L.push("ran on a consumer's machine. Each names the evidence that would promote it.");
+        L.push('');
+        L.push('| Claim id | Measured on | Promoted by |');
+        L.push('|---|---|---|');
+        for (const e of measuredInRepo) {
+            const on = e.measured_on.replace(/\|/g, '\\|');
+            const by = e.promotion_evidence.replace(/\|/g, '\\|');
+            L.push(`| \`${e.id}\` | ${on} | ${by} |`);
+        }
+        L.push('');
+    }
     L.push('Artefact counts in public prose (skills, commands, governed rules,');
     L.push('guidelines, personas) are **generated from source and CI-drift-checked**:');
     L.push('`update_counts.ts` writes the numbers, `check_artefact_count_messaging.ts`');
@@ -456,9 +476,11 @@ function render(): string {
         const ledger = [...load_ledger().values()].sort((a, b) => a.id.localeCompare(b.id));
         const backed = ledger.filter((e) => e.status === 'backed').length;
         const nulls = ledger.filter((e) => e.status === 'resolved-null').length;
+        const measured = ledger.filter((e) => e.status === 'measured-in-repo').length;
         L.push(
             `**Axis 2 — evidence form per public claim.** ${ledger.length} ledger entries · ` +
-                `${backed} backed · ${ledger.length - backed - nulls} unbacked inventory · ` +
+                `${backed} backed · ${measured} measured-in-repo · ` +
+                `${ledger.length - backed - nulls - measured} unbacked inventory · ` +
                 `${nulls} resolved-null.`,
         );
         L.push('');