@brighterly/lib-fe-codestyle 1.0.0 → 1.0.2

package/dist/engine/meta.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Meta rules. They police the escape hatch rather than the app, so they are not in the rule
+ * inventory — but they are live names (a suppression or an override may name them), they
+ * report like any rule, and their rationale lives here, next to the scans.
+ *   IG0 — a `codestyle-ignore` with no reason
+ *   IG1 — a reference to a rule name that no longer exists
+ *   IG2 — a `codestyle-ignore` naming a rule declared `noIgnore`
+ */
+import type { Registry } from './registry.js';
+import type { Finding } from './types.js';
+import { parseIgnores } from './util.js';
+export type MetaRuleId = 'IG0' | 'IG1' | 'IG2';
+export declare const metaRuleInfo: Record<MetaRuleId, {
+    title: string;
+    why: string;
+    fix: string;
+}>;
+export type ParsedIgnores = ReturnType<typeof parseIgnores>;
+export interface MetaFinding extends Finding {
+    rule: MetaRuleId;
+}
+/**
+ * IG0/IG1/IG2 over the given files. `ignoresFor` is the caller's per-file parse cache (it
+ * already knows which files are exempt from parsing — the rule sources whose fixture strings
+ * carry ignore comments on purpose).
+ */
+export declare const scanMeta: (input: {
+    files: string[];
+    ignoresFor: (file: string) => ParsedIgnores;
+    registry: Registry;
+    configFile: string;
+}) => MetaFinding[];

package/dist/engine/meta.js

@@ -0,0 +1,47 @@
+/**
+ * Meta rules. They police the escape hatch rather than the app, so they are not in the rule
+ * inventory — but they are live names (a suppression or an override may name them), they
+ * report like any rule, and their rationale lives here, next to the scans.
+ *   IG0 — a `codestyle-ignore` with no reason
+ *   IG1 — a reference to a rule name that no longer exists
+ *   IG2 — a `codestyle-ignore` naming a rule declared `noIgnore`
+ */
+import { findDanglingRuleRefs, findForbiddenSuppressions } from './util.js';
+export const metaRuleInfo = {
+    IG0: {
+        title: 'unexplained suppression',
+        why: 'an escape hatch nobody audits is a backdoor — the run prints PASS while the rule is not enforced, and nobody can later tell a reviewed exemption from someone making the red go away',
+        fix: 'put the reason after the name: // codestyle-ignore: no-bare-storage — 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 renamed rule silently voids every suppression and override naming it',
+        fix: 'drop the dead entry, or point it at a live rule name — `codestyle 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 proof — exceptions are made in the rulebook by a human, not in the file under check',
+    },
+};
+/**
+ * IG0/IG1/IG2 over the given files. `ignoresFor` is the caller's per-file parse cache (it
+ * already knows which files are exempt from parsing — the rule sources whose fixture strings
+ * carry ignore comments on purpose).
+ */
+export const scanMeta = (input) => {
+    const { files, ignoresFor, registry, configFile } = input;
+    const out = [];
+    const comments = files.flatMap(file => ignoresFor(file).comments.map(c => ({ file, ...c })));
+    for (const file of files) {
+        for (const u of ignoresFor(file).unreasoned) {
+            out.push({ rule: 'IG0', file, line: u.line, message: `codestyle-ignore: ${u.ids.join(', ')} has no reason — an unexplained exemption silently deletes the rule` });
+        }
+    }
+    const noIgnore = new Set(registry.all.filter(r => 'noIgnore' in r.rule && r.rule.noIgnore).map(r => r.rule.name));
+    for (const v of findForbiddenSuppressions(comments, noIgnore))
+        out.push({ rule: 'IG2', ...v });
+    for (const v of findDanglingRuleRefs({ live: registry.live, renamed: registry.renamed, ignores: comments, configFile }))
+        out.push({ rule: 'IG1', ...v });
+    return out;
+};

