@brighterly/lib-fe-codestyle 1.0.0 → 1.0.1

package/dist/engine/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * 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 = 'off' | 'warn' | 'error';
+/**
+ * A rule's name — a plain kebab-case word (`no-bare-storage`), not a family-numbered id.
+ * Names are load-bearing (`--only=`, `codestyle-ignore:`, overrides): rename one only
+ * through the `renamed` registry, never by editing it in place.
+ */
+export type RuleName = string;
+/** 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;
+    /**
+     * What the finding is ABOUT, when that differs from the file it is reported against —
+     * a View checked through the route registry. Overrides match on `subject ?? file`, so
+     * an exemption is keyed by the thing checked, not by where the finding lands.
+     */
+    subject?: string;
+}
+/** A finding after the runner has attributed it to a rule and a level. */
+export interface ReportedFinding extends Finding {
+    rule: RuleName;
+    level: Level;
+}
+/**
+ * One override as it applies to one rule: the files it covers, the level it sets, the
+ * mandatory reason, and the `until YYYY-MM-DD` parsed out of that reason (null when it has
+ * none). The engine resolves them; a rule only reads them, to validate its own entries.
+ */
+export interface EffectiveOverride {
+    files: string[];
+    level: Level;
+    reason: string;
+    until: string | null;
+}
+/**
+ * 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 {
+    /** `no-bare-storage`/`guarded-json-parse` fix messages: how this app names its safe storage wrapper, e.g. 'safeLocalStorage from @helpers/safe-local-storage'. */
+    safeStorageModule?: string;
+    /** `no-bare-storage`: repo-relative path of the wrapper FILE itself — the one place bare storage access belongs, auto-exempted so no app has to allowlist its own wrapper. E.g. 'app/utils/helpers/safe-local-storage.ts'. */
+    safeStorageFile?: string;
+    /** `guarded-json-parse` fix message: the guarded parse helper, e.g. 'parseStoredJson() from @helpers/safe-local-storage'. */
+    safeJsonParse?: string;
+    /** `scss-tokens`: the palette file that legitimately DEFINES colour literals, e.g. 'app/assets/scss/_colors.scss'. */
+    scssTokensFile?: string;
+    /** `ui-kit-unique-names`: root of the UI-kit tree whose component names must not be duplicated. Default 'app/components/UI'. */
+    uiKitRoot?: string;
+    /** `date-format-enum` fix message: the shared date-format enum, e.g. 'DateFormat from @ts-types/date/enums'. */
+    dateFormatModule?: string;
+    /** `types-layout`: where entity type folders live. Default 'app/types'. */
+    typesRoot?: string;
+    /** `typography-source` 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;
+    /** `script-attr-order`: 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>>;
+    /**
+     * The effective overrides for THIS rule, so a rule can validate its own entries (one naming
+     * a View that is not registered) without importing the consumer's config.
+     */
+    overrides: EffectiveOverride[];
+    /** Today as an ISO date (`YYYY-MM-DD`): the runner sets the real one, the world harness the fixture's. */
+    today: string;
+}
+/** A `once: true` rule reads its own inputs, so it gets no per-file fields. */
+export type OnceRuleContext = Pick<RuleContext, 'read' | 'allFiles' | 'overrides' | 'today'> & Partial<RuleContext>;
+interface BaseRule {
+    name: RuleName;
+    /** 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[];
+    /**
+     * The rule cannot be suppressed with `invariant-ignore`; a comment naming it is
+     * itself a finding (IG2). For rules whose author is an AI: exceptions are made by
+     * a human in the rulebook (rule + fixture), never by the agent in the file under
+     * check — an AI writes a plausible reason for free.
+     * Honoured by the runner: the suppression lookup skips such rules, and the IG2
+     * block reports the attempt.
+     */
+    noIgnore?: boolean;
+    /** Set when `check` returns a promise, so the runner awaits it. */
+    async?: boolean;
+    /**
+     * Selection labels — `codestyle check --tags=e2e` runs every rule carrying `e2e`. Replaces
+     * the family letter as the way a gate picks its rules. Package rules carry none.
+     */
+    tags?: string[];
+    /**
+     * An override of this rule without an `until YYYY-MM-DD` in its reason is an error: every
+     * exemption is a debt with a date (a coverage gap, not a permanent pass).
+     */
+    exemptionsRequireUntil?: 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[]>;
+}
+/**
+ * One single-file fixture case. `bad` must produce >=1 finding, `good` must produce none.
+ * `excluded: true` asserts the FILE is matched by the rule's own `exclude` list — the case
+ * never runs the check; it proves the exclusion glob is right.
+ */
+export interface FixtureCase {
+    file: string;
+    bad?: string;
+    good?: string;
+    excluded?: true;
+}
+/**
+ * A multi-file fixture for a registry rule: a virtual repo fed through `read`/`allFiles`,
+ * and whether the rule must report on it. `match` narrows "a finding" to one whose message
+ * matches; `today` pins the date an `until` comparison sees.
+ */
+export interface WorldFixture {
+    files: Record<string, string>;
+    expect: 'finding' | 'silence';
+    match?: RegExp;
+    today?: string;
+}
+/**
+ * How a rule proves it still fires. Exactly one form is mandatory — a rule that has silently
+ * stopped matching finds nothing, which is indistinguishable from a clean codebase.
+ *   fixtures — single-file cases (the 0.5.x grammar)
+ *   world    — a virtual repo, for rules that read several files
+ *   verify   — a programmatic proof returning failure messages
+ */
+export type Proof = {
+    fixtures: FixtureCase | FixtureCase[];
+} | {
+    world: WorldFixture | WorldFixture[];
+} | {
+    verify: () => string[] | Promise<string[]>;
+};
+/**
+ * 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. Either way a rule object
+ * always carries one proof.
+ */
+export type Rule = (FileRule | OnceRule) & Proof;
+/**
+ * A rule whose check lives elsewhere — an ESLint rule or a test — declared so its name stays
+ * live (no IG1 on a suppression naming it), appears in the inventory with its owner, and
+ * produces no findings here.
+ */
+export interface ExternalRule {
+    name: RuleName;
+    title: string;
+    why: string;
+    owner: 'eslint' | 'test';
+    /** The ESLint rule id or the test file that owns the check. */
+    ref: string;
+    /** Selection labels, so a tag-selected doc (`codestyle docs`) can list the declaration. Never selected for a run. */
+    tags?: string[];
+}
+/** Anything a consumer may list as a rule. */
+export type AnyRule = Rule | ExternalRule;
+/** An external declaration has `owner` set to one of the two owners; `defineConfig` rejects any other `owner`. */
+export declare const isExternal: (r: AnyRule) => r is ExternalRule;
+/** Everything rule IG1 needs, passed in so the check stays pure and testable. */
+export interface DanglingRefInput {
+    /** Names of rules currently loaded. */
+    live: Set<string>;
+    /** Old name → new name, so a stale reference says where the rule went. */
+    renamed?: Record<string, string>;
+    /** Every `codestyle-ignore` comment found in the scanned set. */
+    ignores: {
+        file: string;
+        line: number;
+        ids: string[];
+    }[];
+    /** The consumer's config file, for findings about it. */
+    configFile?: string;
+}
+export {};

