@brighterly/lib-fe-codestyle 1.0.0 → 1.0.2

package/dist/engine/run.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `check()` — the runner on the 1.0 surface: load the config, build the registry, compile the
+ * overrides, pick the files and the rules, run them, apply suppressions and overrides to every
+ * finding, add the meta findings, self-test the repo's own rules, report.
+ *
+ * Exit codes:
+ *   0 — clean, or warnings only
+ *   1 — an error-level finding, or a failed self-test
+ *   2 — the tool itself failed (bad flags, no or bad config, a crashing rule)
+ */
+import type { RegisteredRule } from './registry.js';
+import type { Level } from './types.js';
+export interface CheckOptions {
+    /** Repo root. Passed, never derived — import.meta.url here resolves into node_modules. */
+    root: string;
+    argv: string[];
+    /** `YYYY-MM-DD`; defaults to today (UTC). Overrides and rules read it for `until` dates. */
+    today?: string;
+    /**
+     * Defaults to setting `process.exitCode` — never `process.exit()`, which would cut stdout still
+     * draining into a pipe. Engine code always `return exit(...)`. Injectable so tests can collect the code.
+     */
+    exit?: (code: number) => never;
+    /** The `--stdin` content. Defaults to reading fd 0. */
+    stdin?: () => string;
+}
+export interface CheckJson {
+    schemaVersion: 1;
+    ok: boolean;
+    scanned: number;
+    errors: number;
+    warnings: number;
+    rules: {
+        name: string;
+        level: Level;
+        title: string;
+        tags: string[];
+        owner: RegisteredRule['owner'];
+    }[];
+    findings: {
+        rule: string;
+        level: Level;
+        file: string;
+        line: number;
+        message: string;
+    }[];
+    skipped?: {
+        file: string;
+        reason: string;
+    };
+    /** Present whenever the self-test ran. */
+    selfTest?: {
+        ok: boolean;
+        failures: string[];
+    };
+}
+export declare const check: (options: CheckOptions) => Promise<void>;

package/dist/engine/run.js

