@brighterly/lib-fe-codestyle 0.2.0 → 0.4.1

package/README.md

@@ -5,6 +5,10 @@ cs-app, app-tutor, app-admin.
 
 It holds the **mechanisms**. Domain rules stay in each app.
 
+**New here?** [docs/how-it-works.md](docs/how-it-works.md) — how a check reads real
+code, what the gate can and cannot cover, what is already enforced, how to extend it,
+and how to run it.
+
 ## Subpaths
 
 | Import | What it is |
@@ -53,28 +57,30 @@ exported as data.
 
 | Rule | Level | Checks |
 |---|---|---|
-| `_R1` | error | bare `localStorage` / `sessionStorage` — the accessor itself throws on Safari ITP and in-app webviews |
-| `_R2` | error | SCSS rules inline in a Vue `<style>` block instead of a referenced `.scss` file |
-| `_R3` | error | `JSON.parse` with no enclosing `try`/`catch` — a corrupt entry breaks that path permanently |
-| `_R4` | error | `@font-face` declaring a font *stack* — an invalid descriptor, so the browser drops the face silently |
-| `_C1` | warn | hand-rolled browser API with a VueUse equivalent |
-| `_C2` | warn | a component duplicating an existing UI-kit component name |
-| `_C3` | warn | a literal colour in SCSS instead of a design token |
-| `_C4` | warn | a hand-rolled date format string, or `toISOString()` |
-| `_C5` | warn | a type file outside the `types/<entity>/{enums,interfaces,types}.ts` structure |
-| `_C6` | warn | a raw `font-family` / `font-size` / `font-weight` declaration instead of the app's typography source |
-| `_C7` | warn | `<script>` attribute order differing from the app's canonical (`setup lang` vs `lang setup`) |
-
-Level discipline: `error` is reserved for crash-class rules (`_R*` — a visitor-facing
-throw or silent production breakage); `warn` is for conventions and style choices
-(`_C*`). A consumer's `levels` ceiling on an `_R*` rule is NOT the tool for an existing
-backlog — fix the call sites or allowlist the reviewed exceptions with reasons.
+| `core/R1` | warn* | bare `localStorage` / `sessionStorage` — the accessor itself throws on Safari ITP and in-app webviews |
+| `core/R2` | error | SCSS rules inline in a Vue `<style>` block instead of a referenced `.scss` file |
+| `core/R3` | warn* | `JSON.parse` with no enclosing `try`/`catch` — a corrupt entry breaks that path permanently |
+| `core/R4` | error | `@font-face` declaring a font *stack* — an invalid descriptor, so the browser drops the face silently |
+| `core/C1` | warn | hand-rolled browser API with a VueUse equivalent |
+| `core/C2` | warn | a component duplicating an existing UI-kit component name |
+| `core/C3` | warn | a literal colour in SCSS instead of a design token |
+| `core/C4` | warn | a hand-rolled date format string, or `toISOString()` |
+| `core/C5` | warn | a type file outside the `types/<entity>/{enums,interfaces,types}.ts` structure |
+| `core/C6` | warn | a raw `font-family` / `font-size` / `font-weight` declaration instead of the app's typography source |
+| `core/C7` | warn | `<script>` attribute order differing from the app's canonical (`setup lang` vs `lang setup`) |
+
+Level discipline: `error` is for crash-class rules (`core/R*`); `warn` is for
+conventions (`core/C*`). `core/R1`/`core/R3` (marked *) ship at `warn` **as an interim
+state** (2026-09-25): their fleet backlog is real code nobody has bandwidth to migrate
+and re-verify right now. Their target level is `error` — promote once the backlog
+clears (a breaking-style bump). `core/R2`/`core/R4` stay `error`. A consumer's `levels`
+ceiling is still never the tool for a backlog on an `error` rule — fix or allowlist.
 Underscore-prefixed SCSS partials (`_extends.scss`, `_colors-*.scss`, …) are declaration
-files by convention in every Brighterly app and are exempt from `_C3`/`_C6` wholesale.
+files by convention in every Brighterly app and are exempt from `core/C3`/`core/C6` wholesale.
 
-`_R*` were ported from land-app, where each was a production scar (as `R1`, `R7`, `R18`,
+`core/R*` were ported from land-app, where each was a production scar (as `R1`, `R7`, `R18`,
 `R28` — renumbered sequentially when the prefix landed, pre-publish, while no released
-version pinned the old tokens). `_C*` are conventions with
+version pinned the old tokens). `core/C*` are conventions with
 no incident behind them *yet* — they ship at `warn` so a consuming app can measure what they
 find before anyone decides to block on them. Promoting one to `error` is a **major** bump.
 