package/dist/{invariants → engine}/types.js

@@ -6,4 +6,5 @@
  * mechanism that has no resolver, a level that is not a real level. Those were
  * all silently ignored while this was plain JavaScript.
  */
-export {};
+/** An external declaration has `owner` set to one of the two owners; `defineConfig` rejects any other `owner`. */
+export const isExternal = (r) => 'owner' in r && (r.owner === 'eslint' || r.owner === 'test');

package/dist/{invariants → engine}/util.d.ts

@@ -1,10 +1,10 @@
 /**
  * Shared plumbing for validate-invariants: file walking, glob matching,
- * a read cache, and the `invariant-ignore` escape hatch.
+ * a read cache, and the `codestyle-ignore` escape hatch.
  *
  * No dependencies — this runs in pre-commit, so it must not need an install.
  */
-import type { DanglingRefInput, Finding, Level, Levels, MetaRuleId } from './types.js';
+import type { DanglingRefInput, Finding, Level } from './types.js';
 /**
  * Minimal glob → RegExp. Supports `**`, `*`, `?` and `{a,b}`.
  * Deliberately not a full glob implementation: rule scopes are simple by
@@ -12,16 +12,19 @@ import type { DanglingRefInput, Finding, Level, Levels, MetaRuleId } from './typ
  */
 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[];