@@ -0,0 +1,353 @@
+/**
+ * `check()` — the runner on the 1.0 surface: load the config, build the registry, compile the
+ * overrides, pick the files and the rules, run them, apply suppressions and overrides to every
+ * finding, add the meta findings, self-test the repo's own rules, report.
+ *
+ * Exit codes:
+ *   0 — clean, or warnings only
+ *   1 — an error-level finding, or a failed self-test
+ *   2 — the tool itself failed (bad flags, no or bad config, a crashing rule)
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ConfigError } from '../config/define-config.js';
+import { findConfig, loadConfig } from '../config/load-config.js';
+import { metaRuleInfo, scanMeta } from './meta.js';
+import { compileOverrides } from './overrides.js';
+import { buildRegistry } from './registry.js';
+import { printReport } from './report.js';
+import { runSelfTest } from './self-test.js';
+import { createReader, globToRegExp, matchesAny, parseIgnores, resolveFindingLevel, stripCodeComments, toRelative, todayUtc, walk, } from './util.js';
+const USAGE = 'usage: codestyle check [--staged | --stdin --file=<path>] [--json] [--only=<a,b>] [--rule=<name>] [--tags=<a,b>] [--no-self-test] [--no-color]';
+const SWITCHES = new Set(['--staged', '--stdin', '--json', '--no-self-test', '--no-color']);
+const VALUES = ['file', 'rule', 'tags', 'only'];
+/** Parse the flags, or name the first one that is not ours — a typo must not run a full scan. */
+const parseArgs = (argv) => {
+    const values = {};
+    for (const arg of argv) {
+        if (SWITCHES.has(arg))
+            continue;
+        const key = VALUES.find(v => arg.startsWith(`--${v}=`));
+        if (!key)
+            return `unknown argument "${arg}"`;
+        values[key] = arg.slice(key.length + 3);
+    }
+    const list = (v) => (v ?? '').split(',').map(s => s.trim()).filter(Boolean);
+    return {
+        staged: argv.includes('--staged'),
+        stdin: argv.includes('--stdin'),
+        json: argv.includes('--json'),
+        selfTest: !argv.includes('--no-self-test'),
+        color: !argv.includes('--no-color'),
+        file: values.file ?? null,
+        // --rule= is the 0.5.x spelling of --only=, kept so consumer hooks need no change.
+        only: [...list(values.only), ...list(values.rule)],
+        tags: list(values.tags),
+    };
+};
+const isGlob = (p) => /[*?{]/.test(p);
+/** `config.files` minus `config.ignores`: directories are walked, files taken, globs matched against the whole root. */
+const fileSet = (root, config) => {
+    const ignoreTests = config.ignores.map(ig => (isGlob(ig)
+        ? (rel) => globToRegExp(ig).test(rel)
+        : ig.includes('/') ? (rel) => rel === ig || rel.startsWith(`${ig}/`) : (rel) => rel.split('/').includes(ig)));
+    const ignored = (rel) => ignoreTests.some(t => t(rel));
+    const out = new Set();
+    let rootWalk = null;
+    for (const entry of config.files) {
+        if (isGlob(entry)) {
+            rootWalk ??= walk(root, '', ignored);
+            const re = globToRegExp(entry);
+            for (const f of rootWalk)
+                if (re.test(f))
+                    out.add(f);
+            continue;
+        }
+        if (ignored(entry))
+            continue;
+        const stat = statSync(resolve(root, entry), { throwIfNoEntry: false });
+        if (!stat)
+            continue;
+        if (stat.isDirectory())
+            for (const f of walk(root, entry, ignored))
+                out.add(f);
+        else
+            out.add(entry);
+    }
+    const covered = (rel) => config.files.some(e => (isGlob(e) ? globToRegExp(e).test(rel) : rel === e || rel.startsWith(`${e}/`)));
+    return { files: [...out], ignored, covered };
+};
+/** What this commit stages: present paths, and the deleted/renamed-away ones a `once` rule must still see. */
+const stagedChanges = (root) => {
+    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);
+    }
+    return { present: present.filter(f => existsSync(resolve(root, f))), gone };
+};
+const inScope = (rule, file) => matchesAny(file, rule.scope) && !(rule.exclude && matchesAny(file, rule.exclude));
+const IGNORE_SCAN = /\.(?:m?ts|vue|mjs|js)$/;
+const LEVELS = ['off', 'warn', 'error'];
+export const check = async (options) => {
+    const exit = options.exit ?? ((code) => { process.exitCode = code; });
+    const json = options.argv.includes('--json');
+    const fail = (message) => {
+        console.error(`codestyle: ${message}`);
+        // The JSON contract is total: a tool failure under --json still prints an object.
+        if (json)
+            console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: message }));
+        return exit(2);
+    };
+    const args = parseArgs(options.argv);
+    if (typeof args === 'string')
+        return fail(`${args}\n${USAGE}`);
+    if (args.stdin && !args.file)
+        return fail('--stdin requires --file=<repo-relative path>');
+    if (args.file && !args.stdin)
+        return fail('--file= is only meaningful with --stdin');
+    if (args.stdin && args.staged)
+        return fail('--stdin and --staged are exclusive');
+    try {
+        return await run(options, args, exit, fail);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            return fail(e.message);
+        // Anything else is the tool failing (a config that throws while loading, a crash in the
+        // engine) — exit 2, never the 1 that means "an error-level finding". Keep the stack.
+        if (e instanceof Error && e.stack)
+            console.error(e.stack);
+        return fail(e instanceof Error ? e.message : String(e));
+    }
+};
+const run = async (options, args, exit, fail) => {
+    const { root } = options;
+    const today = options.today ?? todayUtc();
+    const config = await loadConfig(root);
+    const configFile = toRelative(root, findConfig(root));
+    const registry = buildRegistry(config);
+    const selected = registry.select({ tags: args.tags, only: args.only });
+    const narrowed = args.tags.length > 0 || args.only.length > 0;
+    /** A `ruleSources` entry is a directory prefix, matched at a `/` boundary. */
+    const isRuleSource = (f) => config.ruleSources.some(p => f === p || f.startsWith(p.endsWith('/') ? p : `${p}/`));
+    // ---------------------------------------------------------------- stdin
+    let stdinContent = null;
+    const stdinFile = args.stdin ? toRelative(root, args.file) : null;
+    if (args.stdin) {
+        if (!options.stdin && process.stdin.isTTY)
+            return fail('--stdin expects content on stdin, not a terminal');
+        try {
+            stdinContent = (options.stdin ?? (() => readFileSync(0, 'utf8')))();
+        }
+        catch (e) {
+            return fail(`could not read stdin — ${e.message}`);
+        }
+        // Empty is a plumbing failure, not a clean file: the rules would invent findings about content never sent.
+        if (stdinContent === '')
+            return fail('--stdin received no content');
+    }
+    const baseRead = createReader(root);
+    const read = (rel) => (rel === stdinFile ? stdinContent : baseRead(rel));
+    // ---------------------------------------------------------------- files
+    const tree = fileSet(root, config);
+    // `allFiles` may gain the stdin path; the overrides keep the tree as it is on disk.
+    let allFiles = tree.files;
+    const compiled = compileOverrides(config, registry, { configFile, configSource: baseRead(configFile) ?? undefined, files: tree.files, today });
+    const rulesJson = registry.all.map(r => ({ name: r.rule.name, level: r.level, title: r.rule.title, tags: r.tags, owner: r.owner }));
+    /** A file this run will not check says so, in the shape the caller asked for — never a bare PASS. */
+    const skip = (file, reason) => {
+        if (args.json) {
+            const json = { schemaVersion: 1, ok: true, scanned: 0, errors: 0, warnings: 0, rules: rulesJson, findings: [], skipped: { file, reason } };
+            console.log(JSON.stringify(json, null, 2));
+        }
+        else {
+            console.log(`  not checked: ${file} — ${reason}`);
+        }
+        return exit(0);
+    };
+    /** Under `files` and not under `ignores` (the path or any directory above it) — the tree's own gate. */
+    const inTree = (f) => tree.covered(f) && !f.split('/').some((_, i, parts) => tree.ignored(parts.slice(0, i + 1).join('/')));
+    let candidates = allFiles;
+    let triggers = allFiles;
+    let selfTestDue = args.selfTest && !args.staged && !args.stdin && !narrowed;
+    /** stdin on a path no selected rule scopes: only the meta scans run, and a clean file is skipped. */
+    let metaOnly = false;
+    if (stdinFile !== null) {
+        // The path or any directory above it may be ignored.
+        if (stdinFile.split('/').some((_, i, parts) => tree.ignored(parts.slice(0, i + 1).join('/'))))
+            return skip(stdinFile, `under ignores in ${configFile}`);
+        if (!tree.covered(stdinFile))
+            return skip(stdinFile, `not under files in ${configFile}`);
+        metaOnly = !selected.some(r => inScope(r.rule, stdinFile));
+        candidates = [stdinFile];
+        // A once rule in stdin mode runs when the one file passes its gate, and reads the piped content.
+        triggers = candidates;
+        if (!allFiles.includes(stdinFile))
+            allFiles = [...allFiles, stdinFile];
+    }
+    else if (args.staged) {
+        let staged;
+        try {
+            staged = stagedChanges(root);
+        }
+        catch (e) {
+            return fail(`could not read the staged file list — ${e.message}`);
+        }
+        const treeSet = new Set(allFiles);
+        candidates = staged.present.filter(f => treeSet.has(f));
+        // Deleted paths are no candidates, but still a change to the tree a once rule reads. Present
+        // and deleted alike pass the tree's gate, so a once rule fires the same in every mode.
+        const touched = [...staged.present, ...staged.gone];
+        triggers = touched.filter(inTree);
+        // Deleting a rule or its proof is exactly when the self-test must run.
+        selfTestDue = args.selfTest && touched.some(isRuleSource);
+    }
+    // A narrowed run describes its own reach: the files its rules can see.
+    if (narrowed && !args.stdin)
+        candidates = candidates.filter(f => selected.some(r => inScope(r.rule, f)));
+    // ---------------------------------------------------------------- suppressions
+    const empty = { suppressions: new Map(), unreasoned: [], comments: [], legacy: false };
+    const ignoreCache = new Map();
+    /** One parse per file; rule sources are exempt (their fixture strings carry ignore comments on purpose). */
+    const ignoresFor = (file) => {
+        let parsed = ignoreCache.get(file);
+        if (parsed)
+            return parsed;
+        const src = isRuleSource(file) ? null : read(file);
+        parsed = src === null || !src.includes('-ignore:') ? empty : parseIgnores(src);
+        if (parsed.legacy)
+            console.error(`codestyle: ${file} uses "invariant-ignore:" — rename it to "codestyle-ignore:" (the old spelling is accepted through 1.x)`);
+        ignoreCache.set(file, parsed);
+        return parsed;
+    };
+    // ---------------------------------------------------------------- rules
+    const findings = [];
+    const settings = config.settings;
+    const strippedCache = new Map();
+    const stripped = (file, source) => {
+        if (!strippedCache.has(file))
+            strippedCache.set(file, stripCodeComments(source, file));
+        return strippedCache.get(file);
+    };
+    /** Returns an error message when a finding is malformed — the caller turns it into a rule crash. */
+    const accept = (entry, rule, raw) => {
+        for (const v of raw) {
+            if (v.level !== undefined && !LEVELS.includes(v.level))
+                return `rule ${rule.name} produced an invalid level "${String(v.level)}"`;
+            if (!rule.noIgnore && ignoresFor(v.file).suppressions.get(v.line)?.has(rule.name))
+                continue;
+            // A `rules` entry is the base level and a ceiling over the finding's own; without one, the finding's own level wins.
+            const level = compiled.resolve(v, rule.name, resolveFindingLevel(rule.level, entry.configured, v.level));
+            if (level === 'off')
+                continue;
+            findings.push({ ...v, rule: rule.name, level });
+        }
+        return null;
+    };
+    // A custom rule whose scope finds nothing in the tree never runs — say so (not a finding).
+    if (!args.staged && !args.stdin) {
+        for (const entry of selected) {
+            if (entry.owner === 'custom' && !tree.files.some(f => inScope(entry.rule, f))) {
+                console.error(`codestyle: rule ${entry.rule.name} matches no file under files — check files/ignores`);
+            }
+        }
+    }
+    for (const entry of metaOnly ? [] : selected) {
+        const rule = entry.rule;
+        const overrides = compiled.forRule(rule.name);
+        if (rule.once) {
+            if (!triggers.some(f => inScope(rule, f)))
+                continue;
+            let raw;
+            try {
+                raw = (await rule.check({ file: rule.scope[0], source: '', code: '', read, allFiles, settings, overrides, today })) ?? [];
+            }
+            catch (e) {
+                return fail(`rule ${rule.name} crashed — ${e.message}`);
+            }
+            // At write time only findings about the written path count; `subject` names it for a registry finding.
+            if (stdinFile !== null)
+                raw = raw.filter(v => (v.subject ?? v.file) === stdinFile);
+            const bad = accept(entry, rule, raw);
+            if (bad)
+                return fail(bad);
+            continue;
+        }
+        for (const file of candidates) {
+            if (!inScope(rule, file))
+                continue;
+            const source = read(file);
+            if (source === null)
+                continue;
+            try {
+                // Always await: a Promise-returning check whose author forgot `async` must not be iterated as a Promise.
+                const raw = await rule.check({ file, source, code: stripped(file, source), read, allFiles, settings, overrides, today });
+                const bad = accept(entry, rule, raw ?? []);
+                if (bad)
+                    return fail(bad);
+            }
+            catch (e) {
+                return fail(`rule ${rule.name} crashed on ${file} — ${e.message}`);
+            }
+        }
+    }
+    // ---------------------------------------------------------------- meta + config problems
+    const metaFiles = candidates.filter(f => IGNORE_SCAN.test(f) && !isRuleSource(f));
+    for (const v of scanMeta({ files: metaFiles, ignoresFor, registry, configFile })) {
+        // An override may lower a meta rule too (IG0 for a legacy file).
+        const level = compiled.resolve(v, v.rule, 'error');
+        if (level !== 'off')
+            findings.push({ ...v, level });
+    }
+    // Config problems are properties of the config, not of the file a hook is checking.
+    if (!args.stdin)
+        findings.push(...compiled.problems);
+    if (metaOnly && findings.length === 0)
+        return skip(stdinFile, 'no selected rule scopes this path');
+    // ---------------------------------------------------------------- self-test (the repo's own rules)
+    let selfTest;
+    if (selfTestDue) {
+        const own = registry.all.filter(r => r.owner === 'custom').map(r => r.rule);
+        const { ok, failures } = await runSelfTest({ rules: own, settings, today });
+        selfTest = { ok, failures };
+        for (const f of failures)
+            console.error(`codestyle: self-test: ${f}`);
+    }
+    const selfTestOk = selfTest?.ok ?? true;
+    // ---------------------------------------------------------------- report
+    const errors = findings.filter(f => f.level === 'error').length;
+    const warnings = findings.filter(f => f.level === 'warn').length;
+    const ok = errors === 0 && selfTestOk;
+    if (args.json) {
+        const json = {
+            schemaVersion: 1,
+            ok,
+            scanned: candidates.length,
+            errors,
+            warnings,
+            rules: rulesJson,
+            findings: findings.map(f => ({ rule: f.rule, level: f.level, file: f.file, line: f.line, message: f.message })),
+            ...(selfTest ? { selfTest } : {}),
+        };
+        console.log(JSON.stringify(json, null, 2));
+    }
+    else {
+        const color = args.color && Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+        printReport(findings, registry, metaRuleInfo, { color, scanned: candidates.length, selfTestFailed: !selfTestOk });
+    }
+    return exit(ok ? 0 : 1);
+};

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