@@ -100,21 +106,22 @@ A shared rule must not hardcode a consuming app's paths. Each app declares them
 // invariants/config.mts
 export const settings = {
   safeStorageModule: 'safeLocalStorage from @helpers/safe-local-storage',
-  safeStorageFile:   'app/utils/helpers/safe-local-storage.ts', // _R1 auto-exempts the wrapper itself
+  safeStorageFile:   'app/utils/helpers/safe-local-storage.ts', // core/R1 auto-exempts the wrapper itself
   safeJsonParse:     'parseStoredJson() from @helpers/safe-local-storage',
   scssTokensFile:    'app/assets/scss/_colors.scss',
   uiKitRoot:         'app/components/UI',
   dateFormatModule:  'DateFormat from @ts-types/date/enums',
-  typesRoot:         'app/types',                              // _C5 (default shown)
-  typographySource:  'the font() mixin from @scss/_mixins.scss', // _C6 — cs-app points this at its AppText component instead
-  scriptAttrOrder:   'setup-first',                            // _C7 — or 'lang-first' (default 'setup-first')
+  typesRoot:         'app/types',                              // core/C5 (default shown)
+  typographySource:  'the font() mixin from @scss/_mixins.scss', // core/C6 — cs-app points this at its AppText component instead
+  scriptAttrOrder:   'setup-first',                            // core/C7 — or 'lang-first' (default 'setup-first')
+  selfTestFile:      'invariants/self-test.mts',               // its ignore-strings are fixture DATA — skipped by IG0/IG1
 }
 ```
 
 A missing key degrades the rule's *message*, never its firing. A rule that went quiet
 because a path was unset would be the exact silent failure this package exists to prevent.
-Two keys shape behaviour rather than the message — `typesRoot` (where `_C5` looks) and
-`scriptAttrOrder` (which direction `_C7` flags) — and both fall back to the documented
+Two keys shape behaviour rather than the message — `typesRoot` (where `core/C5` looks) and
+`scriptAttrOrder` (which direction `core/C7` flags) — and both fall back to the documented
 default above, so leaving them unset still never silences the rule.
 
 ## What consumers see in the IDE
@@ -124,7 +131,7 @@ requires opening this repo:
 
 - **`sharedRuleIds`** (from `…/invariants/rules`) — the catalog: one constant per rule,
   each JSDoc'd with level, what it checks, and the fix. Use them as `allowlists` /
-  `levels` keys (`[sharedRuleIds._C6]: 'off'`) and hover for the contract. A test pins
+  `levels` keys (`[sharedRuleIds.core/C6]: 'off'`) and hover for the contract. A test pins
   the catalog to the shipped rules, so it cannot drift.
 - **`SharedRuleSettings`** (from `…/invariants`) — annotate the app's `settings` const
   with it to get completion plus the per-key contract, and a type error on an invalid
@@ -171,18 +178,18 @@ The ESLint config and its seven rules are already plain `.mjs` and ship as-is.
 
 ## Rule IDs
 
-Shared rules carry an **underscore prefix**: `_R1`, `_C3`. App-local rules stay bare:
-`R1`, `B2`. The prefix marks provenance — an `_`-id is shipped by this package, never
+Shared rules carry the **`core/` prefix**: `core/R1`, `core/C3`. App-local rules stay bare:
+`R1`, `B2`. The prefix marks provenance — a `core/`-id is shipped by this package, never
 defined, renumbered or recycled in a consumer — and it keeps the two number lines
 independent: every app allocates its own `R1, R2, …` naturally, with no risk of
 colliding with a rule the package ships later. `run()` still exits 2 on a duplicate,
 so a collision is loud, not silent.
 
-Within the package each family is numbered sequentially with no gaps (`_R1`–`_R4`,
-`_C1`–`_C7`) — enforced by `test/invariants/rule-ids.test.ts`. The family letter keeps
+Within the package each family is numbered sequentially with no gaps (`core/R1`–`core/R4`,
+`core/C1`–`core/C7`) — enforced by `test/invariants/rule-ids.test.ts`. The family letter keeps
 meaning provenance — `R` regression scar, `B` business, `C` convention, `L`
-linter-owned — not topic. The underscore does **not** mean private (everything here is
-the public surface); it means "owned by the library, hands off the numbering."
+linter-owned — not topic. `core/` in a report means exactly one thing: this finding
+comes from the library, and its numbering is the library's to own.
 
 ## Versioning is about blocking power
 

package/dist/invariants/rules/convention.d.ts

@@ -2,12 +2,12 @@
  * Convention rules — preferences we chose, with no production incident behind them.
  * Advisory by default (`warn`): nudged, not policed, and droppable by team consensus.
  *
- * `_C1` was land-app's `C1`, and reads the same everywhere. `_C2`-`_C4` are new, and came out of a
+ * `core/C1` was land-app's `C1`, and reads the same everywhere. `core/C2`-`core/C4` 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.
  *
- * `_C5`-`_C7` (2026-09-23) come from the org's Notion frontend-conventions doc and from
+ * `core/C5`-`core/C7` (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.
  *

package/dist/invariants/rules/convention.js

@@ -2,12 +2,12 @@
  * Convention rules — preferences we chose, with no production incident behind them.
  * Advisory by default (`warn`): nudged, not policed, and droppable by team consensus.
  *
- * `_C1` was land-app's `C1`, and reads the same everywhere. `_C2`-`_C4` are new, and came out of a
+ * `core/C1` was land-app's `C1`, and reads the same everywhere. `core/C2`-`core/C4` 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.
  *
- * `_C5`-`_C7` (2026-09-23) come from the org's Notion frontend-conventions doc and from
+ * `core/C5`-`core/C7` (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.
  *
@@ -16,7 +16,7 @@
  */
 import { eachLine, setting } from './shared.js';
 const vueUseFirst = {
-    id: '_C1',
+    id: 'core/C1',
     title: 'hand-rolled browser API with a VueUse equivalent',
     level: 'warn',
     why: 'VueUse handles the lifecycle, SSR and error paths we otherwise re-implement (and forget to tear down) per call site',
@@ -47,7 +47,7 @@ const vueUseFirst = {
     },
 };
 const uiKitReuseFirst = {
-    id: '_C2',
+    id: 'core/C2',
     title: 'component duplicates an existing UI-kit component name',
     level: 'warn',
     once: true,
@@ -81,7 +81,7 @@ const uiKitReuseFirst = {
     },
 };
 const scssColourTokens = {
-    id: '_C3',
+    id: 'core/C3',
     title: 'literal colour in SCSS instead of a design token',
     level: 'warn',
     why: 'a hardcoded colour is invisible to the token system — it survives theme changes and palette corrections silently, and only a side-by-side screenshot shows the drift',
@@ -108,7 +108,7 @@ const scssColourTokens = {
     },
 };
 const dateFormatEnum = {
-    id: '_C4',
+    id: 'core/C4',
     title: 'hand-rolled date format string instead of the shared enum',
     level: 'warn',
     why: 'a format string written at the call site makes the date\'s shape an accident rather than a contract; `date`-validated endpoints accept several shapes, so a wrong one ships silently and surfaces later as bad data',
@@ -134,7 +134,7 @@ const dateFormatEnum = {
     },
 };
 const typesOrganization = {
-    id: '_C5',
+    id: 'core/C5',
     title: 'type file outside the entity-folder structure',
     level: 'warn',
     once: true,
@@ -166,7 +166,7 @@ const typesOrganization = {
     },
 };
 const typographySource = {
-    id: '_C6',
+    id: 'core/C6',
     title: 'raw font declaration instead of the app\'s typography source',
     level: 'warn',
     why: 'a hand-written font-family/size/weight is invisible to the UI-kit type scale — it survives font and scale changes silently, and the page drifts off-brand one declaration at a time (Notion: UI та стилі)',
@@ -179,7 +179,7 @@ const typographySource = {
         // Brighterly apps, decided 2026-09-24), plus non-underscore fonts/typography files.
         if (/\/(?:_[^/]*|fonts|typography)\.scss$/.test(file))
             return [];
-        // @font-face declares a face, not a usage — _R4 polices those blocks.
+        // @font-face declares a face, not a usage — core/R4 polices those blocks.
         const stripped = code.replace(/@font-face\s*\{[^}]*\}/g, m => m.replace(/[^\n]/g, ' '));
         return eachLine(stripped, (line, n) => {
             const m = /\bfont(?:-family|-size|-weight)?\s*:/.exec(line);
@@ -190,7 +190,7 @@ const typographySource = {
     },
 };
 const scriptAttrOrder = {
-    id: '_C7',
+    id: 'core/C7',
     title: 'script tag attribute order differs from the app canonical',
     level: 'warn',
     why: '<script setup lang="ts"> and <script lang="ts" setup> are compiler-equivalent, so nothing ever fails — the split just grows (723 vs 384 files in one app, Sep 2026) and every diff, codemod and grep has to handle both spellings',

package/dist/invariants/rules/fixtures.d.ts

@@ -10,7 +10,7 @@
 import type { Fixture } from '../self-test.js';
 export declare const commonFixtures: Record<string, Fixture>;
 /**
- * `_C2` and `_C5` are `once` rules over the whole file list — a single-file fixture
+ * `core/C2` and `core/C5` are `once` rules over the whole file list — a single-file fixture
  * cannot express them, so they are exempt from the fixture requirement and covered by
  * their own tests instead.
  */

package/dist/invariants/rules/fixtures.js

@@ -8,47 +8,47 @@
  * `bad` must produce at least one finding, `good` none.
  */
 export const commonFixtures = {
-    '_R1': {
+    'core/R1': {
         file: 'app/a.ts',
         bad: 'const t = localStorage.getItem("k")',
         good: 'const t = safeLocalStorage.getItem("k")',
     },
-    '_R2': {
+    'core/R2': {
         file: 'app/components/A.vue',
         bad: '<template><div /></template>\n<style scoped lang="scss">.a { color: red; }</style>',
         good: '<template><div /></template>\n<style scoped lang="scss" src="@scss/components/A.scss" />',
     },
-    '_R3': {
+    'core/R3': {
         file: 'app/a.ts',
         bad: 'const v = JSON.parse(raw)',
         good: 'let v = null\ntry { v = JSON.parse(raw) } catch { v = null }',
     },
-    '_R4': {
+    'core/R4': {
         file: 'app/assets/scss/fonts.scss',
         bad: '@font-face { font-family: Rubik, sans-serif; src: url(a.woff2); }',
         good: '@font-face { font-family: Rubik; src: url(a.woff2); }',
     },
-    '_C1': {
+    'core/C1': {
         file: 'app/a.ts',
         bad: 'window.addEventListener("resize", onResize)',
         good: 'useEventListener(window, "resize", onResize)',
     },
-    '_C3': {
+    'core/C3': {
         file: 'app/assets/scss/components/Card.scss',
         bad: '.card { color: #1f2937; }',
         good: '.card { color: $slate-800; }',
     },
-    '_C4': {
+    'core/C4': {
         file: 'app/a.ts',
         bad: "const d = dayjs().format('YYYY-MM-DD')",
         good: 'const d = dayjs().format(DateFormat.DefaultDate)',
     },
-    '_C6': {
+    'core/C6': {
         file: 'app/assets/scss/components/Card.scss',
         bad: '.card { font-size: 14px; }',
         good: '.card { @include font(14px, 20px); color: $slate-800; }',
     },
-    '_C7': {
+    'core/C7': {
         // Two script tags in OPPOSITE orders, so the bad fixture violates whichever
         // direction the consuming app declares in settings.scriptAttrOrder. The good
         // fixture carries no lang attribute, so it is clean under either canonical.
@@ -58,8 +58,8 @@ export const commonFixtures = {
     },
 };
 /**
- * `_C2` and `_C5` are `once` rules over the whole file list — a single-file fixture
+ * `core/C2` and `core/C5` are `once` rules over the whole file list — a single-file fixture
  * cannot express them, so they are exempt from the fixture requirement and covered by
  * their own tests instead.
  */
-export const commonSelfTestSkip = ['_C2', '_C5'];
+export const commonSelfTestSkip = ['core/C2', 'core/C5'];

package/dist/invariants/rules/index.d.ts

@@ -9,7 +9,7 @@
  *   C — convention: a preference we chose               → team consensus
  *   L — linter: a built-in ESLint rule                  → eslint.config.mjs
  *
- * Shared rule ids carry the underscore prefix (`_R1`); app-local ids stay bare (`R1`).
+ * Shared rule ids carry the `core/` prefix (`core/R1`); app-local ids stay bare (`R1`).
  * The prefix marks provenance and keeps the two number lines independent — and `run()`
  * still fails fast on a duplicate rather than letting an allowlist silently suppress
  * the wrong rule.
@@ -28,28 +28,28 @@ export declare const commonRules: Rule[];
  * instead. A test pins this map to `commonRules`, so it cannot drift.
  */
 export declare const sharedRuleIds: {
-    /** `error` — bare `localStorage`/`sessionStorage` access. The accessor itself throws SecurityError on Safari ITP, Firefox strict mode and in-app webviews; `if (localStorage)` guards throw too. Fix: the app's safe storage wrapper (`settings.safeStorageModule`). */
-    readonly _R1: "_R1";
+    /** `warn` (target `error`, interim 2026-09-25) — bare `localStorage`/`sessionStorage` access. The accessor itself throws SecurityError on Safari ITP, Firefox strict mode and in-app webviews; `if (localStorage)` guards throw too. Fix: the app's safe storage wrapper (`settings.safeStorageModule`). */
+    readonly 'core/R1': "core/R1";
     /** `error` — SCSS rules written inline in a Vue `<style>` block. Inline styles drift from the design tokens invisibly. Fix: a dedicated `.scss` file referenced via `<style scoped lang="scss" src="…" />`. */
-    readonly _R2: "_R2";
-    /** `error` — `JSON.parse` with no enclosing `try`/`catch`. A corrupt stored value crashes that code path permanently for the visitor. Fix: the app's guarded parse helper (`settings.safeJsonParse`) or try/catch. */
-    readonly _R3: "_R3";
+    readonly 'core/R2': "core/R2";
+    /** `warn` (target `error`, interim 2026-09-25) — `JSON.parse` with no enclosing `try`/`catch`. A corrupt stored value crashes that code path permanently for the visitor. Fix: the app's guarded parse helper (`settings.safeJsonParse`) or try/catch. */
+    readonly 'core/R3': "core/R3";
     /** `error` — `@font-face` declaring a font *stack*. Inside `@font-face`, `font-family` names the face being defined; a comma-separated stack is invalid and the browser drops the face silently. Fix: single family name inside, the stack on the selectors that use it. */
-    readonly _R4: "_R4";
+    readonly 'core/R4': "core/R4";
     /** `warn` — hand-rolled browser API with a VueUse equivalent (`new IntersectionObserver`, `addEventListener`, `setInterval`, …). VueUse owns the lifecycle/SSR/error paths. Fix: the composable named in the message, imported from `@vueuse/core`. */
-    readonly _C1: "_C1";
+    readonly 'core/C1': "core/C1";
     /** `warn` — a component whose filename duplicates a UI-kit component (`settings.uiKitRoot`). A same-name second component splits the design system in two. Fix: import or extend the UI-kit one. */
-    readonly _C2: "_C2";
+    readonly 'core/C2': "core/C2";
     /** `warn` — a literal colour (`#hex`, numeric `rgba()`) in SCSS/Vue instead of a palette token. Hardcoded colours survive theme and palette changes silently. Fix: a token from `settings.scssTokensFile`. */