package/dist/engine/migrate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `codestyle migrate` — the mechanical half of moving a repo from 0.5.x to 1.0:
+ *   1. rewrite `invariant-ignore:` → `codestyle-ignore:` and every renamed package id (`core/R1` →
+ *      `no-bare-storage`) inside suppression comments and in `invariants/config.mts`;
+ *   2. print (or write) a `codestyle.config.ts` skeleton from the old config.
+ * Moving `invariants/` to `codestyle/` stays manual — the recipe in the README.
+ *
+ * The old config cannot be imported (the 0.5.x subpath it imports no longer exists), so it is read
+ * as text: each section's object literal is evaluated on its own, once, at migration time — it is
+ * the developer's own config. A section that will not evaluate is carried as a TODO, never dropped.
+ */
+export interface MigrateResult {
+    /** Repo-relative files whose content changed (or would change on a dry run). */
+    rewritten: string[];
+    /** A complete `codestyle.config.ts`, or `''` when there is no old config. */
+    configSkeleton: string;
+    /** One line per thing the migration dropped or could not do. */
+    notes: string[];
+}
+export declare const migrate: (root: string, io: {
+    write: boolean;
+}) => MigrateResult;

package/dist/engine/migrate.js

@@ -0,0 +1,175 @@
+/**
+ * `codestyle migrate` — the mechanical half of moving a repo from 0.5.x to 1.0:
+ *   1. rewrite `invariant-ignore:` → `codestyle-ignore:` and every renamed package id (`core/R1` →
+ *      `no-bare-storage`) inside suppression comments and in `invariants/config.mts`;
+ *   2. print (or write) a `codestyle.config.ts` skeleton from the old config.
+ * Moving `invariants/` to `codestyle/` stays manual — the recipe in the README.
+ *
+ * The old config cannot be imported (the 0.5.x subpath it imports no longer exists), so it is read
+ * as text: each section's object literal is evaluated on its own, once, at migration time — it is
+ * the developer's own config. A section that will not evaluate is carried as a TODO, never dropped.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ConfigError } from '../config/define-config.js';
+import { DEFAULT_IGNORES } from '../config/schema.js';
+import { renamedRules } from '../rules/index.js';
+import { sliceObjectLiteral, walk } from './util.js';
+const OLD_CONFIG = 'invariants/config.mts';
+const OLD_CLI = 'invariants/cli.mts';
+const NEW_CONFIG = 'codestyle.config.ts';
+const REWRITE = /\.(?:ts|mts|js|mjs|vue|scss|md)$/;
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+/** Whole tokens only: `core/R1` must not touch `core/R10`. */
+const RENAMED = Object.entries(renamedRules).map(([from, to]) => [new RegExp(`(?<![\\w/-])${escape(from)}(?![\\w-])`, 'g'), to]);
+const renameIds = (text) => RENAMED.reduce((t, [re, to]) => t.replace(re, to), text);
+const renamedName = (id) => (Object.hasOwn(renamedRules, id) ? renamedRules[id] : id);
+/**
+ * Every `invariant-ignore:` marker becomes `codestyle-ignore:` — every one on a line, in comments
+ * and in strings alike (a fixture string holding an ignore comment is a proof that wants the 1.0
+ * spelling too). Renamed ids are rewritten from a line's first marker onwards, so every marker's
+ * ids are covered; in the old config, anywhere. Idempotent: a second pass changes nothing.
+ */
+const rewrite = (file, source) => {
+    if (file === OLD_CONFIG)
+        return renameIds(source.replace(/invariant-ignore:/g, 'codestyle-ignore:'));
+    return source.split('\n').map(line => {
+        const at = line.search(/(?:invariant|codestyle)-ignore:/);
+        if (at === -1)
+            return line;
+        return line.slice(0, at) + renameIds(line.slice(at).replace(/invariant-ignore:/g, 'codestyle-ignore:'));
+    }).join('\n');
+};
+/** `export const <key>…= { … }` → its evaluated value, its raw text when evaluation fails, or null. */
+const section = (source, key) => {
+    const m = new RegExp(`export\\s+const\\s+${key}\\b[^=]*=`).exec(source);
+    if (!m)
+        return null;
+    const literal = sliceObjectLiteral(source, m.index + m[0].length);
+    try {
+        return { ok: true, value: new Function(`return (${literal})`)() };
+    }
+    catch {
+        return { ok: false, raw: literal };
+    }
+};
+/** The `[ ... ]` literal starting at the first `[` after `fromIndex`, balanced on brackets. */
+const sliceArrayLiteral = (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 === 0)
+            return source.slice(start, i + 1);
+    }
+    return source.slice(start);
+};
+/** A string array assigned to one of `keys` in the 0.5.x composition root (`scanRoots: [...]`). */
+const arrayIn = (source, keys) => {
+    const m = new RegExp(`\\b(?:${keys.join('|')})\\s*[:=]\\s*(?=\\[)`).exec(source);
+    if (!m)
+        return null;
+    const literal = sliceArrayLiteral(source, m.index + m[0].length);
+    try {
+        const value = new Function(`return (${literal})`)();
+        return Array.isArray(value) && value.every(v => typeof v === 'string') ? { ok: true, value } : { ok: false, raw: literal };
+    }
+    catch {
+        return { ok: false, raw: literal };
+    }
+};
+/** The old tree moves to `codestyle/`; its paths follow. */
+const moved = (p) => p.replace(/^invariants(?=\/|$)/, 'codestyle');
+const q = (s) => JSON.stringify(s);
+const todo = (key, raw) => [`  // TODO: could not evaluate ${key} — port by hand:`, ...raw.split('\n').map(l => `  // ${l}`)];
+const skeletonOf = (source, cli, notes) => {
+    const lines = [
+        "import { defineConfig } from '@brighterly/lib-fe-codestyle'",
+        "// custom rules: import repo from './codestyle/index.ts' and spread it: ...repo",
+        '',
+        'export default defineConfig({',
+    ];
+    // The scan roots and rule sources lived in the composition root, not the config. Dropping them
+    // would shrink the tree to the defaults and silence any rule scoped outside it.
+    if (cli !== null) {
+        for (const [key, names] of [['files', ['scanRoots', 'SCAN_ROOTS']], ['ruleSources', ['ruleSources', 'RULE_SOURCES']]]) {
+            const found = arrayIn(cli, [...names]);
+            if (found?.ok)
+                lines.push(`  ${key}: [${found.value.map(p => q(moved(p))).join(', ')}],`);
+            else if (found)
+                lines.push(...todo(key, found.raw));
+        }
+    }
+    const settings = section(source, 'settings');
+    if (settings?.ok) {
+        const entries = Object.entries(settings.value);
+        if (entries.some(([k]) => k === 'selfTestFile'))
+            notes.push('migrate: dropped settings.selfTestFile — fixtures live on the rule objects; files under ruleSources are exempt from ignore parsing');
+        const kept = entries.filter(([k]) => k !== 'selfTestFile');
+        if (kept.length) {
+            lines.push('  settings: {', ...kept.map(([k, v]) => (typeof v === 'string'
+                ? `    ${q(k)}: ${q(v)},`
+                : `    // TODO: could not read settings[${q(k)}] — port by hand: ${JSON.stringify(v)}`)), '  },');
+        }
+    }
+    else if (settings)
+        lines.push(...todo('settings', settings.raw));
+    const levels = section(source, 'levels');
+    if (levels?.ok) {
+        const entries = Object.entries(levels.value);
+        const isLevel = (v) => typeof v === 'object' && v !== null && typeof v.level === 'string';
+        if (entries.length) {
+            lines.push('  rules: {', ...entries.map(([id, o]) => (isLevel(o)
+                ? `    ${q(renamedName(id))}: ${q(o.level)},${typeof o.reason === 'string' && o.reason ? ` // ${o.reason.replace(/\n/g, ' ')}` : ''}`
+                : `    // TODO: could not read levels[${q(id)}] — port by hand: ${JSON.stringify(o)}`)), '  },');
+        }
+    }
+    else if (levels)
+        lines.push(...todo('levels', levels.raw));
+    const allowlists = section(source, 'allowlists');
+    if (allowlists?.ok) {
+        const entries = Object.entries(allowlists.value)
+            .flatMap(([id, paths]) => Object.entries(paths).map(([path, reason]) => `    { files: [${q(path)}], rules: { ${q(renamedName(id))}: "off" }, reason: ${q(reason)} },`));
+        if (entries.length)
+            lines.push('  overrides: [', ...entries, '  ],');
+    }
+    else if (allowlists)
+        lines.push(...todo('allowlists', allowlists.raw));
+    if (/export\s+const\s+unmaintained\b/.test(source))
+        notes.push('migrate: dropped unmaintained — 1.0 has no exclusion list; prune a tree with `ignores`, or exempt it with an override and its reason');
+    if (/export\s+const\s+retired\b/.test(source))
+        notes.push('migrate: dropped retired — a dead name is reported by IG1; renamed package ids say where they went');
+    lines.push('})', '');
+    return lines.join('\n');
+};
+export const migrate = (root, io) => {
+    // Never overwrite a config, and refuse before any file is touched.
+    if (io.write && existsSync(resolve(root, NEW_CONFIG)))
+        throw new ConfigError(`${NEW_CONFIG} already exists — delete it or run without --write`);
+    const notes = [];
+    const oldPath = resolve(root, OLD_CONFIG);
+    const oldSource = existsSync(oldPath) ? readFileSync(oldPath, 'utf8') : null;
+    const cliPath = resolve(root, OLD_CLI);
+    const cliSource = existsSync(cliPath) ? readFileSync(cliPath, 'utf8') : null;
+    const configSkeleton = oldSource === null ? '' : skeletonOf(oldSource, cliSource, notes);
+    if (oldSource === null)
+        notes.push(`migrate: no ${OLD_CONFIG} — no config skeleton; write ${NEW_CONFIG} by hand`);
+    const ignored = new Set(DEFAULT_IGNORES);
+    const files = walk(root, '', rel => ignored.has(rel.slice(rel.lastIndexOf('/') + 1))).filter(f => REWRITE.test(f));
+    const rewritten = [];
+    for (const file of files) {
+        const source = readFileSync(resolve(root, file), 'utf8');
+        const next = rewrite(file, source);
+        if (next === source)
+            continue;
+        rewritten.push(file);
+        if (io.write)
+            writeFileSync(resolve(root, file), next);
+    }
+    if (io.write && configSkeleton)
+        writeFileSync(resolve(root, NEW_CONFIG), configSkeleton);
+    return { rewritten: rewritten.sort(), configSkeleton, notes };
+};

