@brighterly/lib-fe-codestyle 0.3.0 → 0.5.1

package/dist/invariants/run.js

@@ -13,9 +13,9 @@
  *   2 — the validator itself failed
  */
 import { execSync, spawnSync } from 'child_process';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
-import { walk, matchesAny, createReader, parseIgnores, stripCodeComments, findDanglingRuleRefs, resolveFindingLevel, knownRuleIds, levelOverrideOf, } from './util.js';
+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;
@@ -23,7 +23,7 @@ export const run = async (options) => {
     const settings = options.config.settings ?? {};
     const configFile = options.configFile ?? 'invariants/config.mts';
     const exit = options.exit ?? process.exit;
-    const read = createReader(root);
+    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
@@ -51,13 +51,63 @@ export const run = async (options) => {
         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'),
-        // 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'),
+        // --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
@@ -95,6 +145,10 @@ export const run = async (options) => {
         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('');
@@ -115,6 +169,47 @@ export const run = async (options) => {
         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
@@ -125,19 +220,59 @@ export const run = async (options) => {
     // 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 execSync('git diff --staged --name-only --diff-filter=ACMR', { cwd: root, encoding: 'utf8' })
-                .split('\n').some(f => ruleSources.some(p => f.trim().startsWith(p)));
+            return stagedChanges().present.some(f => ruleSources.some(p => f.startsWith(p)));
         }
         catch {
             return false;
         }
     };
-    // A full run — no --staged, no --rule= — verifies the rules before trusting them.
-    const isFullRun = !opts.staged && !opts.rule;
+    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()');
@@ -185,50 +320,86 @@ export const run = async (options) => {
     // 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
+    let allFiles = UNMAINTAINED_PATHS.length
         ? scanned.filter((f) => !matchesAny(f, UNMAINTAINED_PATHS))
         : scanned;
-    const unmaintainedCount = scanned.length - allFiles.length;
+    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 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;
+            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 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));
+            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)) {
-            const src = read(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);
@@ -242,11 +413,16 @@ export const run = async (options) => {
         // `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)))
+            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, settings })) || [];
+                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}`);
@@ -254,7 +430,7 @@ export const run = async (options) => {
             }
             for (const v of raw) {
                 const { suppressions } = ignoresFor(v.file);
-                if (suppressions.get(v.line)?.has(rule.id))
+                if (!rule.noIgnore && suppressions.get(v.line)?.has(rule.id))
                     continue;
                 const resolved = resolveFindingLevel(rule.level, override, v.level);
                 if (resolved === 'off')
@@ -279,7 +455,7 @@ export const run = async (options) => {
                 // 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 })) ?? [];
+                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}`);
@@ -287,7 +463,7 @@ export const run = async (options) => {
             }
             const { suppressions } = ignoresFor(file);
             for (const v of raw) {
-                if (suppressions.get(v.line)?.has(rule.id))
+                if (!rule.noIgnore && suppressions.get(v.line)?.has(rule.id))
                     continue;
                 const resolved = resolveFindingLevel(rule.level, override, v.level);
                 if (resolved === 'off')
@@ -302,6 +478,9 @@ export const run = async (options) => {
     // 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;
@@ -317,6 +496,15 @@ export const run = async (options) => {
             });
         }
     }
+    // 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
@@ -329,25 +517,14 @@ export const run = async (options) => {
             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'],
+            meta: ['IG0', 'IG1', 'IG2'],
         });
-        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 });
-        }
+        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 });
         }
