@brighterly/lib-fe-codestyle 1.0.0 → 1.0.1

package/dist/invariants/run.js

@@ -1,746 +0,0 @@
-/**
- * The invariants runner — `run(options)`.
- *
- * This is land-app's `invariants/cli.mts` with four hardcoded constants lifted into
- * arguments (scan roots, rule sources, the spec dir/project, the README path) and the rule
- * list, config and fixtures injected. Nothing else was redesigned: the argv surface, the
- * self-test gate, the caches, the suppression grammar, severity resolution, the reporter
- * and the exit codes are the originals.
- *
- * Exit codes:
- *   0 — no error-level violations
- *   1 — at least one error-level violation
- *   2 — the validator itself failed
- */
-import { execSync, spawnSync } from 'child_process';
-import { existsSync, readFileSync } from 'fs';
-import { resolve } from 'path';
-import { walk, matchesAny, createReader, parseIgnores, stripCodeComments, findDanglingRuleRefs, findForbiddenSuppressions, resolveFindingLevel, knownRuleIds, levelOverrideOf, toRelative, } from './util.js';
-import { runSelfTest } from './self-test.js';
-export const run = async (options) => {
-    const { root, rules, linterOwnedRules, scanRoots, ruleSources, vitestProject, specDir, readmePath, fixtures, extraChecks, selfTestSkip } = options;
-    const { allowlists, levels, retired, unmaintained } = options.config;
-    const settings = options.config.settings ?? {};
-    const configFile = options.configFile ?? 'invariants/config.mts';
-    const exit = options.exit ?? process.exit;
-    const baseRead = createReader(root);
-    // Rule ids are allocated across the shared pack AND every consuming app. Nothing
-    // namespaces them, so two sources CAN pick the same number — and a duplicate id is
-    // silently destructive: allowlists, `levels` and `invariant-ignore` all dereference an
-    // id, so an exemption written for one rule would suppress the other. Fail loudly instead.
-    {
-        const seen = new Map();
-        for (const r of rules)
-            seen.set(r.id, (seen.get(r.id) ?? 0) + 1);
-        const dupes = [...seen.entries()].filter(([, n]) => n > 1).map(([id]) => id);
-        if (dupes.length) {
-            console.error(`validate-invariants: duplicate rule id(s) ${dupes.join(', ')} — an allowlist or invariant-ignore naming one would silently suppress the other. Renumber the app-local rule; \`--list\` prints every id in use.`);
-            return exit(2);
-        }
-    }
-    // ---------------------------------------------------------------------------
-    // args
-    // ---------------------------------------------------------------------------
-    const argv = options.argv ?? process.argv.slice(2);
-    const has = (flag) => argv.includes(flag);
-    const valueOf = (name) => {
-        const hit = argv.find(a => a.startsWith(`--${name}=`));
-        return hit ? hit.slice(name.length + 3) : null;
-    };
-    const opts = {
-        staged: has('--staged'),
-        json: has('--json'),
-        rule: valueOf('rule'),
-        // --family=E: every rule of one family over the whole repo. A family gate (e.g.
-        // `pnpm validate:e2e`) runs this way, so it is one visible command in pre-commit /
-        // CI — not a side effect of --staged (which sees only this commit's files).
-        family: valueOf('family'),
-        selfTest: has('--self-test'),
-        // --stdin --file=<path>: check the content on stdin AS IF it were that file. This
-        // is the PreToolUse hook's entry point — the file is not on disk yet.
-        stdin: has('--stdin'),
-        file: valueOf('file'),
-        // The vitest half (invariants/specs) resolves real modules, so it costs a vitest
-        // boot. A full run includes it; --staged, --rule=, --family= and --stdin skip it,
-        // because the pre-commit hook runs `pnpm test` right after, a single-rule run is
-        // a dev loop, and the hook is per-file.
-        vitest: !has('--staged') && !has('--no-vitest') && !valueOf('rule') && !valueOf('family') && !has('--stdin'),
-    };
-    // stdin mode runs: every FileRule whose scope matches `--file` (only that family's, with
-    // --family=), plus the IG* meta rules.
-    // It skips: the rule self-test and the vitest half (per-file latency), and every
-    // `once` rule (they read the repo, not the candidate) — so a PASS here is narrower
-    // than a PASS from a full run.
-    if (opts.stdin && !opts.file) {
-        console.error('validate-invariants: --stdin requires --file=<repo-relative path>');
-        return exit(2);
-    }
-    if (opts.file && !opts.stdin) {
-        console.error('validate-invariants: --file= is only meaningful with --stdin');
-        return exit(2);
-    }
-    if (opts.stdin && opts.staged) {
-        console.error('validate-invariants: --stdin and --staged are exclusive');
-        return exit(2);
-    }
-    if (opts.stdin && process.stdin.isTTY) {
-        console.error('validate-invariants: --stdin expects content on stdin, not a terminal');
-        return exit(2);
-    }
-    let stdinContent = null;
-    if (opts.stdin) {
-        try {
-            stdinContent = readFileSync(0, 'utf8');
-        }
-        catch (e) {
-            console.error(`validate-invariants: could not read stdin — ${e.message}`);
-            return exit(2);
-        }
-        // Empty is a plumbing failure, not a clean file: the rules would invent findings
-        // about content that was never sent.
-        if (stdinContent === '') {
-            console.error('validate-invariants: --stdin received no content');
-            return exit(2);
-        }
-    }
-    // Normalise: './x' or an absolute path under the repo matches no rule scope and no
-    // unmaintained glob, so the run would print PASS over content it never checked.
-    const stdinFile = opts.stdin ? toRelative(root, opts.file) : null;
-    /** In stdin mode the candidate file reads from stdin; everything else from disk. */
-    const read = (rel) => (stdinFile !== null && rel === stdinFile ? stdinContent : baseRead(rel));
-    // ---------------------------------------------------------------------------
-    // --list — the rule inventory as markdown, generated from the rules themselves
-    // so invariants/README.md cannot drift from what actually runs
-    // ---------------------------------------------------------------------------
-    const specTitles = () => {
-        const out = [];
-        for (const file of walk(root, specDir)) {
-            if (!file.endsWith('.test.ts'))
-                continue;
-            const src = read(file) || '';
-            const suite = (src.match(/describe\('([^']+)'/) || [])[1] || file;
-            const id = (suite.match(/^([A-Z]\d+)/) || [])[1] || '—';
-            const assertions = [...src.matchAll(/\n\s{2}it\('([^']+)'/g)].flatMap(m => (m[1] ? [m[1]] : []));
-            out.push({ id, suite: suite.replace(/^[A-Z]\d+\s*—\s*/, ''), file, assertions });
-        }
-        return out.sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
-    };
-    const renderInventory = () => {
-        const byId = (a, b) => a.id.localeCompare(b.id, undefined, { numeric: true });
-        const lines = [];
-        lines.push('### Vector 1 — plain checks (regex, or a real AST where regex would lie)');
-        lines.push('');
-        lines.push('| Rule | Level | Checks | Where it looks |');
-        lines.push('|---|---|---|---|');
-        for (const r of [...rules].sort(byId)) {
-            const level = levelOverrideOf(levels, r.id) ?? r.level;
-            const scope = r.scope.map(sc => `\`${sc}\``).join(', ');
-            lines.push(`| **${r.id}** | ${level} | ${r.title} | ${scope} |`);
-        }
-        lines.push('');
-        lines.push('### Vector 2 — vitest specs (need the real modules, not their text)');
-        lines.push('');
-        lines.push('| Rule | Checks | Assertions |');
-        lines.push('|---|---|---|');
-        for (const s of specTitles()) {
-            lines.push(`| **${s.id}** | ${s.suite} | ${s.assertions.map(a => `• ${a}`).join('<br>')} |`);
-        }
-        if (specTitles().some(s => s.id === '—')) {
-            lines.push('');
-            lines.push('_A `—` row is plumbing, not a rule: the spec guards the engine and has no rule id. `knownRuleIds()` filters exactly that placeholder out of the live set, so it is not a citable ID and must stay `—`._');
-        }
-        lines.push('');
-        lines.push('### Vector 3 — built-in ESLint rules (configured, not implemented)');
-        lines.push('');
-        lines.push('| Rule | Level | ESLint rule | Checks |');
-        lines.push('|---|---|---|---|');
-        if (!linterOwnedRules.length) {
-            lines.push('| — | — | — | _none configured — see the `retired` registry in `config.mts` for why_ |');
-        }
-        for (const r of linterOwnedRules) {
-            lines.push(`| **${r.id}** | ${r.level} | \`${r.eslintRule}\` | ${r.title} |`);
-        }
-        lines.push('');
-        lines.push(`_${rules.length} rules + ${specTitles().length} specs + ${linterOwnedRules.length} linter rule(s). Regenerate this section with \`pnpm validate:invariants --list\`._`);
-        return lines.join('\n');
-    };
-    if (has('--list')) {
-        console.log(renderInventory());
-        return exit(0);
-    }
-    // ---------------------------------------------------------------------------
-    // --rules-doc=<name> — an agent-facing rules file (e.g. .claude/rules/e2e.md),
-    // rendered from the rule objects into the prose template at
-    // invariants/rules/<name>-rules.doc.md so the text cannot drift from what is
-    // enforced. The consumer's sync-docs script writes the output where it belongs.
-    // ---------------------------------------------------------------------------
-    const renderRulesDoc = (name) => {
-        const templatePath = `invariants/rules/${name}-rules.doc.md`;
-        const template = read(templatePath);
-        if (template === null) {
-            console.error(`validate-invariants: no template at ${templatePath}`);
-            return null;
-        }
-        const family = name === 'e2e' ? 'E' : name.toUpperCase();
-        const byId = (a, b) => a.id.localeCompare(b.id, undefined, { numeric: true });
-        const own = rules.filter(r => r.id.startsWith(family)).sort(byId);
-        const linted = linterOwnedRules.filter(l => l.eslintRule.startsWith('playwright/')).sort(byId);
-        // Pipes break the table; a bare `<key>` is eaten by any HTML renderer of the file.
-        const cell = (s) => s.replace(/\|/g, '\\|').replace(/</g, '&lt;');
-        const table = [
-            '## Rules',
-            '',
-            '| ID | Violation | Why | Fix |',
-            '|---|---|---|---|',
-            ...own.map(r => `| **${r.id}** | ${cell(r.title)} | ${cell(r.why)} | ${cell(r.fix)} |`),
-            '',
-            '## Playwright hygiene (eslint-plugin-playwright, declared as L-rules)',
-            '',
-            '| ID | ESLint rule | Why |',
-            '|---|---|---|',
-            ...linted.map(l => `| **${l.id}** | \`${l.eslintRule}\` | ${cell(l.why)} |`),
-        ];
-        return template.replace('<!-- rules -->', table.join('\n'));
-    };
-    if (valueOf('rules-doc')) {
-        const doc = renderRulesDoc(valueOf('rules-doc'));
-        if (doc === null)
-            return exit(2);
-        console.log(doc);
-        return exit(0);
-    }
-    // ---------------------------------------------------------------------------
-    // self-test — proves each rule still fires on a known violation
-    // ---------------------------------------------------------------------------
-    // A rule that has silently stopped matching reports nothing — which is
-    // indistinguishable from a clean codebase. So the scan alone can print PASS while
-    // a rule is dead, and R12 proved the inverse too (a passing fixture while the rule
-    // was wrong about real code). Both halves are needed, so a FULL run does both.
-    //
-    // Skipped only where it would be noise rather than signal: --rule= is a dev loop,
-    // and --staged is the pre-commit path, where it runs only if the commit actually
-    // touches the validator's own sources.
-    /**
-     * What this commit stages. `present` is what `--diff-filter=ACMR` used to give — added, copied,
-     * modified, the new side of a rename — and `gone` is what it hid: deleted paths and the old side
-     * of a rename. A `once` rule has to fire on `gone` too: deleting the one file a registry rule
-     * models is exactly the change it exists for, and with the file no longer a candidate it
-     * reached CI unseen.
-     */
-    const stagedChanges = (() => {
-        let cached = null;
-        return () => {
-            if (cached)
-                return cached;
-            const present = [];
-            const gone = [];
-            for (const line of execSync('git diff --staged --name-status -M', { cwd: root, encoding: 'utf8' }).split('\n')) {
-                const [status = '', ...paths] = line.split('\t').map(s => s.trim());
-                const first = paths[0];
-                const last = paths[paths.length - 1];
-                if (!status || !first || !last)
-                    continue;
-                if (status.startsWith('D'))
-                    gone.push(first);
-                else if (status.startsWith('R')) {
-                    gone.push(first);
-                    present.push(last);
-                }
-                else
-                    present.push(last);
-            }
-            cached = { present: present.filter(f => existsSync(resolve(root, f))), gone };
-            return cached;
-        };
-    })();
-    const stagedTouchesRules = () => {
-        if (!opts.staged)
-            return false;
-        try {
-            return stagedChanges().present.some(f => ruleSources.some(p => f.startsWith(p)));
-        }
-        catch {
-            return false;
-        }
-    };
-    if (opts.family && opts.rule) {
-        console.error('validate-invariants: --family= and --rule= are exclusive');
-        return exit(2);
-    }
-    if (opts.family && !rules.some(r => r.id.startsWith(opts.family))) {
-        console.error(`validate-invariants: unknown family "${opts.family}". Known: ${[...new Set(rules.map(r => r.id.replace(/\d+$/, '')))].join(', ')}`);
-        return exit(2);
-    }
-    // A full run — no --staged, no --rule=, no --family=, no --stdin — verifies the rules before trusting them.
-    const isFullRun = !opts.staged && !opts.rule && !opts.stdin && !opts.family;
-    const explicitSelfTest = has('--self-test');
-    if (explicitSelfTest && !fixtures) {
-        console.error('validate-invariants: --self-test needs fixtures; pass `fixtures` to run()');
-        return exit(2);
-    }
-    if (fixtures && (explicitSelfTest || isFullRun || stagedTouchesRules())) {
-        const { failures, checked } = await runSelfTest({ rules, fixtures, extraChecks, skip: selfTestSkip });
-        // The README is the thing a developer or an agent reads to learn what is
-        // enforced. A stale inventory there is worse than none: it states coverage we
-        // do not have. Regenerate with `pnpm validate:invariants --list`.
-        const readme = read(readmePath);
-        if (readme === null) {
-            failures.push(`${readmePath} is missing — it is the entry point for this directory`);
-        }
-        else {
-            const between = readme.match(/<!-- BEGIN rule-inventory[^>]*-->\n([\s\S]*?)<!-- END rule-inventory -->/);
-            if (!between) {
-                failures.push(`${readmePath} has no <!-- BEGIN rule-inventory --> block`);
-            }
-            else if ((between[1] ?? '').trim() !== renderInventory().trim()) {
-                failures.push(`${readmePath} rule inventory is out of date — regenerate it with \`pnpm validate:invariants --list\` and paste it between the markers`);
-            }
-        }
-        console.log();
-        const label = explicitSelfTest ? 'validate-invariants --self-test' : 'rule self-test';
-        console.log(`  ${label} — ${checked.length} rule(s) + plumbing`);
-        if (failures.length) {
-            for (const f of failures)
-                console.log(`  ✗  ${f}`);
-            console.log(`\n✗ ${failures.length} self-test failure(s).`);
-            return exit(1);
-        }
-        console.log('  ✅ every rule fires on its violating fixture and stays quiet on the clean one.');
-        // Explicit --self-test is the whole job; the implicit run continues into the scan.
-        if (explicitSelfTest)
-            return exit(0);
-    }
-    // ---------------------------------------------------------------------------
-    // file set
-    // ---------------------------------------------------------------------------
-    const scanned = scanRoots.flatMap((d) => walk(root, d));
-    // Unmaintained areas come out of `allFiles`, not just `candidates`: rules resolve
-    // each other's files through allFiles (R10 walks it to find a :next-step target,
-    // B1 walks it for a booking wrap, query.mts walks it for Views). Filtering only
-    // the candidate set would keep an excluded file reachable as some other rule's
-    // answer — the exclusion has to be invisible everywhere or it is not one.
-    const UNMAINTAINED_PATHS = Object.keys(unmaintained.paths);
-    let allFiles = UNMAINTAINED_PATHS.length
-        ? scanned.filter((f) => !matchesAny(f, UNMAINTAINED_PATHS))
-        : scanned;
-    let unmaintainedCount = scanned.length - allFiles.length;
-    const activeRules = opts.rule
-        ? rules.filter(r => r.id === opts.rule)
-        : opts.family ? rules.filter(r => r.id.startsWith(opts.family)) : rules;
-    if (opts.rule && activeRules.length === 0) {
-        console.error(`validate-invariants: unknown rule "${opts.rule}". Known: ${rules.map(r => r.id).join(', ')}`);
-        return exit(2);
-    }
-    let candidates = allFiles;
-    // --family= narrows the candidates to what its rules can see, so the header's file count
-    // describes the family's reach ("6 rules (family E) over 0 file(s)" while the tree does
-    // not exist yet), not the whole repo.
-    if (opts.family && !opts.staged && !opts.stdin) {
-        candidates = allFiles.filter(f => activeRules.some(r => matchesAny(f, r.scope)));
-        // …and so must the exclusion count: "not checked: 60 file(s)" under --family= would be
-        // counting files no family rule scopes, which reads as coverage this family never had.
-        // …and a rule that declares `seesUnmaintained` does check them, so it does not count here.
-        unmaintainedCount = scanned.filter(f => matchesAny(f, UNMAINTAINED_PATHS) && activeRules.some(r => !r.seesUnmaintained && matchesAny(f, r.scope))).length;
-    }
-    // In --staged mode the exclusion count must describe THIS COMMIT, not the repo: a hook
-    // that prints "not checked: 35 file(s)" while the developer staged three of them reads
-    // as background noise. Staging only excluded files is the case that has to be loud.
-    let stagedExcluded = 0;
-    /** Every staged path — the unmaintained ones and the deleted ones included: what decides whether a `once` rule runs. */
-    let stagedTouched = [];
-    let stagedGone = 0;
-    if (opts.staged) {
-        try {
-            const { present, gone } = stagedChanges();
-            candidates = present.filter(f => !matchesAny(f, UNMAINTAINED_PATHS));
-            stagedExcluded = present.length - candidates.length;
-            stagedTouched = [...present, ...gone];
-            stagedGone = gone.length;
-        }
-        catch (e) {
-            console.error(`validate-invariants: could not read the staged file list — ${e.message}`);
-            return exit(2);
-        }
-    }
-    if (opts.stdin) {
-        const f = stdinFile;
-        // A skipped file must say so, in the same shape the caller asked for — a bare PASS
-        // over an unchecked path is the failure this mode must never produce.
-        const skip = (reason) => {
-            if (opts.json)
-                console.log(JSON.stringify({ ok: true, scanned: 0, errors: 0, warnings: 0, vitest: { ran: false }, findings: [], skipped: { file: f, reason } }, null, 2));
-            else
-                console.log(`  not checked: ${f} — ${reason}`);
-            return exit(0);
-        };
-        if (matchesAny(f, UNMAINTAINED_PATHS))
-            return skip(`unmaintained in ${configFile}`);
-        if (!activeRules.some(r => matchesAny(f, r.scope)))
-            return skip(`no ${opts.family ? `${opts.family}-family ` : ''}rule scopes this path`);
-        candidates = [f];
-        if (!allFiles.includes(f))
-            allFiles = [...allFiles, f];
-    }
-    // ---------------------------------------------------------------------------
-    // run
-    // ---------------------------------------------------------------------------
-    const findings = []; // { ruleId, level, file, line, message }
-    const ignoreProblems = [];
-    // one comment-strip per file, shared by every rule
-    const strippedCache = new Map();
-    const strippedOf = (file, source) => {
-        if (!strippedCache.has(file))
-            strippedCache.set(file, stripCodeComments(source, file));
-        return strippedCache.get(file);
-    };
-    // one ignore-parse per file, shared by every rule
-    const ignoreCache = new Map();
-    const ignoresFor = (file) => {
-        if (!ignoreCache.has(file)) {
-            // The consumer's self-test file holds literal `invariant-ignore:` strings as
-            // fixture DATA — parsing them would report the fixtures themselves (IG0/IG1).
-            const src = file === settings.selfTestFile ? null : read(file);
-            ignoreCache.set(file, src === null ? { suppressions: new Map(), unreasoned: [], comments: [] } : parseIgnores(src));
-        }
-        return ignoreCache.get(file);
-    };
-    for (const rule of activeRules) {
-        const override = levelOverrideOf(levels, rule.id);
-        const level = override ?? rule.level;
-        if (level === 'off')
-            continue;
-        const allowed = allowlists[rule.id] ?? {};
-        // `once` rules read their own inputs — run them a single time if any file
-        // they depend on is in scope, instead of once per matching file.
-        if (rule.once) {
-            if (opts.stdin)
-                continue; // a once rule reads the repo itself; the hook is per-file
-            // Staged mode asks the whole staged set: a deleted file, or one under an unmaintained glob,
-            // is no candidate but is still a change to the tree the rule reads.
-            const triggers = opts.staged ? stagedTouched : candidates;
-            if (!triggers.some(f => matchesAny(f, rule.scope)))
-                continue;
-            let raw;
-            try {
-                raw = (await rule.check({ file: rule.scope[0], source: '', code: '', read, allFiles, scanned: rule.seesUnmaintained ? scanned : undefined, settings })) || [];
-            }
-            catch (e) {
-                console.error(`validate-invariants: rule ${rule.id} crashed — ${e.message}`);
-                return exit(2);
-            }
-            for (const v of raw) {
-                const { suppressions } = ignoresFor(v.file);
-                if (!rule.noIgnore && suppressions.get(v.line)?.has(rule.id))
-                    continue;
-                const resolved = resolveFindingLevel(rule.level, override, v.level);
-                if (resolved === 'off')
-                    continue;
-                findings.push({ ...v, ruleId: rule.id, level: resolved });
-            }
-            continue;
-        }
-        for (const file of candidates) {
-            if (!matchesAny(file, rule.scope))
-                continue;
-            if (rule.exclude && matchesAny(file, rule.exclude))
-                continue;
-            if (allowed[file])
-                continue;
-            const source = read(file);
-            if (source === null)
-                continue;
-            const code = strippedOf(file, source);
-            let raw;
-            try {
-                // Always await, never dispatch on rule.async: a Promise-returning check whose author
-                // forgot the flag was iterated AS a Promise — zero findings, exit 2, and nothing
-                // pointing at the cause. Awaiting a sync value costs nothing.
-                raw = (await rule.check({ file, source, code, read, allFiles, scanned: rule.seesUnmaintained ? scanned : undefined, settings })) ?? [];
-            }
-            catch (e) {
-                console.error(`validate-invariants: rule ${rule.id} crashed on ${file} — ${e.message}`);
-                return exit(2);
-            }
-            const { suppressions } = ignoresFor(file);
-            for (const v of raw) {
-                if (!rule.noIgnore && suppressions.get(v.line)?.has(rule.id))
-                    continue;
-                const resolved = resolveFindingLevel(rule.level, override, v.level);
-                if (resolved === 'off')
-                    continue;
-                findings.push({ ...v, ruleId: rule.id, level: resolved });
-            }
-        }
-    }
-    // IG0 — unreasoned ignore comments are themselves a finding. Scans `.mts` too:
-    // the validator's own sources are the likeliest place to grow a suppression, and
-    // exempting the tool from its own reason requirement is the backdoor IG0 exists
-    // to close. Honours `allowlists.IG0` so self-test fixture strings can opt out.
-    const ignoreScanRe = /\.(m?ts|vue|mjs|js)$/;
-    const ig0Allowed = allowlists.IG0 ?? {};
-    /** Every `invariant-ignore` comment in the candidate set, minus one meta rule's allowlist — IG1 and IG2 read the same comments. */
-    const ignoreCommentsExcept = (allowed) => candidates.filter(f => ignoreScanRe.test(f) && !allowed[f])
-        .flatMap(f => (read(f)?.includes('invariant-ignore') ? ignoresFor(f).comments.map(cm => ({ file: f, ...cm })) : []));
-    for (const file of candidates) {
-        if (!ignoreScanRe.test(file))
-            continue;
-        if (ig0Allowed[file])
-            continue;
-        const src = read(file);
-        if (src === null || !src.includes('invariant-ignore'))
-            continue;
-        for (const u of ignoresFor(file).unreasoned) {
-            ignoreProblems.push({
-                ruleId: 'IG0', level: 'error', file, line: u.line,
-                message: `invariant-ignore: ${u.ids.join(', ')} has no reason — an unexplained exemption silently deletes the rule`,
-            });
-        }
-    }
-    // IG2 — a suppression naming a `noIgnore` rule. The check above already refused to
-    // honour it (rule.noIgnore skips the suppression lookup); report the attempt so it
-    // cannot pass as a reviewed exemption. Honours `allowlists.IG2` for the self-test's
-    // fixture strings.
-    {
-        const noIgnoreIds = new Set(rules.filter(r => r.noIgnore).map(r => r.id));
-        for (const v of findForbiddenSuppressions(ignoreCommentsExcept(allowlists.IG2 ?? {}), noIgnoreIds))
-            ignoreProblems.push({ ruleId: 'IG2', level: 'error', ...v });
-    }
-    findings.push(...ignoreProblems);
-    // IG1 — references to rule IDs that no longer exist. Three sinks dereference an
-    // ID (allowlists, levels, invariant-ignore) and none of them used to check it
-    // resolved, so renumbering a rule silently voided every suppression naming it.
-    // Runs on the FULL rule set, never the --rule= subset: a stale reference is a
-    // property of the config, not of whichever rule is being debugged.
-    {
-        const live = knownRuleIds({
-            fileScan: rules.map(r => r.id),
-            specs: specTitles().map(sp => sp.id),
-            linter: linterOwnedRules.map(r => r.id),
-            // The meta rules are addressable too, so they must count as live.
-            meta: ['IG0', 'IG1', 'IG2'],
-        });
-        const ignores = ignoreCommentsExcept(allowlists.IG1 ?? {});
-        for (const v of findDanglingRuleRefs({
-            live, retired, allowlists, levels, ignores,
-            configFile,
-            configSource: read(configFile) ?? undefined,
-            pathExists: p => read(p) !== null,
-        })) {
-            findings.push({ ruleId: 'IG1', level: 'error', ...v });
-        }
-    }
-    // ---------------------------------------------------------------------------
-    // module-resolving half — invariants/specs/*.test.ts
-    // ---------------------------------------------------------------------------
-    const runVitestInvariants = () => {
-        const bin = resolve(root, 'node_modules/.bin/vitest');
-        const args = ['run', '--project', vitestProject, specDir, '--reporter=dot'];
-        const r = existsSync(bin)
-            ? spawnSync(bin, args, { cwd: root, encoding: 'utf8' })
-            : spawnSync('npx', ['vitest', ...args], { cwd: root, encoding: 'utf8' });
-        return { ok: r.status === 0, output: `${r.stdout || ''}${r.stderr || ''}`.trim() };
-    };
-    // A consumer with no specs yet (a freshly wired app) must not fail on
-    // `vitest --project <name>` finding nothing — the spec half only runs when
-    // the spec dir actually holds tests.
-    const hasSpecs = walk(root, specDir).some(f => f.endsWith('.test.ts'));
-    const vitestResult = opts.vitest && hasSpecs ? runVitestInvariants() : null;
-    // ---------------------------------------------------------------------------
-    // report
-    // ---------------------------------------------------------------------------
-    const errors = findings.filter(f => f.level === 'error');
-    const warns = findings.filter(f => f.level === 'warn');
-    if (opts.json) {
-        console.log(JSON.stringify({
-            ok: errors.length === 0 && (vitestResult ? vitestResult.ok : true),
-            scanned: candidates.length,
-            errors: errors.length,
-            warnings: warns.length,
-            vitest: vitestResult ? { ran: true, ok: vitestResult.ok } : { ran: false },
-            findings,
-        }, null, 2));
-        return exit(errors.length || (vitestResult && !vitestResult.ok) ? 1 : 0);
-    }
-    // ---------------------------------------------------------------------------
-    // report
-    //
-    // Layout is deliberate: severity first, then where, then which rule, then what
-    // happened, then what to do about it — with a hard rule between issues so a long
-    // run stays scannable instead of turning into a wall of text.
-    // ---------------------------------------------------------------------------
-    /** Colour only when a human is watching: NO_COLOR and pipes both disable it. */
-    const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
-    const paint = (code) => (text) => (useColor ? `\u001B[${code}m${text}\u001B[0m` : text);
-    const c = {
-        red: paint('31'),
-        redBold: paint('1;31'),
-        yellow: paint('33'),
-        yellowBold: paint('1;33'),
-        green: paint('32'),
-        cyan: paint('36'),
-        bold: paint('1'),
-        dim: paint('2'),
-    };
-    const WIDTH = 78;
-    /** Wrap prose to WIDTH with a hanging indent, so long `why` text stays readable. */
-    const wrap = (text, indent) => {
-        const width = WIDTH - indent;
-        const out = [];
-        let line = '';
-        for (const word of text.split(/\s+/)) {
-            if (line && (line + ' ' + word).length > width) {
-                out.push(line);
-                line = word;
-            }
-            else {
-                line = line ? `${line} ${word}` : word;
-            }
-        }
-        if (line)
-            out.push(line);
-        return out;
-    };
-    const LABEL = {
-        error: (t) => c.redBold(t),
-        warn: (t) => c.yellowBold(t),
-        off: (t) => c.dim(t),
-    };
-    const byRule = (list) => {
-        const m = new Map();
-        for (const f of list) {
-            if (!m.has(f.ruleId))
-                m.set(f.ruleId, []);
-            m.get(f.ruleId).push(f);
-        }
-        return m;
-    };
-    const ruleById = new Map(rules.map(r => [r.id, r]));
-    /**
-     * IG0 / IG1 are NOT rules. They say nothing about the app — they are properties
-     * of the escape hatch, so they are deliberately absent from `rules`, from both
-     * rule counts, from `--rule=` and from the README's inventory. A reader browsing
-     * what is enforced about the funnel should never meet them.
-     *
-     * But a finding still has to explain itself the moment it fires, and there is no
-     * Rule object to carry the rationale — so it lives here, next to the reporter
-     * that prints it. This is the whole of their documentation; keep it self-contained.
-     */
-    const metaRuleInfo = {
-        IG0: {
-            title: 'unexplained suppression',
-            why: 'an escape hatch nobody audits is a backdoor — the run prints PASS while the invariant is not enforced, and nobody can later tell a reviewed exemption from someone making the red go away',
-            fix: 'put the reason after the ID: // invariant-ignore: R1 — the safe wrapper is the one place bare storage is allowed. Or delete the comment and fix the code.',
-        },
-        IG1: {
-            title: 'reference to a rule that does not exist',
-            why: 'the entry is inert but reads like active protection — a deleted or renumbered ID silently voids every suppression and allowlist naming it',
-            fix: 'drop the dead entry, or point it at a live rule ID — pnpm validate:invariants --list prints them',
-        },
-        IG2: {
-            title: 'suppression of a rule that cannot be suppressed',
-            why: 'a rule marked noIgnore has an AI author in scope; a plausible reason costs an AI nothing, so the escape hatch would become the default path — the comment suppresses nothing and the attempt is reported so a reviewer sees the intent',
-            fix: 'fix the code. If the rule is wrong, change it in the rulebook together with its fixture — exceptions are made in the rulebook by a human, not in the file under check',
-        },
-    };
-    /** How many findings of one rule to print in full before summarising the rest. */
-    const PER_RULE_LIMIT = 6;
-    /**
-     * One issue per block: severity, where, which rule, what happened — and the
-     * rationale once per rule rather than once per finding, because 27 copies of the
-     * same `why` is the wall of text this layout exists to avoid.
-     */
-    const printFinding = (f, rule, index, total, withRationale) => {
-        const severity = f.level === 'error' ? LABEL.error('ERROR') : LABEL.warn('WARN ');
-        const counter = total > 1 ? c.dim(` ${index}/${total}`) : '';
-        console.log(c.dim('─'.repeat(WIDTH)));
-        console.log(`${severity}  ${c.bold(f.ruleId)}${counter}  ${rule?.title ?? 'unattributed finding'}`);
-        console.log(`       ${c.cyan(`${f.file}:${f.line}`)}`);
-        console.log();
-        for (const [i, l] of wrap(f.message, 9).entries())
-            console.log(`  ${i === 0 ? c.dim('what  ') : '      '} ${l}`);
-        if (rule && withRationale) {
-            for (const [i, l] of wrap(rule.why, 9).entries())
-                console.log(`  ${i === 0 ? c.dim('why   ') : '      '} ${c.dim(l)}`);
-            for (const [i, l] of wrap(rule.fix, 9).entries())
-                console.log(`  ${i === 0 ? c.dim('fix   ') : '      '} ${c.green(l)}`);
-        }
-        console.log();
-    };
-    const printGroup = (list) => {
-        for (const [id, items] of byRule(list)) {
-            const rule = ruleById.get(id) ?? metaRuleInfo[id];
-            const shown = items.slice(0, PER_RULE_LIMIT);
-            shown.forEach((f, i) => printFinding(f, rule, i + 1, items.length, i === 0));
-            if (items.length > shown.length) {
-                const rest = items.length - shown.length;
-                console.log(c.dim('─'.repeat(WIDTH)));
-                // `--rule=` only accepts real rule IDs, so do not offer it for IG0/IG1.
-                console.log(ruleById.has(id)
-                    ? `       ${c.dim(`+ ${rest} more ${id} finding(s) — see them all with`)} ${c.bold(`pnpm validate:invariants --rule=${id}`)}`
-                    : `       ${c.dim(`+ ${rest} more ${id} finding(s)`)}`);
-                console.log();
-            }
-        }
-    };
-    const engines = [
-        `${activeRules.length} rule${activeRules.length === 1 ? '' : 's'}${opts.family ? ` (family ${opts.family})` : ''}`,
-        opts.vitest ? `${specTitles().length} module-resolving specs` : null,
-    ].filter(Boolean).join(c.dim(' + '));
-    console.log();
-    console.log(c.bold('  validate-invariants') + c.dim(` — ${engines} over ${candidates.length} file(s)${opts.staged ? ', staged only' : ''}`));
-    // Printed on EVERY run, not behind a flag: a silent exclusion reads as coverage.
-    {
-        const funnelKeys = opts.stdin || opts.family ? [] : Object.keys(unmaintained.funnels);
-        const fileCount = opts.staged ? stagedExcluded : opts.stdin ? 0 : unmaintainedCount;
-        const parts = [
-            fileCount > 0 ? (opts.staged ? `${fileCount} of your staged file(s)` : `${fileCount} file(s)`) : '',
-            funnelKeys.length > 0 ? `funnel${funnelKeys.length > 1 ? 's' : ''} ${funnelKeys.join(', ')}` : '',
-        ].filter(Boolean).join(' + ');
-        if (parts)
-            console.log(c.dim(`  not checked: ${parts} — unmaintained in ${configFile}`));
-        // Staged nothing BUT excluded files: the PASS below covers zero of this commit's work.
-        if (opts.staged && stagedExcluded > 0 && candidates.length === 0) {
-            console.log(c.dim('  every staged file is excluded — this run checked nothing'));
-        }
-        if (opts.staged && stagedGone > 0) {
-            console.log(c.dim(`  ${stagedGone} staged deletion(s) — a once rule that scopes a deleted path still ran`));
-        }
-    }
-    console.log();
-    if (errors.length)
-        printGroup(errors);
-    if (warns.length)
-        printGroup(warns);
-    if (vitestResult && !vitestResult.ok) {
-        console.log(c.dim('─'.repeat(WIDTH)));
-        console.log(`${LABEL.error('ERROR')}  ${c.bold(specDir)}  module-resolving specs failed`);
-        console.log(`       ${c.cyan(specDir)}`);
-        console.log();
-        console.log(vitestResult.output.split('\n').map(l => c.dim(`       ${l}`)).join('\n'));
-        console.log();
-    }
-    const vitestFailed = Boolean(vitestResult && !vitestResult.ok);
-    console.log(c.dim('─'.repeat(WIDTH)));
-    if (errors.length === 0 && warns.length === 0 && !vitestFailed) {
-        console.log(`${c.green('PASS')}   all invariants hold`);
-        console.log();
-        return exit(0);
-    }
-    const totals = [
-        errors.length + (vitestFailed ? 1 : 0) > 0 ? c.red(`${errors.length + (vitestFailed ? 1 : 0)} error`) : null,
-        warns.length > 0 ? c.yellow(`${warns.length} warning`) : null,
-    ].filter(Boolean).join(c.dim(' · '));
-    if (errors.length === 0 && !vitestFailed) {
-        console.log(`${c.green('PASS')}   ${totals}${c.dim(' — nothing blocking')}`);
-        console.log();
-        return exit(0);
-    }
-    console.log(`${c.red('FAIL')}   ${totals}`);
-    // Never advertise the escape hatch to an author whose every finding is noIgnore or a
-    // meta rule — that is the move IG2 exists to forbid.
-    const suppressible = errors.some(f => { const r = ruleById.get(f.ruleId); return r !== undefined && !r.noIgnore; });
-    if (suppressible)
-        console.log(c.dim('       suppress a reviewed line with  // invariant-ignore: <RULE_ID> — <reason>'));
-    console.log();
-    return exit(1);
-};