package/dist/engine/overrides.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-place overrides: "never the rule is off — always this place, this reason".
+ *
+ * Compiled once per run from the config against the registry. The runner asks `resolve` for
+ * each finding's effective level; a rule receives its own entries through
+ * `RuleContext.overrides` (`forRule`). Everything wrong with an entry is a `problem` reported
+ * against the config file as IG1, never a silent no-op:
+ *   a rules key naming no live rule (or an external one, or a renamed id),
+ *   a glob that matches no file of the scanned tree,
+ *   an `until` in the past (the entry then stops applying),
+ *   a missing `until` on a rule that requires one (the entry does not apply to that rule).
+ *
+ * Pure: the scanned files, the config source and today's date all arrive through `io`.
+ */
+import type { ResolvedConfig } from '../config/schema.js';
+import type { Registry } from './registry.js';
+import type { EffectiveOverride, Finding, Level, ReportedFinding, RuleName } from './types.js';
+export interface CompiledOverrides {
+    /** The non-expired entries naming `name`, window-adjusted, in config order — what `RuleContext.overrides` receives. */
+    forRule: (name: RuleName) => EffectiveOverride[];
+    /** `min(level, lowest matching entry)` on `finding.subject ?? finding.file`; never raises. */
+    resolve: (finding: Finding, name: RuleName, level: Level) => Level;
+    /** Reported against the config file, rule `IG1`, level `error`. */
+    problems: ReportedFinding[];
+}
+export interface OverridesIo {
+    /** Repo-relative path the problems are reported against. */
+    configFile: string;
+    /** Its text, so a problem can point at the entry's line. */
+    configSource?: string;
+    /** The FULL scanned tree, repo-relative — never a --staged/--stdin subset. */
+    files: string[];
+    /** Today as `YYYY-MM-DD`. */
+    today: string;
+}
+export declare const compileOverrides: (config: ResolvedConfig, registry: Registry, io: OverridesIo) => CompiledOverrides;

