@brighterly/lib-fe-codestyle 0.1.0

package/dist/invariants/run.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 type { Allowlists, Levels, LinterOwnedRule, RetiredRules, Rule, Unmaintained } from './types.js';
+export interface RunOptions {
+    /** Repo root. Passed, never derived — import.meta.url here resolves into node_modules. */
+    root: string;
+    rules: Rule[];
+    linterOwnedRules: LinterOwnedRule[];
+    config: {
+        allowlists: Allowlists;
+        levels: Levels;
+        retired: RetiredRules;
+        unmaintained: Unmaintained;
+        /** App-specific paths shared rules read from RuleContext.settings. */
+        settings?: Readonly<Record<string, string>>;
+    };
+    /** Directories walked for the candidate file set. */
+    scanRoots: string[];
+    /** Path prefixes whose change triggers the self-test in --staged mode. */
+    ruleSources: string[];
+    /** Vitest project name for the module-resolving half. */
+    vitestProject: string;
+    /** Directory holding the vector-2 specs. */
+    specDir: string;
+    /** README whose generated inventory must not drift. */
+    readmePath: string;
+    /** Config file a dangling allowlist/levels key is reported against. */
+    configFile?: string;
+    /** Fixtures for --self-test, keyed by rule id. Omit to skip the self-test entirely. */
+    fixtures?: Record<string, {
+        file: string;
+        bad: string;
+        good: string;
+    }>;
+    /** Repo-specific self-test assertions; each returns failure messages. */
+    extraChecks?: (() => string[] | Promise<string[]>)[];
+    /** Rule ids exempt from the fixture requirement — registry rules a fixture cannot express. */
+    selfTestSkip?: string[];
+    /** Defaults to process.argv.slice(2). Injectable so tests need no argv games. */
+    argv?: string[];
+    /** Defaults to process.exit. Injectable so tests can assert the code. */
+    exit?: (code: number) => never;
+}
+export declare const run: (options: RunOptions) => Promise<void>;

package/dist/invariants/run.js