-    readonly _C3: "_C3";
+    readonly 'core/C3': "core/C3";
     /** `warn` — a hand-rolled date format string (`'YYYY-MM-DD'`) or `toISOString()`. The date's shape becomes an accident instead of a contract. Fix: the shared enum (`settings.dateFormatModule`). */
-    readonly _C4: "_C4";
+    readonly 'core/C4': "core/C4";
     /** `warn` — a type file outside `types/<entity>/{enums,interfaces,types}.ts` (root under `settings.typesRoot`). Root-level or mixed-kind type files accrete unrelated entities. `.d.ts` ambient files are exempt. */
-    readonly _C5: "_C5";
+    readonly 'core/C5': "core/C5";
     /** `warn` — a raw `font-family`/`font-size`/`font-weight` declaration. Hand-written fonts drift off the UI-kit type scale silently. Fix: the app's typography source (`settings.typographySource`). */
-    readonly _C6: "_C6";
+    readonly 'core/C6': "core/C6";
     /** `warn` — `<script>` attribute order differing from the app canonical (`settings.scriptAttrOrder`, default `setup-first`). The two spellings are compiler-equivalent, so the split only ever grows. */
-    readonly _C7: "_C7";
+    readonly 'core/C7': "core/C7";
 };
 /** Union of every id the shared pack ships — for typing app config keys. */
 export type SharedRuleId = keyof typeof sharedRuleIds;