package/dist/engine/overrides.js

@@ -0,0 +1,92 @@
+/**
+ * Per-place overrides: "never the rule is off — always this place, this reason".
+ *
+ * Compiled once per run from the config against the registry. The runner asks `resolve` for
+ * each finding's effective level; a rule receives its own entries through
+ * `RuleContext.overrides` (`forRule`). Everything wrong with an entry is a `problem` reported
+ * against the config file as IG1, never a silent no-op:
+ *   a rules key naming no live rule (or an external one, or a renamed id),
+ *   a glob that matches no file of the scanned tree,
+ *   an `until` in the past (the entry then stops applying),
+ *   a missing `until` on a rule that requires one (the entry does not apply to that rule).
+ *
+ * Pure: the scanned files, the config source and today's date all arrive through `io`.
+ */
+import { exemptionExpiry, globToRegExp } from './util.js';
+const RANK = { off: 0, warn: 1, error: 2 };
+const lower = (a, b) => (RANK[a] <= RANK[b] ? a : b);
+const higher = (a, b) => (RANK[a] >= RANK[b] ? a : b);
+/** `iso` minus `days` calendar days, as `YYYY-MM-DD`. */
+const minusDays = (iso, days) => {
+    const [y, m, d] = iso.split('-').map(Number);
+    return new Date(Date.UTC(y, m - 1, d - days)).toISOString().slice(0, 10);
+};
+export const compileOverrides = (config, registry, io) => {
+    const problems = [];
+    const lines = io.configSource?.split('\n') ?? [];
+    /** First line containing the entry's reason, else the glob, else 1. */
+    const lineOf = (...needles) => {
+        for (const needle of needles) {
+            const i = needle === '' ? -1 : lines.findIndex(l => l.includes(needle));
+            if (i !== -1)
+                return i + 1;
+        }
+        return 1;
+    };
+    const report = (entryIndex, message, glob = '') => {
+        const line = lineOf(config.overrides[entryIndex]?.reason ?? '', glob);
+        problems.push({ file: io.configFile, line, message, rule: 'IG1', level: 'error' });
+    };
+    const compiled = [];
+    config.overrides.forEach((o, i) => {
+        const patterns = o.files.map(g => globToRegExp(g));
+        o.files.forEach((glob, j) => {
+            if (!io.files.some(f => patterns[j].test(f)))
+                report(i, `overrides[${i}].files[${j}] "${glob}" matches no file — the exemption is inert; drop it or fix the glob`, glob);
+        });
+        const until = exemptionExpiry(o.reason);
+        if (until !== null && io.today > until) {
+            report(i, `overrides[${i}] expired on ${until} — remove the entry or renew it`);
+            return;
+        }
+        const inWindow = until !== null && io.today >= minusDays(until, 7);
+        for (const [name, entryLevel] of Object.entries(o.rules)) {
+            const label = `overrides[${i}].rules["${name}"]`;
+            if (!registry.live.has(name)) {
+                const to = Object.hasOwn(registry.renamed, name) ? registry.renamed[name] : undefined;
+                report(i, `${label}: unknown rule${to ? ` — it was renamed to ${to}` : ''}`);
+                continue;
+            }
+            const reg = registry.byName.get(name);
+            if (reg && (reg.owner === 'eslint' || reg.owner === 'test')) {
+                report(i, `${label}: ${name} is owned by ${reg.owner === 'eslint' ? 'eslint' : 'a test'} — an override cannot change it`);
+                continue;
+            }
+            if (until === null && reg && 'exemptionsRequireUntil' in reg.rule && reg.rule.exemptionsRequireUntil) {
+                report(i, `overrides[${i}] names ${name}, which requires an "until YYYY-MM-DD" in its reason`);
+                continue;
+            }
+            // An entry at or above the rule's effective level changes nothing — an inert exemption.
+            if (reg && RANK[entryLevel] >= RANK[reg.level]) {
+                report(i, `overrides[${i}] never lowers ${name} (${entryLevel} ≥ ${reg.level}) — drop it`);
+                continue;
+            }
+            const effective = inWindow ? higher(entryLevel, 'warn') : entryLevel;
+            compiled.push({ name, entry: { files: [...o.files], level: effective, reason: o.reason, until }, patterns });
+        }
+    });
+    return {
+        forRule: name => compiled.filter(c => c.name === name).map(c => ({ ...c.entry, files: [...c.entry.files] })),
+        resolve: (finding, name, level) => {
+            const target = finding.subject ?? finding.file;
+            let out = level;
+            for (const c of compiled) {
+                if (c.name !== name || !c.patterns.some(p => p.test(target)))
+                    continue;
+                out = lower(out, c.entry.level);
+            }
+            return out;
+        },
+        problems,
+    };
+};

