@brighterly/lib-fe-codestyle 0.3.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,9 +57,9 @@ exported as data.
 
 | Rule | Level | Checks |
 |---|---|---|
-| `core/R1` | error | bare `localStorage` / `sessionStorage` — the accessor itself throws on Safari ITP and in-app webviews |
+| `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` | error | `JSON.parse` with no enclosing `try`/`catch` — a corrupt entry breaks that path permanently |
+| `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 |
@@ -65,10 +69,12 @@ exported as data.
 | `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 reserved for crash-class rules (`core/R*` — a visitor-facing
-throw or silent production breakage); `warn` is for conventions and style choices
-(`core/C*`). A consumer's `levels` ceiling on an `core/R*` rule is NOT the tool for an existing
-backlog — fix the call sites or allowlist the reviewed exceptions with reasons.
+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 `core/C3`/`core/C6` wholesale.
 
@@ -108,6 +114,7 @@ export const settings = {
   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
 }
 ```
 

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

@@ -28,11 +28,11 @@ 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`). */
+    /** `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 'core/R2': "core/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. */
+    /** `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 'core/R4': "core/R4";

package/dist/invariants/rules/index.js

@@ -28,11 +28,11 @@ 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`). */
+    /** `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="…" />`. */
     'core/R2': 'core/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. */
+    /** `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. */
     'core/R4': 'core/R4',

package/dist/invariants/rules/regression.js

@@ -14,7 +14,11 @@ import { eachLine, setting } from './shared.js';
 const bareStorage = {
     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}'],
@@ -68,7 +72,8 @@ const scssInStyleBlock = {
 const unguardedJsonParse = {
     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',

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

@@ -74,6 +74,8 @@ export interface SharedRuleSettings {
     typographySource?: string;
     /** `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

@@ -214,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.3.0",
+  "version": "0.4.1",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Shared invariant-validator engine, rule pack and ESLint config for Brighterly Nuxt frontend apps",