@@ -0,0 +1,33 @@
+/**
+ * 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 proofs travel on the rule objects themselves — `fixtures`
+ * (single-file cases), `world` (a virtual repo) or `verify` (a programmatic proof) — so a
+ * consumer's rules prove themselves exactly like the package's.
+ */
+import type { FixtureCase, Rule, RuleName, SharedRuleSettings } from './types.js';
+/** 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[];
+    /** The date fixture contexts see, and world contexts unless the world pins its own. Default: today (UTC). */
+    today?: string;
+    /** The consumer's settings, handed to every proof context. Default `{}`. */
+    settings?: SharedRuleSettings & Record<string, string>;
+}
+export interface SelfTestResult {
+    ok: boolean;
+    failures: string[];
+    /** Names of the rules whose proof ran, in input order. */
+    checked: RuleName[];
+}
+/**
+ * Prove every rule still fires on a known violation and stays quiet on a clean case, through
+ * whichever proof the rule carries. A rule with none is itself a failure.
+ */
+export declare const runSelfTest: (input: SelfTestInput) => Promise<SelfTestResult>;

package/dist/engine/self-test.js

@@ -0,0 +1,141 @@
+/**
+ * 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 proofs travel on the rule objects themselves — `fixtures`
+ * (single-file cases), `world` (a virtual repo) or `verify` (a programmatic proof) — so a
+ * consumer's rules prove themselves exactly like the package's.
+ */
+import { matchesAny, stripCodeComments, todayUtc } from './util.js';
+const callCheck = async (rule, ctx) => (await rule.check(ctx)) ?? [];
+/** Run one rule against a synthetic single-file context: the tree is that one file. */
+const runOnFile = (rule, file, source, settings, today) => callCheck(rule, {
+    file,
+    source,
+    code: stripCodeComments(source, file),
+    read: (p) => (p === file ? source : null),
+    allFiles: [file],
+    settings,
+    overrides: [],
+    today,
+});
+const asList = (v) => (Array.isArray(v) ? v : [v]);
+/** The 0.5.x grammar: `bad` must produce >=1 finding, `good` none, `excluded` proves the exclude glob. */
+const proveFixtures = async (rule, cases, settings, today) => {
+    const failures = [];
+    // 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.name}: ${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.name}: ${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.name}: ${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.name}: 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 runOnFile(rule, fx.file, fx.bad, settings, today);
+            if (bad.length === 0)
+                failures.push(`${rule.name}: 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 runOnFile(rule, fx.file, fx.good, settings, today);
+            if (good.length > 0)
+                failures.push(`${rule.name}: clean fixture at ${fx.file} produced ${good.length} false positive(s): ${good.map(g => g.message).join('; ')}`);
+        }
+    }
+    if (!misplaced && !declaredGood)
+        failures.push(`${rule.name}: no case proves the rule stays quiet — at least one 'good' snippet is required`);
+    if (!misplaced && !declaredBad)
+        failures.push(`${rule.name}: no case declares a 'bad' snippet — an 'excluded' case never runs the check, and a 'good'-only fixture cannot prove the rule still matches`);
+    return failures;
+};
+/**
+ * A virtual repo, gated exactly like the runner: only files in `scope` minus `exclude` count.
+ * A `once` rule runs once over the whole world; a file rule runs over every world file in
+ * scope. A `finding` world with nothing in scope is no proof — production would never run it.
+ */
+const proveWorld = async (rule, world, settings, today) => {
+    const paths = Object.keys(world.files);
+    const read = (p) => world.files[p] ?? null;
+    const inScope = paths.filter(f => matchesAny(f, rule.scope) && !(rule.exclude && matchesAny(f, rule.exclude)));
+    const date = world.today ?? today;
+    if (inScope.length === 0)
+        return world.expect === 'finding' ? [`${rule.name}: world has no file in scope`] : [];
+    const findings = [];
+    if (rule.once) {
+        // Shaped like the runner's once context.
+        findings.push(...await callCheck(rule, { file: rule.scope[0], source: '', code: '', read, allFiles: paths, settings, overrides: [], today: date }));
+    }
+    else {
+        for (const file of inScope) {
+            const source = world.files[file] ?? '';
+            findings.push(...await callCheck(rule, { file, source, code: stripCodeComments(source, file), read, allFiles: paths, settings, overrides: [], today: date }));
+        }
+    }
+    const listed = findings.map(f => `${f.file}:${f.line} ${f.message}`).join('; ');
+    if (world.expect === 'silence')
+        return findings.length ? [`${rule.name}: world expected silence but produced ${findings.length} finding(s): ${listed}`] : [];
+    if (findings.length === 0)
+        return [`${rule.name}: world expected a finding and produced none — the check is a no-op`];
+    if (world.match && !findings.some(f => world.match.test(f.message)))
+        return [`${rule.name}: world produced findings but none matched ${world.match}: ${listed}`];
+    return [];
+};
+/** A programmatic proof: every returned string is a failure. */
+const proveVerify = async (rule, verify) => (await verify()).map(msg => `${rule.name}: ${msg}`);
+/**
+ * Prove every rule still fires on a known violation and stays quiet on a clean case, through
+ * whichever proof the rule carries. A rule with none is itself a failure.
+ */
+export const runSelfTest = async (input) => {
+    const settings = input.settings ?? {};
+    const today = input.today ?? todayUtc();
+    const failures = [];
+    const checked = [];
+    for (const rule of input.rules) {
+        // A JS consumer can hand over a rule the type would have refused.
+        const proof = rule;
+        const forms = ['fixtures', 'world', 'verify'].filter(k => proof[k] !== undefined);
+        if (forms.length === 0) {
+            failures.push(`${rule.name}: no proof — add fixtures, world or verify`);
+            continue;
+        }
+        if (forms.length > 1) {
+            failures.push(`${rule.name}: carries more than one proof form — keep fixtures, world or verify`);
+            continue;
+        }
+        // A throwing check or a rejecting verify fails THIS rule; the rest still get proven.
+        try {
+            if (proof.fixtures)
+                failures.push(...await proveFixtures(rule, asList(proof.fixtures), settings, today));
+            else if (proof.world)
+                for (const w of asList(proof.world))
+                    failures.push(...await proveWorld(rule, w, settings, today));
+            else if (proof.verify)
+                failures.push(...await proveVerify(rule, proof.verify));
+        }
+        catch (e) {
+            failures.push(`${rule.name}: proof crashed — ${e instanceof Error ? e.message : String(e)}`);
+        }
+        checked.push(rule.name);
+    }
+    return { ok: failures.length === 0, failures, checked };
+};