package/dist/engine/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The rule registry — the one place that knows which rules exist, who owns each, and at what
+ * effective level. Overrides, the runner and the CLI all read it; nothing else decides whether
+ * a name is live.
+ *
+ *   effective level = `config.rules[name]` when present, else the rule's own `level`
+ *   external rules  = live names with no check here: level `off`, never selected
+ *   meta rules      = IG0/IG1/IG2: live (a suppression may name them), never configurable
+ */
+import type { ResolvedConfig } from '../config/schema.js';
+import type { AnyRule, Level, Rule, RuleName } from './types.js';
+export interface RegisteredRule {
+    rule: AnyRule;
+    /** Effective level: the `rules` entry when present, else the rule's own `level`. */
+    level: Level;
+    owner: 'package' | 'custom' | 'eslint' | 'test';
+    tags: string[];
+    /** The config's `rules` entry for this rule, when there is one: the base level AND a ceiling over a finding's own level. */
+    configured?: Level;
+}
+export interface Registry {
+    /** Package first (in its given order), then custom in declaration order. */
+    all: RegisteredRule[];
+    byName: Map<RuleName, RegisteredRule>;
+    /** Checkable (non-external) rules whose effective level is not `off`, in `all` order. */
+    select: (opts: {
+        tags?: string[];
+        only?: RuleName[];
+    }) => RegisteredRule[];
+    /** Every addressable name, external and IG0/IG1/IG2 included. */
+    live: Set<RuleName>;
+    /** Old id → new name, for IG1 messages. */
+    renamed: Record<string, RuleName>;
+}
+export declare const buildRegistry: (config: ResolvedConfig, pkg?: Rule[]) => Registry;