@@ -0,0 +1,553 @@
+/**
+ * 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 } from 'fs';
+import { resolve } from 'path';
+import { walk, matchesAny, createReader, parseIgnores, stripCodeComments, findDanglingRuleRefs, resolveFindingLevel, knownRuleIds, levelOverrideOf, } 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 read = 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'),
+        selfTest: has('--self-test'),
+        // The vitest half (R3, R9, R19) resolves real modules, so it costs a vitest
+        // boot. A full run includes it; --staged and --rule= skip it, because the
+        // pre-commit hook runs `pnpm test` right after and a single-rule run is a
+        // dev loop, not a gate.
+        vitest: !has('--staged') && !has('--no-vitest') && !valueOf('rule'),
+    };
+    // ---------------------------------------------------------------------------
+    // --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>')} |`);
+        }
+        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);
+    }
+    // ---------------------------------------------------------------------------
+    // 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.
+    const stagedTouchesRules = () => {
+        if (!opts.staged)
+            return false;
+        try {
+            return execSync('git diff --staged --name-only --diff-filter=ACMR', { cwd: root, encoding: 'utf8' })
+                .split('\n').some(f => ruleSources.some(p => f.trim().startsWith(p)));
+        }
+        catch {
+            return false;
+        }
+    };
+    // A full run — no --staged, no --rule= — verifies the rules before trusting them.
+    const isFullRun = !opts.staged && !opts.rule;
+    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);
+    const allFiles = UNMAINTAINED_PATHS.length
+        ? scanned.filter((f) => !matchesAny(f, UNMAINTAINED_PATHS))
+        : scanned;
+    const unmaintainedCount = scanned.length - allFiles.length;
+    let candidates = allFiles;
+    // 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;
+    if (opts.staged) {
+        try {
+            const staged = execSync('git diff --staged --name-only --diff-filter=ACMR', { cwd: root, encoding: 'utf8' })
+                .split('\n').map(s => s.trim()).filter((s) => Boolean(s))
+                .filter(f => existsSync(resolve(root, f)));
+            candidates = staged.filter(f => !matchesAny(f, UNMAINTAINED_PATHS));
+            stagedExcluded = staged.length - candidates.length;
+        }
+        catch (e) {
+            console.error(`validate-invariants: could not read the staged file list — ${e.message}`);
+            return exit(2);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // run
+    // ---------------------------------------------------------------------------
+    const activeRules = opts.rule ? rules.filter(r => r.id === opts.rule) : 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);
+    }
+    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));
+        return strippedCache.get(file);
+    };
+    // one ignore-parse per file, shared by every rule
+    const ignoreCache = new Map();
+    const ignoresFor = (file) => {
+        if (!ignoreCache.has(file)) {
+            const src = 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 (!candidates.some(f => matchesAny(f, rule.scope)))
+                continue;
+            let raw;
+            try {
+                raw = (await rule.check({ file: rule.scope[0], source: '', code: '', read, allFiles, 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 (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, 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 (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 ?? {};
+    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`,
+            });
+        }
+    }
+    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'],
+        });
+        const ignores = [];
+        const ig1Allowed = allowlists.IG1 ?? {};
+        for (const file of candidates) {
+            if (!ignoreScanRe.test(file))
+                continue;
+            if (ig1Allowed[file])
+                continue;
+            const src = read(file);
+            if (src === null || !src.includes('invariant-ignore'))
+                continue;
+            for (const c of ignoresFor(file).comments)
+                ignores.push({ file, ...c });
+        }
+        for (const v of findDanglingRuleRefs({
+            live, retired, allowlists, levels, ignores,
+            configFile,
+            configSource: read(configFile) ?? undefined,
+        })) {
+            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() };
+    };
+    const vitestResult = opts.vitest ? 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',
+        },
+    };
+    /** 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.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 = Object.keys(unmaintained.funnels);
+        const fileCount = opts.staged ? stagedExcluded : 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 invariants/config.mts`));
+        // 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'));
+        }
+    }
+    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('R3/R9/R19')}  module-resolving specs failed`);
+        console.log(`       ${c.cyan('invariants/specs')}`);
+        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}`);
+    console.log(c.dim('       suppress a reviewed line with  // invariant-ignore: <RULE_ID> — <reason>'));
+    console.log();
+    return exit(1);
+};

package/dist/invariants/self-test.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The generic half of the self-test: prove every rule still fires on a violating fixture
+ * and stays quiet on a clean one.
+ *
+ * This exists because a rule that has silently stopped matching finds nothing — which is
+ * indistinguishable from a clean codebase. The scan alone can print PASS while a rule is
+ * dead.
+ *
+ * Only the harness lives here. The FIXTURES map and any repo-specific assertions stay with
+ * the app that owns them and arrive through `fixtures` and `extraChecks` — the original
+ * imported the app's funnel queries directly, which is exactly the coupling the package
+ * boundary removes.
+ */
+import type { Rule } from './types.js';
+export interface Fixture {
+    file: string;
+    bad: string;
+    good: string;
+}
+export interface SelfTestInput {
+    rules: Rule[];
+    fixtures: Record<string, Fixture>;
+    /**
+     * Rule ids exempt from the fixture requirement — registry and graph rules that read real
+     * repo files rather than a synthetic source, so a fixture cannot express them.
+     */
+    skip?: string[];
+    /** Repo-specific assertions; each returns failure messages. May be async — the
+     *  domain cases they express usually need to await a rule's own check(). */
+    extraChecks?: (() => string[] | Promise<string[]>)[];
+}
+export interface SelfTestResult {
+    ok: boolean;
+    failures: string[];
+    /** Rule ids that were actually exercised against a fixture. */
+    checked: string[];
+}
+export declare const runSelfTest: (input: SelfTestInput) => Promise<SelfTestResult>;