+/**
+ * Recursively list repo-relative file paths under `dir` (`''` = the root), POSIX separators.
+ * `skip` prunes an entry — a directory is not descended into — by its repo-relative path.
+ */
+export declare const walk: (root: string, dir: string, skip?: (rel: string) => boolean) => 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 }] }
+ * Parse every `codestyle-ignore:` (or legacy `invariant-ignore:`) comment in a file.
+ * `legacy` says whether the file used the old spelling, so the runner can warn once.
  *
  * 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.
+ * `// codestyle-ignore: no-bare-storage — 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.
  */
@@ -35,6 +38,7 @@ export declare const parseIgnores: (source: string) => {
         line: number;
         ids: string[];
     }[];
+    legacy: boolean;
 };
 /**
  * Blanks comment bodies in place: every line and every non-comment character stays where it was,
@@ -64,19 +68,18 @@ export declare const sliceObjectLiteral: (source: string, fromIndex: number) =>
 /** 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.
+ * Every `codestyle-ignore` comment naming a rule that is not live.
  *
- * 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.
+ * A stale suppression is inert and silent — which is what made "retire a name, never
+ * recycle it" a discipline rather than a check. This is the check. A renamed rule says
+ * where it went.
  *
- * Pure by design: the caller supplies the live set and the config, so the
- * self-test can exercise it without touching the repo.
+ * Pure by design: the caller supplies the live set, so the self-test can exercise it
+ * without touching the repo.
  */
 export declare const findDanglingRuleRefs: (input: DanglingRefInput) => Finding[];
 /**
- * `invariant-ignore` comments that name a rule declared `noIgnore` (IG2). The
+ * `codestyle-ignore` comments that name a rule declared `noIgnore` (IG2). The
  * runner never honours such a comment; reporting it makes the attempt visible so a
  * reviewer sees the intent and an AI author learns the rule cannot be argued with
  * in the file under check.
@@ -108,31 +111,20 @@ export declare const findForbiddenSuppressions: (ignores: {
  */
 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?: MetaRuleId[];
-}) => 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;
-/**
- * The `until YYYY-MM-DD` an allowlist reason may carry. A rule may require one — a coverage gap is
+ * The `until YYYY-MM-DD` an override's reason may carry. A rule may require one — a coverage gap is
  * a debt with a date, not a permanent exemption — and report the entry once the date has passed.
  * ISO dates compare as strings, so the caller needs no Date arithmetic.
  */
 export declare const exemptionExpiry: (reason: string) => string | null;
+/** A real calendar date in `YYYY-MM-DD`: `2026-13-40` has the right shape and no such day (UTC round-trip). */
+export declare const isRealDate: (iso: string) => boolean;
+/**
+ * The token after `until` when the author clearly meant a date but did not write a real
+ * `YYYY-MM-DD` one (`until 2026-1-5`, `until 05/01/2026`, `until 2026-10-311`) — otherwise null.
+ * `exemptionExpiry` cannot see such a token, so without this check the exemption would silently
+ * never expire. Only a digit-led token counts: prose (`until the redesign lands`) is a reason
+ * with no expiry. Trailing sentence punctuation (`until 2026-10-31.`) is not part of the token.
+ */
+export declare const malformedUntil: (reason: string) => string | null;
+/** Today as `YYYY-MM-DD` (UTC) — the one place the engine reads the clock for a date. */
+export declare const todayUtc: () => string;

package/dist/{invariants → engine}/util.js

@@ -1,6 +1,6 @@
 /**
  * Shared plumbing for validate-invariants: file walking, glob matching,
- * a read cache, and the `invariant-ignore` escape hatch.
+ * a read cache, and the `codestyle-ignore` escape hatch.
  *
  * No dependencies — this runs in pre-commit, so it must not need an install.
  */
@@ -56,8 +56,11 @@ export const globToRegExp = (glob) => {
     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) => {
+/**
+ * Recursively list repo-relative file paths under `dir` (`''` = the root), POSIX separators.
+ * `skip` prunes an entry — a directory is not descended into — by its repo-relative path.
+ */
+export const walk = (root, dir, skip = () => false) => {
     const out = [];
     const abs = resolve(root, dir);
     let entries;
@@ -68,13 +71,13 @@ export const walk = (root, dir) => {
         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}`;