package/dist/engine/registry.js

@@ -0,0 +1,100 @@
+/**
+ * The rule registry — the one place that knows which rules exist, who owns each, and at what
+ * effective level. Overrides, the runner and the CLI all read it; nothing else decides whether
+ * a name is live.
+ *
+ *   effective level = `config.rules[name]` when present, else the rule's own `level`
+ *   external rules  = live names with no check here: level `off`, never selected
+ *   meta rules      = IG0/IG1/IG2: live (a suppression may name them), never configurable
+ */
+import { ConfigError } from '../config/define-config.js';
+import { packageRules, renamedRules } from '../rules/index.js';
+import { isExternal } from './types.js';
+const META = ['IG0', 'IG1', 'IG2'];
+const META_NAMES = new Set(META);
+/** Own keys only: `constructor` or `toString` must never read as a renamed rule. */
+const renamedTo = (name) => (Object.hasOwn(renamedRules, name) ? renamedRules[name] : undefined);
+const ownerWording = (owner) => (owner === 'eslint' ? 'eslint' : 'a test');
+const unknownName = (label, name) => {
+    const to = renamedTo(name);
+    return new ConfigError(`${label}: unknown rule${to ? ` — it was renamed to ${to}` : ''}`);
+};
+export const buildRegistry = (config, pkg = packageRules) => {
+    const levels = config.rules;
+    /** Own keys only: a rule named `toString` must not read `Object.prototype.toString` as its level. */
+    const configuredFor = (name) => (Object.hasOwn(levels, name) ? levels[name] : undefined);
+    const levelFor = (name, fallback) => configuredFor(name) ?? fallback;
+    const byName = new Map();
+    const all = [];
+    const add = (entry) => {
+        all.push(entry);
+        byName.set(entry.rule.name, entry);
+    };
+    for (const rule of pkg) {
+        if (byName.has(rule.name))
+            throw new ConfigError(`${rule.name} is declared twice in the package rules`);
+        add({ rule, level: levelFor(rule.name, rule.level), owner: 'package', tags: [...(rule.tags ?? [])], configured: configuredFor(rule.name) });
+    }
+    for (const rule of config.custom) {
+        const name = rule.name;
+        const taken = byName.get(name);
+        if (taken) {
+            throw new ConfigError(taken.owner === 'package'
+                ? `${name} is both a package rule and a custom rule — rename the custom one`
+                : `${name} is declared twice in custom — rule names must be unique`);
+        }
+        const to = renamedTo(name);
+        if (to)
+            throw new ConfigError(`custom rule "${name}" uses a retired package id (renamed to ${to}) — pick another name`);
+        if (META_NAMES.has(name))
+            throw new ConfigError(`custom rule "${name}" uses an engine rule name — pick another name`);
+        if (isExternal(rule))
+            add({ rule, level: 'off', owner: rule.owner, tags: [...(rule.tags ?? [])] });
+        else
+            add({ rule, level: levelFor(name, rule.level), owner: 'custom', tags: [...(rule.tags ?? [])], configured: configuredFor(name) });
+    }
+    for (const name of Object.keys(levels)) {
+        const label = `rules["${name}"]`;
+        if (META_NAMES.has(name))
+            throw new ConfigError(`${label}: ${name} is an engine rule and cannot be configured`);
+        const entry = byName.get(name);
+        if (!entry)
+            throw unknownName(label, name);
+        if (entry.owner === 'eslint')
+            throw new ConfigError(`${label}: ${name} is owned by ${ownerWording(entry.owner)} — set its level in the ESLint config`);
+        if (entry.owner === 'test')
+            throw new ConfigError(`${label}: ${name} is owned by ${ownerWording(entry.owner)} — it has no level here; the test passes or fails`);
+    }
+    const checkable = (r) => r.owner === 'package' || r.owner === 'custom';
+    const select = ({ tags, only }) => {
+        let picked = all.filter(r => checkable(r) && r.level !== 'off');
+        // A tag no rule carries selects nothing and would print PASS over an empty gate — a typo, not a filter.
+        for (const t of tags ?? []) {
+            if (!all.some(r => r.tags.includes(t)))
+                throw new ConfigError(`no rule carries tag "${t}" — codestyle list prints the tags`);
+        }
+        // An empty filter is no filter: the CLI passes [] or undefined for "everything".
+        if (only?.length) {
+            for (const name of only) {
+                const entry = byName.get(name);
+                if (!entry)
+                    throw unknownName(`--only "${name}"`, name);
+                if (!checkable(entry))
+                    throw new ConfigError(`--only "${name}": owned by ${ownerWording(entry.owner)}, so there is nothing to run here`);
+                if (entry.level === 'off')
+                    throw new ConfigError(`${name} is off in the config — raise its level or drop --only`);
+            }
+            picked = picked.filter(r => only.includes(r.rule.name));
+        }
+        if (tags?.length)
+            picked = picked.filter(r => r.tags.some(t => tags.includes(t)));
+        return picked;
+    };
+    return {
+        all,
+        byName,
+        select,
+        live: new Set([...byName.keys(), ...META]),
+        renamed: renamedRules,
+    };
+};