package/dist/invariants/rules/index.js

@@ -9,7 +9,7 @@
  *   C — convention: a preference we chose               → team consensus
  *   L — linter: a built-in ESLint rule                  → eslint.config.mjs
  *
- * Shared rule ids carry the underscore prefix (`_R1`); app-local ids stay bare (`R1`).
+ * Shared rule ids carry the `core/` prefix (`core/R1`); app-local ids stay bare (`R1`).
  * The prefix marks provenance and keeps the two number lines independent — and `run()`
  * still fails fast on a duplicate rather than letting an allowlist silently suppress
  * the wrong rule.
@@ -28,26 +28,26 @@ export const commonRules = [...rRules, ...cRules];
  * instead. A test pins this map to `commonRules`, so it cannot drift.
  */
 export const sharedRuleIds = {
-    /** `error` — bare `localStorage`/`sessionStorage` access. The accessor itself throws SecurityError on Safari ITP, Firefox strict mode and in-app webviews; `if (localStorage)` guards throw too. Fix: the app's safe storage wrapper (`settings.safeStorageModule`). */
-    _R1: '_R1',
+    /** `warn` (target `error`, interim 2026-09-25) — bare `localStorage`/`sessionStorage` access. The accessor itself throws SecurityError on Safari ITP, Firefox strict mode and in-app webviews; `if (localStorage)` guards throw too. Fix: the app's safe storage wrapper (`settings.safeStorageModule`). */
+    'core/R1': 'core/R1',
     /** `error` — SCSS rules written inline in a Vue `<style>` block. Inline styles drift from the design tokens invisibly. Fix: a dedicated `.scss` file referenced via `<style scoped lang="scss" src="…" />`. */
-    _R2: '_R2',
-    /** `error` — `JSON.parse` with no enclosing `try`/`catch`. A corrupt stored value crashes that code path permanently for the visitor. Fix: the app's guarded parse helper (`settings.safeJsonParse`) or try/catch. */
-    _R3: '_R3',
+    'core/R2': 'core/R2',
+    /** `warn` (target `error`, interim 2026-09-25) — `JSON.parse` with no enclosing `try`/`catch`. A corrupt stored value crashes that code path permanently for the visitor. Fix: the app's guarded parse helper (`settings.safeJsonParse`) or try/catch. */
+    'core/R3': 'core/R3',
     /** `error` — `@font-face` declaring a font *stack*. Inside `@font-face`, `font-family` names the face being defined; a comma-separated stack is invalid and the browser drops the face silently. Fix: single family name inside, the stack on the selectors that use it. */
-    _R4: '_R4',
+    'core/R4': 'core/R4',
     /** `warn` — hand-rolled browser API with a VueUse equivalent (`new IntersectionObserver`, `addEventListener`, `setInterval`, …). VueUse owns the lifecycle/SSR/error paths. Fix: the composable named in the message, imported from `@vueuse/core`. */
-    _C1: '_C1',
+    'core/C1': 'core/C1',
     /** `warn` — a component whose filename duplicates a UI-kit component (`settings.uiKitRoot`). A same-name second component splits the design system in two. Fix: import or extend the UI-kit one. */
-    _C2: '_C2',
+    'core/C2': 'core/C2',
     /** `warn` — a literal colour (`#hex`, numeric `rgba()`) in SCSS/Vue instead of a palette token. Hardcoded colours survive theme and palette changes silently. Fix: a token from `settings.scssTokensFile`. */
-    _C3: '_C3',
+    'core/C3': 'core/C3',
     /** `warn` — a hand-rolled date format string (`'YYYY-MM-DD'`) or `toISOString()`. The date's shape becomes an accident instead of a contract. Fix: the shared enum (`settings.dateFormatModule`). */
-    _C4: '_C4',
+    'core/C4': 'core/C4',
     /** `warn` — a type file outside `types/<entity>/{enums,interfaces,types}.ts` (root under `settings.typesRoot`). Root-level or mixed-kind type files accrete unrelated entities. `.d.ts` ambient files are exempt. */
-    _C5: '_C5',
+    'core/C5': 'core/C5',
     /** `warn` — a raw `font-family`/`font-size`/`font-weight` declaration. Hand-written fonts drift off the UI-kit type scale silently. Fix: the app's typography source (`settings.typographySource`). */
-    _C6: '_C6',
+    'core/C6': 'core/C6',
     /** `warn` — `<script>` attribute order differing from the app canonical (`settings.scriptAttrOrder`, default `setup-first`). The two spellings are compiler-equivalent, so the split only ever grows. */
-    _C7: '_C7',
+    'core/C7': 'core/C7',
 };