@@ -459,6 +636,11 @@ export const run = async (options) => {
             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;
@@ -501,25 +683,28 @@ export const run = async (options) => {
         }
     };
     const engines = [
-        `${activeRules.length} rule${activeRules.length === 1 ? '' : 's'}`,
+        `${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 = Object.keys(unmaintained.funnels);
-        const fileCount = opts.staged ? stagedExcluded : unmaintainedCount;
+        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 invariants/config.mts`));
+            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)
@@ -528,8 +713,8 @@ export const run = async (options) => {
         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(`${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();
@@ -551,7 +736,11 @@ export const run = async (options) => {
         return exit(0);
     }
     console.log(`${c.red('FAIL')}   ${totals}`);
-    console.log(c.dim('       suppress a reviewed line with  // invariant-ignore: <RULE_ID> — <reason>'));
+    // 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);
 };

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

@@ -12,11 +12,19 @@
  * boundary removes.
  */
 import type { Rule } from './types.js';
-export interface Fixture {
+/**
+ * One fixture case. `bad` must produce >=1 finding, `good` must produce none.
+ * `excluded: true` asserts the FILE is matched by the rule's own `exclude` list —
+ * the case never runs the check; it proves the exclusion glob is right.
+ */
+export interface FixtureCase {
     file: string;
-    bad: string;
-    good: string;
+    bad?: string;
+    good?: string;
+    excluded?: true;
 }
+/** A rule may declare one case or an array (multi-check rules need one `bad` per check). */
+export type Fixture = FixtureCase | FixtureCase[];
 export interface SelfTestInput {
     rules: Rule[];
     fixtures: Record<string, Fixture>;

package/dist/invariants/self-test.js

@@ -17,7 +17,7 @@ const runRule = async (rule, file, source, extra = {}) => {
     const ctx = {
         file,
         source,
-        code: stripCodeComments(source),
+        code: stripCodeComments(source, file),
         read: () => null,
         allFiles: [],
         settings: {},
@@ -32,23 +32,50 @@ export const runSelfTest = async (input) => {
     for (const rule of rules) {
         if (skip.includes(rule.id))
             continue;
-        const fx = fixtures[rule.id];
-        if (!fx) {
+        const declared = fixtures[rule.id];
+        if (!declared) {
             failures.push(`${rule.id}: no self-test fixture — every rule needs one`);
             continue;
         }
-        if (!matchesAny(fx.file, rule.scope)) {
-            failures.push(`${rule.id}: fixture path ${fx.file} is outside the rule's own scope (${rule.scope.join(', ')})`);
-            continue;
-        }
-        const bad = await runRule(rule, fx.file, fx.bad);
-        const good = await runRule(rule, fx.file, fx.good);
-        if (bad.length === 0) {
-            failures.push(`${rule.id}: violating fixture produced no finding — the rule is a no-op`);
-        }
-        if (good.length > 0) {
-            failures.push(`${rule.id}: clean fixture produced ${good.length} false positive(s): ${good.map(g => g.message).join('; ')}`);
+        const cases = Array.isArray(declared) ? declared : [declared];
+        // Declared, not fired: a dead snippet reports once, on its own line. `misplaced`
+        // mutes the two floors — an out-of-scope path already has its own message and
+        // the floors would only tell the author to add cases they already declared.
+        let declaredBad = false;
+        let declaredGood = false;
+        let misplaced = false;
+        for (const fx of cases) {
+            if (fx.excluded) {
+                if (!matchesAny(fx.file, rule.scope))
+                    failures.push(`${rule.id}: ${fx.file} is declared excluded but is not in the rule's scope (${rule.scope.join(', ')}) — the exclusion is doing no work`);
+                if (!rule.exclude || !matchesAny(fx.file, rule.exclude))
+                    failures.push(`${rule.id}: ${fx.file} is declared excluded but the rule's exclude list (${(rule.exclude ?? []).join(', ') || 'none'}) does not match it`);
+                if (fx.bad !== undefined)
+                    failures.push(`${rule.id}: ${fx.file} is excluded — the runner never checks it, so a 'bad' snippet proves nothing; drop it`);
+                continue;
+            }
+            if (!matchesAny(fx.file, rule.scope)) {
+                failures.push(`${rule.id}: fixture path ${fx.file} is outside the rule's own scope (${rule.scope.join(', ')})`);
+                misplaced = true;
+                continue;
+            }
+            if (fx.bad !== undefined) {
+                declaredBad = true;
+                const bad = await runRule(rule, fx.file, fx.bad);
+                if (bad.length === 0)
+                    failures.push(`${rule.id}: violating fixture at ${fx.file} produced no finding — the check is a no-op:\n${fx.bad}`);
+            }
+            if (fx.good !== undefined) {
+                declaredGood = true;
+                const good = await runRule(rule, fx.file, fx.good);
+                if (good.length > 0)
+                    failures.push(`${rule.id}: clean fixture at ${fx.file} produced ${good.length} false positive(s): ${good.map(g => g.message).join('; ')}`);
+            }
         }
+        if (!misplaced && !declaredGood)
+            failures.push(`${rule.id}: no case proves the rule stays quiet — at least one 'good' snippet is required`);
+        if (!misplaced && !declaredBad)
+            failures.push(`${rule.id}: no case declares a 'bad' snippet — an 'excluded' case never runs the check, and a 'good'-only fixture cannot prove the rule still matches`);
         checked.push(rule.id);
     }
     for (const check of extraChecks)