+        const child = dir ? `${dir}/${e.name}` : e.name;
+        if (skip(child))
+            continue;
         if (e.isDirectory())
-            out.push(...walk(root, child));
+            out.push(...walk(root, child, skip));
         else if (e.isFile())
             out.push(child);
     }
@@ -95,14 +98,17 @@ export const createReader = (root) => {
     };
 };
 export const toRelative = (root, p) => relative(root, resolve(root, p)).split(sep).join('/');
-// `(?:core\/)?` — shared-pack rules carry the core/ prefix (`core/R1`); app-local rules are bare (`R1`).
-const IGNORE_RE = /invariant-ignore:\s*((?:core\/)?[A-Z]{1,3}\d{1,3}(?:\s*,\s*(?:core\/)?[A-Z]{1,3}\d{1,3})*)\s*(?:—|–|--|-|:)?\s*(.*)$/;
+// A rule name is kebab-case (`no-bare-storage`) or a family-numbered app id (`R1`). A 0.5.x
+// package id (`core/` + family + number) still parses, so IG1 can say what it was renamed to.
+const RULE_TOKEN = String.raw `(?:(?:core\/)?[A-Z]{1,3}\d{1,3}|[a-z][a-z0-9]*(?:-[a-z0-9]+)*)`;
+// `codestyle-ignore:` is the 1.0 spelling; `invariant-ignore:` is accepted through 1.x as an alias.
+const IGNORE_RE = new RegExp(String.raw `(codestyle|invariant)-ignore:\s*(${RULE_TOKEN}(?:\s*,\s*${RULE_TOKEN})*)\s*(?:—|–|--|-|:)?\s*(.*)$`);
 /**
- * Parse every `invariant-ignore:` comment in a file.
- * Returns { suppressions: Map<lineNumber, Set<ruleId>>, unreasoned: [{ line, ids }] }
+ * Parse every `codestyle-ignore:` (or legacy `invariant-ignore:`) comment in a file.
+ * `legacy` says whether the file used the old spelling, so the runner can warn once.
  *
  * 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.
+ * `// codestyle-ignore: no-bare-storage — 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.
  */
@@ -110,13 +116,16 @@ export const parseIgnores = (source) => {
     const suppressions = new Map();
     const unreasoned = [];
     const comments = [];
+    let legacy = false;
     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();
+        if (m[1] === 'invariant')
+            legacy = true;
+        const ids = (m[2] ?? '').split(',').map(s => s.trim());
+        const reason = (m[3] || '').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
@@ -132,7 +141,7 @@ export const parseIgnores = (source) => {
             ids.forEach(id => suppressions.get(target).add(id));
         }
     });
