@brighterly/lib-fe-codestyle 0.1.0

package/dist/invariants/self-test.js

@@ -0,0 +1,57 @@
+/**
+ * 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 { matchesAny, stripCodeComments } from './util.js';
+/** Run one rule against a synthetic single-file context. */
+const runRule = async (rule, file, source, extra = {}) => {
+    const ctx = {
+        file,
+        source,
+        code: stripCodeComments(source),
+        read: () => null,
+        allFiles: [],
+        settings: {},
+        ...extra,
+    };
+    return (await rule.check(ctx)) ?? [];
+};
+export const runSelfTest = async (input) => {
+    const { rules, fixtures, skip = [], extraChecks = [] } = input;
+    const failures = [];
+    const checked = [];
+    for (const rule of rules) {
+        if (skip.includes(rule.id))
+            continue;
+        const fx = fixtures[rule.id];
+        if (!fx) {
+            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('; ')}`);
+        }
+        checked.push(rule.id);
+    }
+    for (const check of extraChecks)
+        failures.push(...(await check()));
+    return { ok: failures.length === 0, failures, checked };
+};

package/dist/invariants/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The contracts every rule and every config entry must satisfy.
+ *
+ * These exist so that extending this directory fails at typecheck instead of
+ * failing silently: a rule with a typo'd field, a manifest entry naming a
+ * mechanism that has no resolver, a level that is not a real level. Those were
+ * all silently ignored while this was plain JavaScript.
+ */
+/** `error` counts toward the exit code · `warn` reports · `off` skips entirely. */
+export type Level = 'error' | 'warn' | 'off';
+/**
+ * Rule ID: the family letter says where the rule came from.
+ *   R — regression: a CLAUDE.md "What NOT to do" scar
+ *   B — business:   the funnel-data contract, confirmed by PMM
+ *   C — convention: a preference we chose, advisory by default
+ *   L — linter:     covered by a built-in ESLint rule, configured elsewhere
+ * IDs are load-bearing (`--rule=`, `invariant-ignore:`, allowlists, levels) —
+ * retire one, never recycle it.
+ */
+/** App-local ids are bare; shared-pack ids carry the underscore prefix (`_R1`). */
+export type RuleId = `${'' | '_'}${'R' | 'B' | 'C' | 'L'}${number}`;
+/**
+ * Meta rules. They police the escape hatch rather than the app, so they have no
+ * family letter — but they are addressable exactly like any other rule
+ * (`allowlists`, `levels`, `invariant-ignore`), so they belong in the ID space.
+ *   IG0 — an `invariant-ignore` with no reason
+ *   IG1 — a reference to a rule ID that no longer exists
+ */
+export type MetaRuleId = 'IG0' | 'IG1';
+/** Anything addressable in config or a suppression comment. */
+export type AnyRuleId = RuleId | MetaRuleId;
+/** One violation. `line` is 1-based. */
+export interface Finding {
+    file: string;
+    line: number;
+    message: string;
+    /**
+     * Severity for THIS finding, when it differs from the rest of the rule's.
+     * Omit to inherit the rule's. A `levels` override in config.mts is a ceiling
+     * over this — see resolveFindingLevel in util.mts.
+     */
+    level?: Level;
+}
+/** A finding after the runner has attributed it to a rule and a level. */
+export interface ReportedFinding extends Finding {
+    ruleId: AnyRuleId;
+    level: Level;
+}
+/**
+ * Every settings key a shared rule reads, documented for hover. Annotate the app's
+ * `settings` const with this to get completion and the per-key contract in the IDE:
+ *
+ *   export const settings: SharedRuleSettings & Record<string, string> = { ... }
+ *
+ * All keys are optional: a missing one degrades the rule's MESSAGE (or falls back to
+ * the documented default), never its firing.
+ */
+export interface SharedRuleSettings {
+    /** `_R1`/`_R3` fix messages: how this app names its safe storage wrapper, e.g. 'safeLocalStorage from @helpers/safe-local-storage'. */
+    safeStorageModule?: string;
+    /** `_R3` fix message: the guarded parse helper, e.g. 'parseStoredJson() from @helpers/safe-local-storage'. */
+    safeJsonParse?: string;
+    /** `_C3`: the palette file that legitimately DEFINES colour literals, e.g. 'app/assets/scss/_colors.scss'. */
+    scssTokensFile?: string;
+    /** `_C2`: root of the UI-kit tree whose component names must not be duplicated. Default 'app/components/UI'. */
+    uiKitRoot?: string;
+    /** `_C4` fix message: the shared date-format enum, e.g. 'DateFormat from @ts-types/date/enums'. */
+    dateFormatModule?: string;
+    /** `_C5`: where entity type folders live. Default 'app/types'. */
+    typesRoot?: string;
+    /** `_C6` fix message: this app's typography source — a mixin in some apps ('the font() mixin from @scss/_mixins.scss'), a component in others ('the AppText component'). */
+    typographySource?: string;
+    /** `_C7`: which `<script>` attribute order is canonical in this app. Default 'setup-first' (`<script setup lang="ts">`). */
+    scriptAttrOrder?: 'setup-first' | 'lang-first';
+}
+/** What a rule's `check` receives. */
+export interface RuleContext {
+    /** Repo-relative path of the file under inspection. */
+    file: string;
+    /** Raw file contents. */
+    source: string;
+    /** Same contents with comment bodies blanked, line numbers preserved. */
+    code: string;
+    /** Read any other repo-relative file (cached). Returns null if unreadable. */
+    read: (rel: string) => string | null;
+    /** Every scanned file in the repo — for rules that resolve references. */
+    allFiles: string[];
+    /**
+     * App-specific paths a SHARED rule needs, supplied by `config.settings`. This is how a
+     * portable rule learns where this app keeps its SCSS tokens or its UI-kit root, without
+     * the rule becoming a factory. The known keys are documented on `SharedRuleSettings`.
+     */
+    settings: Readonly<SharedRuleSettings & Record<string, string>>;
+}
+/** A `once: true` rule reads its own inputs, so it gets no per-file fields. */
+export type OnceRuleContext = Pick<RuleContext, 'read' | 'allFiles'> & Partial<RuleContext>;
+interface BaseRule {
+    id: RuleId;
+    /** Short description — appears in the report and the README inventory. */
+    title: string;
+    level: Level;
+    /** The silent-failure mode. A rule without a why gets deleted by future-you. */
+    why: string;
+    /** What to do instead. */
+    fix: string;
+    /** Glob patterns this rule applies to. */
+    scope: string[];
+    /** Glob patterns to skip within scope. */
+    exclude?: string[];
+    /** Set when `check` returns a promise, so the runner awaits it. */
+    async?: boolean;
+}
+/** Runs once per matching file. */
+export interface FileRule extends BaseRule {
+    once?: false;
+    check: (ctx: RuleContext) => Finding[] | Promise<Finding[]>;
+}
+/**
+ * Runs once per invocation if any file in `scope` is in the candidate set, for
+ * rules that read several files themselves (registry and graph checks).
+ */
+export interface OnceRule extends BaseRule {
+    once: true;
+    check: (ctx: OnceRuleContext) => Finding[] | Promise<Finding[]>;
+}
+/**
+ * The two shapes are separate so a per-file rule cannot accidentally be handed a
+ * context without `source`, and a `once` rule cannot claim to receive one.
+ */
+export type Rule = FileRule | OnceRule;
+/** Per-rule, per-file exemptions. The value is the reason — required. */
+export type Allowlists = Partial<Record<AnyRuleId, Record<string, string>>>;
+/**
+ * Severity overrides, keyed by rule ID. The reason is MANDATORY: once four repos share a
+ * rule pack, a bare `levels.X = 'off'` is how a shared rule gets silenced invisibly.
+ * Read it through `levelOverrideOf` rather than indexing directly.
+ */
+export type Levels = Partial<Record<AnyRuleId, {
+    level: Level;
+    reason: string;
+}>>;
+/**
+ * Retired rule IDs and why. A numeric gap records only that *something* existed;
+ * this records what, so a stale reference gets a useful message instead of
+ * "unknown rule". Never delete an entry — that is the point of it.
+ */
+export type RetiredRules = Record<string, string>;
+/** Everything rule IG0/IG1 needs, passed in so the check stays pure and testable. */
+export interface DanglingRefInput {
+    /** IDs of rules currently loaded. */
+    live: Set<string>;
+    retired: RetiredRules;
+    allowlists: Allowlists;
+    levels: Levels;
+    /** Every `invariant-ignore` comment found in the scanned set. */
+    ignores: {
+        file: string;
+        line: number;
+        ids: string[];
+    }[];
+    /** Where allowlists/levels live, for the finding location. */
+    configFile?: string;
+    /** Contents of `configFile`, so a stale key can be reported on its own line. */
+    configSource?: string;
+}
+/** An invariant a built-in ESLint rule already covers. */
+export interface LinterOwnedRule {
+    id: RuleId;
+    eslintRule: string;
+    level: Level;
+    title: string;
+    why: string;
+}
+/**
+ * Areas the validator deliberately does not look at.
+ *
+ * Not an allowlist: an allowlist exempts one FILE from one RULE, and the file is
+ * still part of the funnel model. This removes a whole subtree from the scanned
+ * set and a whole funnel from `query.funnels()`, so no rule — present or future —
+ * can see it. That is the right shape for a design system in flux, and the wrong
+ * shape for anything we intend to keep correct.
+ *
+ * Every entry carries a reason, and the CLI prints the totals on every run: an
+ * exclusion nobody can see is how a validator quietly stops covering the repo.
+ */
+export interface Unmaintained {
+    /** Glob patterns dropped from the scanned file set → reason. */
+    paths: Record<string, string>;
+    /** WRAP_STEPS keys hidden from `query.funnels()` → reason. */
+    funnels: Record<string, string>;
+}
+export {};

package/dist/invariants/types.js

@@ -0,0 +1,9 @@
+/**
+ * The contracts every rule and every config entry must satisfy.
+ *
+ * These exist so that extending this directory fails at typecheck instead of
+ * failing silently: a rule with a typo'd field, a manifest entry naming a
+ * mechanism that has no resolver, a level that is not a real level. Those were
+ * all silently ignored while this was plain JavaScript.
+ */
+export {};

package/dist/invariants/util.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared plumbing for validate-invariants: file walking, glob matching,
+ * a read cache, and the `invariant-ignore` escape hatch.
+ *
+ * No dependencies — this runs in pre-commit, so it must not need an install.
+ */
+import type { DanglingRefInput, Finding, Level, Levels } from './types.js';
+/**
+ * Minimal glob → RegExp. Supports `**`, `*`, `?` and `{a,b}`.
+ * Deliberately not a full glob implementation: rule scopes are simple by
+ * convention, and a dependency here would break the pre-commit hook.
+ */
+export declare const globToRegExp: (glob: string) => RegExp;
+export declare const matchesAny: (path: string, globs: string[]) => boolean;
+/** Recursively list repo-relative file paths under `dir`, POSIX separators. */
+export declare const walk: (root: string, dir: string) => string[];
+export declare const createReader: (root: string) => ((rel: string) => string | null);
+export declare const toRelative: (root: string, p: string) => string;
+/**
+ * Parse every `invariant-ignore:` comment in a file.
+ * Returns { suppressions: Map<lineNumber, Set<ruleId>>, unreasoned: [{ line, ids }] }
+ *
+ * A comment suppresses violations on its own line and the line below, so both
+ * `// invariant-ignore: R1 — reason` above the code and a trailing comment work.
+ * The reason is mandatory: an ignore without one is itself reported (rule IG0),
+ * otherwise the escape hatch silently becomes a way to delete rules.
+ */
+export declare const parseIgnores: (source: string) => {
+    suppressions: Map<number, Set<string>>;
+    unreasoned: {
+        line: number;
+        ids: string[];
+    }[];
+    comments: {
+        line: number;
+        ids: string[];
+    }[];
+};
+/**
+ * Blank out comment bodies while preserving every line number and offset, so a
+ * rule that greps for an identifier does not fire on prose. Handles `//`,
+ * block comments and HTML comments.
+ *
+ * Known limitation: a `//` inside a string literal (a URL) blanks the rest of
+ * that line. Harmless for identifier scans; do not use this for parsing.
+ */
+export declare const stripCodeComments: (source: string) => string;
+/** Line number (1-based) of a character offset. */
+export declare const lineOf: (source: string, index: number) => number;
+/**
+ * Return the source of the object literal that starts at the first `{` after
+ * `fromIndex`, balanced on braces. Used by project-level rules that read a
+ * config map out of a real file instead of a fixture.
+ */
+export declare const sliceObjectLiteral: (source: string, fromIndex: number) => string;
+/** Keys of a `'string-literal': value` object literal. */
+export declare const stringKeysOf: (literal: string) => Set<string>;
+/**
+ * Every reference to a rule ID that no longer names a live rule.
+ *
+ * Three sinks dereference an ID and none of them used to validate it: an
+ * allowlist key, a `levels` key, and an `invariant-ignore` comment. A stale
+ * entry in any of them is inert and silent — which is what made "retire an ID,
+ * never recycle it" a discipline rather than a check. This is the check.
+ *
+ * Pure by design: the caller supplies the live set and the config, so the
+ * self-test can exercise it without touching the repo.
+ */
+export declare const findDanglingRuleRefs: (input: DanglingRefInput) => Finding[];
+/**
+ * Severity of one finding, from three inputs that used to be one.
+ *
+ *   ruleLevel — the rule's own default
+ *   override  — `levels[id]` in config.mts, set by whoever runs the gate
+ *   finding   — `Finding.level`, set by the rule for THIS finding
+ *
+ * Rules:
+ *  1. A finding with no level of its own takes the rule's effective level, and
+ *     an override may raise or lower that — the pre-existing behaviour, which
+ *     is how a `warn` rule gets promoted to blocking in one config line.
+ *  2. A finding may set its own level, so one rule can bundle a blocking check
+ *     with an advisory one. R12 is why: an explicit <template> before the
+ *     forwarding loop is a silent Vue override bug, while a missing :data-qa is
+ *     a Playwright-selector gap with a 27-file backlog. One shared severity
+ *     forced the dangerous check down to the backlog's level.
+ *  3. **An override is a CEILING over rule 2.** It can only lower a finding's
+ *     self-declared level, never raise it, so an operator silencing a noisy rule
+ *     cannot be defeated by a finding that promotes itself.
+ */
+export declare const resolveFindingLevel: (ruleLevel: Level, override: Level | undefined, finding: Level | undefined) => Level;
+/**
+ * Every rule ID that currently exists, across all three vectors.
+ *
+ * IG1 needs this, and getting it from `rules` alone is wrong: R3/R9/R19 are
+ * implemented as vitest specs and L1 is owned by ESLint, so a file-scan-only
+ * live set reports a perfectly valid `invariant-ignore: R3` as dangling. The
+ * bug is invisible in a unit test that supplies its own live set — it only
+ * shows up against the real repo.
+ */
+export declare const knownRuleIds: (parts: {
+    fileScan: string[];
+    specs: string[];
+    linter: string[];
+    meta?: string[];
+}) => Set<string>;
+/**
+ * The severity override for a rule, or undefined.
+ *
+ * The only place that knows `Levels` holds `{ level, reason }` rather than a bare level.
+ * The reason is mandatory in the type so a shared rule cannot be silenced invisibly; this
+ * accessor keeps every caller from having to care.
+ */
+export declare const levelOverrideOf: (levels: Levels, id: string) => Level | undefined;

package/dist/invariants/util.js

@@ -0,0 +1,269 @@
+/**
+ * Shared plumbing for validate-invariants: file walking, glob matching,
+ * a read cache, and the `invariant-ignore` escape hatch.
+ *
+ * No dependencies — this runs in pre-commit, so it must not need an install.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, relative, sep } from 'node:path';
+const SKIP_DIRS = new Set(['node_modules', '.git', '.nuxt', '.output', 'dist', 'coverage', 'test-results']);
+/**
+ * Minimal glob → RegExp. Supports `**`, `*`, `?` and `{a,b}`.
+ * Deliberately not a full glob implementation: rule scopes are simple by
+ * convention, and a dependency here would break the pre-commit hook.
+ */
+export const globToRegExp = (glob) => {
+    let out = '^';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                // `**/` swallows the slash so `a/**/*.ts` also matches `a/x.ts`
+                if (glob[i + 2] === '/') {
+                    out += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    out += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                out += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            out += '[^/]';
+        }
+        else if (c === '{') {
+            const end = glob.indexOf('}', i);
+            // Without this, `i = end` sets i to -1, the loop increments it back to 0 and
+            // re-parses the glob forever — the validator would hang in the pre-commit hook
+            // instead of naming the bad scope.
+            if (end === -1)
+                throw new Error(`invalid glob (unterminated '{'): ${glob}`);
+            const alts = glob.slice(i + 1, end).split(',').map(a => a.replace(/[.+^$()|[\]\\]/g, '\\$&'));
+            out += `(?:${alts.join('|')})`;
+            i = end;
+        }
+        else if ('.+^$()|[]\\'.includes(c)) {
+            out += `\\${c}`;
+        }
+        else {
+            out += c;
+        }
+    }
+    return new RegExp(`${out}$`);
+};
+export const matchesAny = (path, globs) => globs.some(g => globToRegExp(g).test(path));
+/** Recursively list repo-relative file paths under `dir`, POSIX separators. */
+export const walk = (root, dir) => {
+    const out = [];
+    const abs = resolve(root, dir);
+    let entries;
+    try {
+        entries = readdirSync(abs, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (e.name.startsWith('.') && e.name !== '.github')
+            continue;
+        if (SKIP_DIRS.has(e.name))
+            continue;
+        const child = `${dir}/${e.name}`;
+        if (e.isDirectory())
+            out.push(...walk(root, child));
+        else if (e.isFile())
+            out.push(child);
+    }
+    return out;
+};
+export const createReader = (root) => {
+    const cache = new Map();
+    return (rel) => {
+        if (!cache.has(rel)) {
+            try {
+                cache.set(rel, readFileSync(resolve(root, rel), 'utf8'));
+            }
+            catch {
+                cache.set(rel, null);
+            }
+        }
+        return cache.get(rel) ?? null;
+    };
+};
+export const toRelative = (root, p) => relative(root, resolve(root, p)).split(sep).join('/');
+// `_?` — shared-pack rules carry an underscore prefix (`_R1`); app-local rules are bare (`R1`).
+const IGNORE_RE = /invariant-ignore:\s*(_?[A-Z]{1,3}\d{1,3}(?:\s*,\s*_?[A-Z]{1,3}\d{1,3})*)\s*(?:—|–|--|-|:)?\s*(.*)$/;
+/**
+ * Parse every `invariant-ignore:` comment in a file.
+ * Returns { suppressions: Map<lineNumber, Set<ruleId>>, unreasoned: [{ line, ids }] }
+ *
+ * A comment suppresses violations on its own line and the line below, so both
+ * `// invariant-ignore: R1 — reason` above the code and a trailing comment work.
+ * The reason is mandatory: an ignore without one is itself reported (rule IG0),
+ * otherwise the escape hatch silently becomes a way to delete rules.
+ */
+export const parseIgnores = (source) => {
+    const suppressions = new Map();
+    const unreasoned = [];
+    const comments = [];
+    const lines = source.split('\n');
+    lines.forEach((line, idx) => {
+        const m = line.match(IGNORE_RE);
+        if (!m)
+            return;
+        const ids = (m[1] ?? '').split(',').map(s => s.trim());
+        const reason = (m[2] || '').trim();
+        // Every comment is recorded here, reasoned or not: IG1 must be able to see a
+        // reference to a dead rule even when IG0 is already reporting the missing
+        // reason. Two ADJACENT comments merge in `suppressions`, so that map cannot
+        // be used to recover per-comment ids.
+        comments.push({ line: idx + 1, ids });
+        if (!reason) {
+            unreasoned.push({ line: idx + 1, ids });
+            return;
+        }
+        for (const target of [idx + 1, idx + 2]) {
+            if (!suppressions.has(target))
+                suppressions.set(target, new Set());
+            ids.forEach(id => suppressions.get(target).add(id));
+        }
+    });
+    return { suppressions, unreasoned, comments };
+};
+/**
+ * Blank out comment bodies while preserving every line number and offset, so a
+ * rule that greps for an identifier does not fire on prose. Handles `//`,
+ * block comments and HTML comments.
+ *
+ * Known limitation: a `//` inside a string literal (a URL) blanks the rest of
+ * that line. Harmless for identifier scans; do not use this for parsing.
+ */
+export const stripCodeComments = (source) => {
+    const blank = (m) => m.replace(/[^\n]/g, ' ');
+    return source
+        .replace(/<!--[\s\S]*?-->/g, blank)
+        .replace(/\/\*[\s\S]*?\*\//g, blank)
+        .replace(/(^|[^:])\/\/[^\n]*/g, (m, pre) => pre + blank(m.slice(pre.length)));
+};
+/** Line number (1-based) of a character offset. */
+export const lineOf = (source, index) => source.slice(0, index).split('\n').length;
+/**
+ * Return the source of the object literal that starts at the first `{` after
+ * `fromIndex`, balanced on braces. Used by project-level rules that read a
+ * config map out of a real file instead of a fixture.
+ */
+export const sliceObjectLiteral = (source, fromIndex) => {
+    const start = source.indexOf('{', fromIndex);
+    if (start === -1)
+        return '';
+    let depth = 0;
+    for (let i = start; i < source.length; i++) {
+        if (source[i] === '{')
+            depth++;
+        else if (source[i] === '}') {
+            depth--;
+            if (depth === 0)
+                return source.slice(start, i + 1);
+        }
+    }
+    return source.slice(start);
+};
+/** Keys of a `'string-literal': value` object literal. */
+export const stringKeysOf = (literal) => new Set([...literal.matchAll(/^\s*'([a-z0-9-]+)'\s*:/gm)].flatMap(m => (m[1] ? [m[1]] : [])));
+/**
+ * Every reference to a rule ID that no longer names a live rule.
+ *
+ * Three sinks dereference an ID and none of them used to validate it: an
+ * allowlist key, a `levels` key, and an `invariant-ignore` comment. A stale
+ * entry in any of them is inert and silent — which is what made "retire an ID,
+ * never recycle it" a discipline rather than a check. This is the check.
+ *
+ * Pure by design: the caller supplies the live set and the config, so the
+ * self-test can exercise it without touching the repo.
+ */
+export const findDanglingRuleRefs = (input) => {
+    const { live, retired, allowlists, levels, ignores } = input;
+    const configFile = input.configFile ?? 'invariants/config.mts';
+    const out = [];
+    // Line of `<id>:` inside the given config block, so the finding points at the
+    // stale entry rather than at line 1 of the file.
+    const lineOfKey = (block, id) => {
+        const src = input.configSource;
+        if (!src)
+            return 1;
+        const start = src.indexOf(block);
+        if (start === -1)
+            return 1;
+        const rel = src.slice(start).search(new RegExp(`^\\s*${id}\\s*:`, 'm'));
+        return rel === -1 ? 1 : lineOf(src, start + rel);
+    };
+    const explain = (id) => retired[id] ? `${id} was retired — ${retired[id]}` : `${id} does not name any rule`;
+    for (const id of Object.keys(allowlists)) {
+        if (live.has(id))
+            continue;
+        out.push({ file: configFile, line: lineOfKey('allowlists', id), message: `allowlists names "${id}", but ${explain(id)} — the exemption is inert; drop it` });
+    }
+    for (const id of Object.keys(levels)) {
+        if (live.has(id))
+            continue;
+        out.push({ file: configFile, line: lineOfKey('levels', id), message: `levels names "${id}", but ${explain(id)} — the severity override does nothing; drop it` });
+    }
+    for (const { file, line, ids } of ignores) {
+        for (const id of ids) {
+            if (live.has(id))
+                continue;
+            out.push({ file, line, message: `invariant-ignore names "${id}", but ${explain(id)} — this suppression is inert; drop it or name a live rule` });
+        }
+    }
+    return out;
+};
+const LEVEL_RANK = { off: 0, warn: 1, error: 2 };
+/**
+ * Severity of one finding, from three inputs that used to be one.
+ *
+ *   ruleLevel — the rule's own default
+ *   override  — `levels[id]` in config.mts, set by whoever runs the gate
+ *   finding   — `Finding.level`, set by the rule for THIS finding
+ *
+ * Rules:
+ *  1. A finding with no level of its own takes the rule's effective level, and
+ *     an override may raise or lower that — the pre-existing behaviour, which
+ *     is how a `warn` rule gets promoted to blocking in one config line.
+ *  2. A finding may set its own level, so one rule can bundle a blocking check
+ *     with an advisory one. R12 is why: an explicit <template> before the
+ *     forwarding loop is a silent Vue override bug, while a missing :data-qa is
+ *     a Playwright-selector gap with a 27-file backlog. One shared severity
+ *     forced the dangerous check down to the backlog's level.
+ *  3. **An override is a CEILING over rule 2.** It can only lower a finding's
+ *     self-declared level, never raise it, so an operator silencing a noisy rule
+ *     cannot be defeated by a finding that promotes itself.
+ */
+export const resolveFindingLevel = (ruleLevel, override, finding) => {
+    const effective = override ?? ruleLevel;
+    const claimed = finding ?? effective;
+    if (override === undefined)
+        return claimed;
+    return LEVEL_RANK[claimed] <= LEVEL_RANK[override] ? claimed : override;
+};
+/**
+ * Every rule ID that currently exists, across all three vectors.
+ *
+ * IG1 needs this, and getting it from `rules` alone is wrong: R3/R9/R19 are
+ * implemented as vitest specs and L1 is owned by ESLint, so a file-scan-only
+ * live set reports a perfectly valid `invariant-ignore: R3` as dangling. The
+ * bug is invisible in a unit test that supplies its own live set — it only
+ * shows up against the real repo.
+ */
+export const knownRuleIds = (parts) => new Set([...parts.fileScan, ...parts.specs, ...parts.linter, ...(parts.meta ?? [])].filter(id => id !== '—'));
+/**
+ * The severity override for a rule, or undefined.
+ *
+ * The only place that knows `Levels` holds `{ level, reason }` rather than a bare level.
+ * The reason is mandatory in the type so a shared rule cannot be silenced invisibly; this
+ * accessor keeps every caller from having to care.
+ */
+export const levelOverrideOf = (levels, id) => levels[id]?.level;

package/dist/validate/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The aggregating runner behind `pnpm validate`.
+ *
+ * Why this exists rather than `a && b && c`: pnpm offers exactly one of the two properties
+ * a gate needs, never both. Default bail stops at the first failure and exits 1 — correct
+ * exit code, incomplete feedback, so you fix lint, push, and only then discover typecheck.
+ * `--no-bail` runs everything but **exits 0**, which is unusable as a gate (the same
+ * footgun the invariants CLI records as "dropped 2026-08-19: --warn-only, always exits 0").
+ *
+ * So: run every step, report all of them, and fail if any failed. One push, one run, every
+ * problem visible — locally as much as in CI.
+ */
+export interface ValidateStep {
+    /** Short label for the summary and the CI group. */
+    name: string;
+    /** Shell command to run. */
+    run: string;
+}
+export interface ValidateResult {
+    name: string;
+    ok: boolean;
+    ms: number;
+}
+export interface ValidateOptions {
+    /** Defaults to a real child_process spawn. Injectable for tests. */
+    exec?: (cmd: string) => {
+        ok: boolean;
+    };
+    /** Defaults to process.stdout.write. */
+    write?: (s: string) => void;
+    /** Defaults to process.exit. Injectable so tests can assert the code. */
+    exit?: (code: number) => never;
+    /** Emit ::group:: markers. Defaults to Boolean(process.env.GITHUB_ACTIONS). */
+    ci?: boolean;
+}
+export declare const validate: (steps: ValidateStep[], options?: ValidateOptions) => Promise<ValidateResult[]>;