package/dist/engine/report.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The human reporter: findings grouped by file, each rule's why/fix once, then the PASS/FAIL
+ * line. Layout is deliberate — where, which rule, what happened, what to do — so a long run
+ * stays scannable. The JSON shape lives with `check()`; this file only prints for people.
+ */
+import type { MetaRuleId } from './meta.js';
+import type { Registry } from './registry.js';
+import type { ReportedFinding } from './types.js';
+export interface ReportOptions {
+    /** ANSI colour; the caller turns it off under `--no-color`, NO_COLOR or a non-TTY stdout. */
+    color: boolean;
+    /** How many files were checked, for the summary line. */
+    scanned: number;
+    /** The repo's own rules failed their proofs: the run fails even with no error finding. */
+    selfTestFailed?: boolean;
+}
+type MetaInfo = Record<MetaRuleId, {
+    title: string;
+    why: string;
+    fix: string;
+}>;
+export declare const printReport: (findings: ReportedFinding[], registry: Registry, meta: MetaInfo, opts: ReportOptions) => void;
+export {};

package/dist/engine/report.js

@@ -0,0 +1,87 @@
+/**
+ * The human reporter: findings grouped by file, each rule's why/fix once, then the PASS/FAIL
+ * line. Layout is deliberate — where, which rule, what happened, what to do — so a long run
+ * stays scannable. The JSON shape lives with `check()`; this file only prints for people.
+ */
+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;
+};
+export const printReport = (findings, registry, meta, opts) => {
+    const paint = (code) => (text) => (opts.color ? `\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 infoOf = (name) => {
+        if (Object.hasOwn(meta, name))
+            return meta[name];
+        const rule = registry.byName.get(name)?.rule;
+        return rule ? { title: rule.title, why: rule.why, fix: 'fix' in rule ? rule.fix : undefined } : undefined;
+    };
+    const ordered = [...findings].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    const byFile = new Map();
+    for (const f of ordered)
+        byFile.set(f.file, [...(byFile.get(f.file) ?? []), f]);
+    console.log();
+    for (const [file, list] of byFile) {
+        console.log(c.cyan(file));
+        for (const f of list) {
+            const label = f.level === 'error' ? c.redBold('error') : c.yellowBold('warn ');
+            console.log(`  ${String(f.line).padStart(4)}  ${label}  ${c.bold(f.rule)}  ${f.message}`);
+        }
+        console.log();
+    }
+    // The rationale once per rule, not once per finding.
+    const fired = [...new Set(ordered.map(f => f.rule))];
+    if (fired.length) {
+        console.log(c.dim('─'.repeat(WIDTH)));
+        for (const name of fired) {
+            const info = infoOf(name);
+            console.log(`${c.bold(name)}  ${info?.title ?? 'unattributed finding'}`);
+            if (info?.why)
+                for (const [i, l] of wrap(info.why, 8).entries())
+                    console.log(`  ${i === 0 ? c.dim('why   ') : '      '}${c.dim(l)}`);
+            if (info?.fix)
+                for (const [i, l] of wrap(info.fix, 8).entries())
+                    console.log(`  ${i === 0 ? c.dim('fix   ') : '      '}${c.green(l)}`);
+            console.log();
+        }
+    }
+    const errors = findings.filter(f => f.level === 'error').length;
+    const warnings = findings.filter(f => f.level === 'warn').length;
+    const totals = [
+        errors ? c.red(`${errors} error${errors === 1 ? '' : 's'}`) : null,
+        warnings ? c.yellow(`${warnings} warning${warnings === 1 ? '' : 's'}`) : null,
+    ].filter(Boolean).join(c.dim(' · '));
+    const scanned = c.dim(` — ${opts.scanned} file(s) checked`);
+    console.log(c.dim('─'.repeat(WIDTH)));
+    const selfTest = opts.selfTestFailed ? c.red('the self-test failed (see stderr)') : null;
+    if (errors === 0 && !selfTest)
+        console.log(`${c.green('PASS')}   ${totals || 'no findings'}${scanned}`);
+    else {
+        console.log(`${c.red('FAIL')}   ${[selfTest, totals].filter(Boolean).join(c.dim(' · '))}${scanned}`);
+        // Never advertise the escape hatch when every error is noIgnore or a meta rule.
+        const suppressible = findings.some(f => {
+            if (f.level !== 'error')
+                return false;
+            const rule = registry.byName.get(f.rule)?.rule;
+            return rule !== undefined && !('noIgnore' in rule && rule.noIgnore);
+        });
+        if (suppressible)
+            console.log(c.dim('       suppress a reviewed line with  // codestyle-ignore: <rule> — <reason>'));
+    }
+    console.log();
+};