package/dist/invariants/rules/regression.js

@@ -12,9 +12,13 @@
 import { findJsonParseCalls } from '../ast.js';
 import { eachLine, setting } from './shared.js';
 const bareStorage = {
-    id: '_R1',
+    id: 'core/R1',
     title: 'bare localStorage / sessionStorage access',
-    level: 'error',
+    // Target level is `error` (crash-class). Shipped at `warn` since 2026-09-25: the fleet
+    // backlog (cs-app ~42 sites, main-app ~28) is real code the team has no bandwidth to
+    // migrate and re-verify right now, and a rushed storage migration is its own risk.
+    // Promote back to `error` once the backlog is cleared — that is a major-style bump.
+    level: 'warn',
     why: 'the bare API throws SecurityError on Safari ITP, Firefox strict mode and in-app webviews (Instagram/Facebook/TikTok) — the `if (localStorage)` guard does not help, the property accessor itself throws',
     fix: 'use the app\'s safe storage wrapper instead of the bare API',
     scope: ['app/**/*.{ts,vue}'],
@@ -37,7 +41,7 @@ const bareStorage = {
     },
 };
 const scssInStyleBlock = {
-    id: '_R2',
+    id: 'core/R2',
     title: 'SCSS rules inside a Vue <style> block',
     level: 'error',
     why: 'inline style blocks drift from the design tokens and are invisible to the SCSS build — the component stops sharing the system without anything failing',
@@ -66,9 +70,10 @@ const scssInStyleBlock = {
     },
 };
 const unguardedJsonParse = {
-    id: '_R3',
+    id: 'core/R3',
     title: 'unguarded JSON.parse',
-    level: 'error',
+    // Target level is `error` — see core/R1 above; same interim decision (2026-09-25).
+    level: 'warn',
     async: true,
     why: 'a truncated write or a hand-edited storage entry makes JSON.parse throw on every re-entry to that code path, until the visitor clears storage — the failure is permanent for them, not transient',
     fix: 'parse through the app\'s guarded helper, or wrap the call in try/catch',
@@ -83,7 +88,7 @@ const unguardedJsonParse = {
     },
 };
 const fontFaceStack = {
-    id: '_R4',
+    id: 'core/R4',
     title: '@font-face with a font stack instead of one family name',
     level: 'error',
     why: 'inside @font-face, font-family names the face being defined; a comma-separated stack is an invalid descriptor and the browser drops the whole face silently. Every page then renders in the fallback font, nothing errors, and only a side-by-side screenshot shows it',

package/dist/invariants/run.js

@@ -228,7 +228,9 @@ export const run = async (options) => {
     const ignoreCache = new Map();
     const ignoresFor = (file) => {
         if (!ignoreCache.has(file)) {
-            const src = read(file);
+            // The consumer's self-test file holds literal `invariant-ignore:` strings as
+            // fixture DATA — parsing them would report the fixtures themselves (IG0/IG1).
+            const src = file === settings.selfTestFile ? null : read(file);
             ignoreCache.set(file, src === null ? { suppressions: new Map(), unreasoned: [], comments: [] } : parseIgnores(src));
         }
         return ignoreCache.get(file);
@@ -348,6 +350,7 @@ export const run = async (options) => {
             live, retired, allowlists, levels, ignores,
             configFile,
             configSource: read(configFile) ?? undefined,
+            pathExists: p => read(p) !== null,
         })) {
             findings.push({ ruleId: 'IG1', level: 'error', ...v });
         }

package/dist/invariants/types.d.ts

@@ -17,8 +17,8 @@ export type Level = 'error' | 'warn' | 'off';
  * IDs are load-bearing (`--rule=`, `invariant-ignore:`, allowlists, levels) —
  * retire one, never recycle it.
  */
-/** App-local ids are bare; shared-pack ids carry the underscore prefix (`_R1`). */
-export type RuleId = `${'' | '_'}${'R' | 'B' | 'C' | 'L'}${number}`;
+/** App-local ids are bare; shared-pack ids carry the `core/` prefix (`core/R1`). */
+export type RuleId = `${'' | 'core/'}${'R' | 'B' | 'C' | 'L'}${number}`;
 /**
  * Meta rules. They police the escape hatch rather than the app, so they have no
  * family letter — but they are addressable exactly like any other rule
@@ -56,24 +56,26 @@ export interface ReportedFinding extends Finding {
  * the documented default), never its firing.
  */
 export interface SharedRuleSettings {
-    /** `_R1`/`_R3` fix messages: how this app names its safe storage wrapper, e.g. 'safeLocalStorage from @helpers/safe-local-storage'. */
+    /** `core/R1`/`core/R3` fix messages: how this app names its safe storage wrapper, e.g. 'safeLocalStorage from @helpers/safe-local-storage'. */
     safeStorageModule?: string;
-    /** `_R1`: 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'. */
+    /** `core/R1`: 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;
-    /** `_R3` fix message: the guarded parse helper, e.g. 'parseStoredJson() from @helpers/safe-local-storage'. */
+    /** `core/R3` fix message: the guarded parse helper, e.g. 'parseStoredJson() from @helpers/safe-local-storage'. */
     safeJsonParse?: string;
-    /** `_C3`: the palette file that legitimately DEFINES colour literals, e.g. 'app/assets/scss/_colors.scss'. */
+    /** `core/C3`: the palette file that legitimately DEFINES colour literals, e.g. 'app/assets/scss/_colors.scss'. */
     scssTokensFile?: string;
-    /** `_C2`: root of the UI-kit tree whose component names must not be duplicated. Default 'app/components/UI'. */
+    /** `core/C2`: root of the UI-kit tree whose component names must not be duplicated. Default 'app/components/UI'. */
     uiKitRoot?: string;
-    /** `_C4` fix message: the shared date-format enum, e.g. 'DateFormat from @ts-types/date/enums'. */
+    /** `core/C4` fix message: the shared date-format enum, e.g. 'DateFormat from @ts-types/date/enums'. */
     dateFormatModule?: string;
-    /** `_C5`: where entity type folders live. Default 'app/types'. */
+    /** `core/C5`: where entity type folders live. Default 'app/types'. */
     typesRoot?: string;
-    /** `_C6` fix message: this app's typography source — a mixin in some apps ('the font() mixin from @scss/_mixins.scss'), a component in others ('the AppText component'). */
+    /** `core/C6` fix message: this app's typography source — a mixin in some apps ('the font() mixin from @scss/_mixins.scss'), a component in others ('the AppText component'). */
     typographySource?: string;
-    /** `_C7`: which `<script>` attribute order is canonical in this app. Default 'setup-first' (`<script setup lang="ts">`). */
+    /** `core/C7`: which `<script>` attribute order is canonical in this app. Default 'setup-first' (`<script setup lang="ts">`). */
     scriptAttrOrder?: 'setup-first' | 'lang-first';
+    /** The consumer file whose `invariant-ignore:` strings are self-test FIXTURE DATA, not real suppressions — the engine skips ignore-parsing it entirely, replacing per-file IG0/IG1 allowlist boilerplate. E.g. 'invariants/self-test.mts'. */
+    selfTestFile?: string;
 }
 /** What a rule's `check` receives. */
 export interface RuleContext {
@@ -164,6 +166,8 @@ export interface DanglingRefInput {
     configFile?: string;
     /** Contents of `configFile`, so a stale key can be reported on its own line. */
     configSource?: string;
+    /** Answers "does this repo-relative file exist?" — enables the allowlist-path staleness check. */
+    pathExists?: (path: string) => boolean;
 }
 /** An invariant a built-in ESLint rule already covers. */
 export interface LinterOwnedRule {

package/dist/invariants/util.js

@@ -95,8 +95,8 @@ export const createReader = (root) => {
     };
 };
 export const toRelative = (root, p) => relative(root, resolve(root, p)).split(sep).join('/');
-// `_?` — shared-pack rules carry an underscore prefix (`_R1`); app-local rules are bare (`R1`).
-const IGNORE_RE = /invariant-ignore:\s*(_?[A-Z]{1,3}\d{1,3}(?:\s*,\s*_?[A-Z]{1,3}\d{1,3})*)\s*(?:—|–|--|-|:)?\s*(.*)$/;
+// `(?: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*(.*)$/;
 /**
  * Parse every `invariant-ignore:` comment in a file.
  * Returns { suppressions: Map<lineNumber, Set<ruleId>>, unreasoned: [{ line, ids }] }
@@ -198,7 +198,9 @@ export const findDanglingRuleRefs = (input) => {
         const start = src.indexOf(block);
         if (start === -1)
             return 1;
-        const rel = src.slice(start).search(new RegExp(`^\\s*${id}\\s*:`, 'm'));
+        // 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`;
@@ -212,6 +214,21 @@ export const findDanglingRuleRefs = (input) => {
             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))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brighterly/lib-fe-codestyle",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Shared invariant-validator engine, rule pack and ESLint config for Brighterly Nuxt frontend apps",