-    return { suppressions, unreasoned, comments };
+    return { suppressions, unreasoned, comments, legacy };
 };
 /**
  * Blanks comment bodies in place: every line and every non-comment character stays where it was,
@@ -322,71 +331,30 @@ export const sliceObjectLiteral = (source, fromIndex) => {
 /** 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.
+ * Every `codestyle-ignore` comment naming a rule that is not live.
  *
- * 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.
+ * A stale suppression is inert and silent — which is what made "retire a name, never
+ * recycle it" a discipline rather than a check. This is the check. A renamed rule says
+ * where it went.
  *
- * Pure by design: the caller supplies the live set and the config, so the
- * self-test can exercise it without touching the repo.
+ * Pure by design: the caller supplies the live set, 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 { live, renamed = {}, ignores } = input;
+    const explain = (id) => Object.hasOwn(renamed, id) ? `"${id}" was renamed to "${renamed[id]}"` : `${id} does not name any rule`;
     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;
-        // Ids may contain `/` (core/R1) and appear as quoted keys — escape and allow quotes.
-        const escaped = id.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
-        const rel = src.slice(start).search(new RegExp(`^\\s*(?:'|")?${escaped}(?:'|")?\\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` });
-    }
-    // Allowlist PATHS had no staleness guard: an entry whose file is gone (or renamed)
-    // is inert and silent. Found live in app-funnels — a dead BtnAuthGoogle.vue entry
-    // survived a fork divergence (2026-09-25). Checked only when the caller can answer
-    // existence, so the self-test can still exercise this function without a filesystem.
-    if (input.pathExists) {
-        for (const [id, entries] of Object.entries(allowlists)) {
-            if (!live.has(id))
-                continue; // the dead-id finding above already covers the whole entry
-            for (const path of Object.keys(entries ?? {})) {
-                if (input.pathExists(path))
-                    continue;
-                out.push({ file: configFile, line: lineOfKey('allowlists', path), message: `allowlists["${id}"] names "${path}", but no such file exists — the exemption is inert; drop it or fix the path` });
-            }
-        }
-    }
     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` });
+            out.push({ file, line, message: `codestyle-ignore names "${id}", but ${explain(id)} — this suppression is inert; drop it or name a live rule` });
         }
     }
     return out;
 };
 /**
- * `invariant-ignore` comments that name a rule declared `noIgnore` (IG2). The
+ * `codestyle-ignore` comments that name a rule declared `noIgnore` (IG2). The
  * runner never honours such a comment; reporting it makes the attempt visible so a
  * reviewer sees the intent and an AI author learns the rule cannot be argued with
  * in the file under check.
@@ -394,7 +362,7 @@ export const findDanglingRuleRefs = (input) => {
 export const findForbiddenSuppressions = (ignores, noIgnoreIds) => ignores.flatMap(({ file, line, ids }) => ids.filter(id => noIgnoreIds.has(id)).map(id => ({
     file,
     line,
-    message: `invariant-ignore names "${id}", a noIgnore rule — this suppression is inert and the attempt is reported`,
+    message: `codestyle-ignore names "${id}", a noIgnore rule — this suppression is inert and the attempt is reported`,
 })));
 const LEVEL_RANK = { off: 0, warn: 1, error: 2 };
 /**
@@ -425,26 +393,31 @@ export const resolveFindingLevel = (ruleLevel, override, finding) => {
     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;
-/**
- * The `until YYYY-MM-DD` an allowlist reason may carry. A rule may require one — a coverage gap is
+ * The `until YYYY-MM-DD` an override's reason may carry. A rule may require one — a coverage gap is
  * a debt with a date, not a permanent exemption — and report the entry once the date has passed.
  * ISO dates compare as strings, so the caller needs no Date arithmetic.
  */
 export const exemptionExpiry = (reason) => reason.match(/\buntil\s+(\d{4}-\d{2}-\d{2})\b/)?.[1] ?? null;
+/** A real calendar date in `YYYY-MM-DD`: `2026-13-40` has the right shape and no such day (UTC round-trip). */
+export const isRealDate = (iso) => {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(iso))
+        return false;
+    const [y, m, d] = iso.split('-').map(Number);
+    const date = new Date(Date.UTC(y, m - 1, d));
+    return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;
+};
+/**
+ * The token after `until` when the author clearly meant a date but did not write a real
+ * `YYYY-MM-DD` one (`until 2026-1-5`, `until 05/01/2026`, `until 2026-10-311`) — otherwise null.
+ * `exemptionExpiry` cannot see such a token, so without this check the exemption would silently
+ * never expire. Only a digit-led token counts: prose (`until the redesign lands`) is a reason
+ * with no expiry. Trailing sentence punctuation (`until 2026-10-31.`) is not part of the token.
+ */
+export const malformedUntil = (reason) => {
+    const tok = reason.match(/\buntil\s+(\d\S*)/)?.[1]?.replace(/[.,;:!?)\]]+$/, '');
+    if (tok === undefined)
+        return null;
+    return isRealDate(tok) ? null : tok;
+};
+/** Today as `YYYY-MM-DD` (UTC) — the one place the engine reads the clock for a date. */
+export const todayUtc = () => new Date().toISOString().slice(0, 10);

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The public surface of `@brighterly/lib-fe-codestyle`, in three groups:
+ *   - config: `defineConfig` (and `ConfigError`) plus the types of `codestyle.config.ts`;
+ *   - contract: the types a custom rule is written against — `Rule`, its contexts, its proofs;
+ *   - helpers: the text and AST utilities custom rules share, and the package's rule names.
+ * Everything else — the runner, the registry, overrides, self-test, docs, migrate — is reached
+ * through the `codestyle` binary, never imported.
+ */
+export { ConfigError, defineConfig } from './config/define-config.js';
+export type { CodestyleConfig, DocsEntry, OverrideEntry, ResolvedConfig, Step } from './config/schema.js';
+export type { AnyRule, EffectiveOverride, ExternalRule, FileRule, Finding, FixtureCase, Level, OnceRule, OnceRuleContext, Proof, Rule, RuleContext, RuleName, SharedRuleSettings, WorldFixture, } from './engine/types.js';
+export { eachLine, packageRuleNames, setting } from './rules/index.js';
+export type { LineFn, PackageRuleName } from './rules/index.js';
+export { exemptionExpiry, globToRegExp, lineOf, matchesAny, sliceObjectLiteral, stringKeysOf, stripCodeComments, walk, } from './engine/util.js';
+export { allElements, attrOf, elementsByTag, findGeneratedTests, findInlineLiterals, findJsonParseCalls, findOptionLiterals, findSharedContainers, findSharedMutables, findStaticImports, findUnawaitedCalls, templateElements, } from './engine/ast.js';
+export type { InlineLiteral, OptionLiteral, TemplateAttr, TemplateEl } from './engine/ast.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * The public surface of `@brighterly/lib-fe-codestyle`, in three groups:
+ *   - config: `defineConfig` (and `ConfigError`) plus the types of `codestyle.config.ts`;
+ *   - contract: the types a custom rule is written against — `Rule`, its contexts, its proofs;
+ *   - helpers: the text and AST utilities custom rules share, and the package's rule names.
+ * Everything else — the runner, the registry, overrides, self-test, docs, migrate — is reached
+ * through the `codestyle` binary, never imported.
+ */
+// ── config ────────────────────────────────────────────────────────────────
+export { ConfigError, defineConfig } from './config/define-config.js';
+// ── helpers ───────────────────────────────────────────────────────────────
+export { eachLine, packageRuleNames, setting } from './rules/index.js';
+export { exemptionExpiry, globToRegExp, lineOf, matchesAny, sliceObjectLiteral, stringKeysOf, stripCodeComments, walk, } from './engine/util.js';
+export { allElements, attrOf, elementsByTag, findGeneratedTests, findInlineLiterals, findJsonParseCalls, findOptionLiterals, findSharedContainers, findSharedMutables, findStaticImports, findUnawaitedCalls, templateElements, } from './engine/ast.js';

package/dist/rules/convention.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Convention rules — preferences we chose, with no production incident behind them.
+ * Advisory by default (`warn`): nudged, not policed, and droppable by team consensus.
+ *
+ * `vueuse-first` was land-app's `C1`, and reads the same everywhere. `ui-kit-unique-names`,
+ * `scss-tokens` and `date-format-enum` are new, and came out of a real code review rather
+ * than an outage: a developer shipped a component that duplicated an existing UI-kit one,
+ * with colours that were not design tokens. Review caught it; nothing automated did,
+ * because the conventions existed only in reviewers\' heads.
+ *
+ * `types-layout`, `typography-source` and `script-attr-order` (2026-09-23) come from the
+ * org's Notion frontend-conventions doc and from mining 400 PR review comments across the
+ * four apps: entity-folder type organization, typography through the app's declared source,
+ * and one canonical <script> attribute order.
+ *
+ * They ship at `warn` so each consuming app can measure what they find before anyone
+ * decides to block on them. Promoting one to `error` is a major version bump.
+ */
+import type { Rule } from '../engine/types.js';
+export declare const cRules: Rule[];