@brighterly/lib-fe-codestyle 1.0.0 → 1.0.2

package/dist/{invariants/rules → rules}/convention.js

@@ -2,28 +2,46 @@
  * Convention rules — preferences we chose, with no production incident behind them.
  * Advisory by default (`warn`): nudged, not policed, and droppable by team consensus.
  *
- * `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.
+ * `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.
  *
- * `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.
+ * `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 { componentScopeLines } from '../engine/ast.js';
 import { eachLine, setting } from './shared.js';
 const vueUseFirst = {
-    id: 'core/C1',
+    name: 'vueuse-first',
     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',
     fix: 'use the VueUse composable named in the message, imported explicitly from @vueuse/core',
     scope: ['app/**/*.{ts,vue}'],
     exclude: ['app/tests/**', 'app/test/**'],
-    check: ({ file, code }) => {
+    async: true,
+    // Only lines inside a component lifetime count (`<script setup>`, a `use…` composable, a `setup()`
+    // method). A store action, a plugin or a plain helper has no effect scope, so the VueUse composable
+    // the message recommends would leak there — those lines are silent by construction.
+    fixtures: [
+        { file: 'app/composables/a.ts', bad: 'export const useA = () => {\n  window.addEventListener("resize", onResize)\n}', good: 'export const useA = () => {\n  useEventListener(window, "resize", onResize)\n}' },
+        { file: 'app/composables/b.ts', bad: 'export function useB() {\n  const run = () => setTimeout(tick, 10)\n  return { run }\n}' },
+        { file: 'app/components/A.vue', bad: '<script setup lang="ts">\nsetTimeout(tick, 10)\n</script>', good: '<script setup lang="ts">\nuseTimeoutFn(tick, 10)\n</script>' },
+        { file: 'app/components/B.vue', bad: '<script lang="ts">\nexport default defineComponent({\n  setup() {\n    setInterval(tick, 10)\n  },\n})\n</script>' },
+        { file: 'app/stores/quiz/actions.ts', good: 'export const actions = {\n  setLazyStep(payload) {\n    setTimeout(() => setStep(payload), 300)\n  },\n}' },
+        { file: 'app/composables/tools/scroll.ts', good: 'export const scrollIntoViewIfHidden = (el) => {\n  new IntersectionObserver(cb).observe(el)\n}' },
+        { file: 'app/composables/tools/sdk.ts', good: 'const init = () => {\n  load().catch(() => setTimeout(init, 800))\n}' },
+        { file: 'app/plugins/axios.client.ts', good: 'export default defineNuxtPlugin(() => {\n  setTimeout(refresh, 1000)\n})' },
+    ],
+    check: async ({ file, source, code }) => {
+        const scoped = await componentScopeLines(file, source);
         const map = [
             [/new\s+IntersectionObserver\s*\(/, 'useIntersectionObserver'],
             [/new\s+ResizeObserver\s*\(/, 'useResizeObserver'],
@@ -38,6 +56,8 @@ const vueUseFirst = {
             [/\b(?:window\s*\.\s*)?setTimeout\s*\(/, 'useTimeoutFn'],
         ];
         return eachLine(code, (line, n) => {
+            if (!scoped.has(n))
+                return null;
             for (const [re, fn] of map) {
                 if (re.test(line))
                     return { file, line: n, message: `hand-rolled browser API — use ${fn} from @vueuse/core` };
@@ -47,13 +67,25 @@ const vueUseFirst = {
     },
 };
 const uiKitReuseFirst = {
-    id: 'core/C2',
+    name: 'ui-kit-unique-names',
     title: 'component duplicates an existing UI-kit component name',
     level: 'warn',
     once: true,
     why: 'a second component with the same name as a UI-kit one splits the design system in two — the new one drifts on colours, spacing and a11y, and nothing fails. Reviewers catch it by memory or not at all',
     fix: 'import the UI-kit component, or extend it. A new one is justified only when the existing cannot express the case without a breaking prop change — say so in the PR body',
     scope: ['app/components/**/*.vue'],
+    // A `once` rule over the whole file list: a single-file case cannot express it.
+    world: [
+        {
+            files: { 'app/components/UI/Buttons/AppButton.vue': '<template />', 'app/components/Pages/Quiz/AppButton.vue': '<template />' },
+            expect: 'finding',
+            match: /duplicates the UI-kit component/,
+        },
+        {
+            files: { 'app/components/UI/Buttons/AppButton.vue': '<template />', 'app/components/Pages/Quiz/QuizButton.vue': '<template />' },
+            expect: 'silence',
+        },
+    ],
     check: ({ allFiles, settings }) => {
         const files = allFiles ?? [];
         const uiKitRoot = settings?.uiKitRoot ?? 'app/components/UI';
@@ -101,12 +133,26 @@ const onlyStyleBlocks = (source) => {
     return out + source.slice(last).replace(/[^\n]/g, ' ');
 };
 const scssColourTokens = {
-    id: 'core/C3',
+    name: 'scss-tokens',
     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',
     fix: 'use a token variable from the palette file; if the colour is genuinely new, add it to the palette first',
     scope: ['app/assets/scss/**/*.scss', 'app/components/**/*.vue'],
+    fixtures: [
+        {
+            file: 'app/assets/scss/components/Card.scss',
+            bad: '.card { color: #1f2937; }',
+            good: '.card { color: $slate-800; }',
+        },
+        // In a .vue file only the <style> block is a stylesheet: an SVG fill in the
+        // template has no place to put a $token, so it must stay quiet.
+        {
+            file: 'app/components/UI/Icons/IconLeaf.vue',
+            bad: '<template><svg><path fill="currentColor" /></svg></template>\n<style scoped lang="scss">\n.icon { color: #e2e8f0; }\n</style>',
+            good: '<template><svg><path fill="#E2E8F0" /></svg></template>\n<style scoped lang="scss">\n.icon { color: $slate-200; }\n</style>',
+        },
+    ],
     check: ({ file, code, settings }) => {
         // Underscore-prefixed partials are DECLARATION files by SCSS convention in every
         // Brighterly app (_colors, _vars, _extends, _mixins, brand variants, …) — they are
@@ -129,13 +175,33 @@ const scssColourTokens = {
     },
 };
 const dateFormatEnum = {
-    id: 'core/C4',
+    name: 'date-format-enum',
     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',
     fix: 'format through the shared DateFormat enum; never hand-roll a format string or use toISOString()',
     scope: ['app/**/*.{ts,vue}'],
     exclude: ['app/tests/**', 'app/test/**'],
+    fixtures: [
+        {
+            file: 'app/a.ts',
+            bad: "const d = dayjs().format('YYYY-MM-DD')",
+            good: 'const d = dayjs().format(DateFormat.DefaultDate)',
+        },
+        // The day-extraction misuse fires; a bare toISOString() (an API timestamp) and the
+        // epoch duration trick do not.
+        {
+            file: 'app/b.ts',
+            bad: "const day = new Date().toISOString().split('T')[0]",
+            good: 'const generatedAt = dayjs().toISOString()\nconst duration = new Date(s * 1000).toISOString().slice(14, 19)',
+        },
+        // Every letter run must be a real dayjs token — an answer label that happens to fit
+        // the char class ('ADHD / ADD' carries a DD) is not a format string.
+        {
+            file: 'app/c.ts',
+            good: "const option = { code: 'ADHD_ADD', label: 'ADHD / ADD' }",
+        },
+    ],
     check: ({ file, code, settings }) => {
         const dateModule = setting({ settings }, 'dateFormatModule', 'the shared DateFormat enum');
         // The module that DEFINES the formats is the one place the literals belong.
@@ -162,13 +228,21 @@ const dateFormatEnum = {
     },
 };
 const typesOrganization = {
-    id: 'core/C5',
+    name: 'types-layout',
     title: 'type file outside the entity-folder structure',
     level: 'warn',
     once: true,
     why: 'types grouped by business entity are findable and own their imports; a root-level types.ts or a mixed-kind file accretes unrelated entities until nobody can say what depends on it (Notion: Types Organization, §1/§5)',
     fix: 'move every type into <typesRoot>/<entity>/{enums,interfaces,types}.ts — enums in enums.ts, interfaces in interfaces.ts, aliases/unions in types.ts',
     scope: ['app/types/**/*.ts'],
+    // A `once` rule over the whole file list: a single-file case cannot express it.
+    world: [
+        { files: { 'app/types/global-types.ts': 'export type A = 1' }, expect: 'finding', match: /directly under app\/types/ },
+        {
+            files: { 'app/types/quiz/enums.ts': '', 'app/types/quiz/interfaces.ts': '', 'app/types/quiz/types.ts': '', 'app/types/globals.d.ts': '' },
+            expect: 'silence',
+        },
+    ],
     check: ({ allFiles, settings }) => {
         const files = allFiles ?? [];
         const root = settings?.typesRoot ?? 'app/types';
@@ -194,12 +268,17 @@ const typesOrganization = {
     },
 };
 const typographySource = {
-    id: 'core/C6',
+    name: 'typography-source',
     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 та стилі)',
     fix: 'go through the app\'s typography source (see settings.typographySource — a mixin in some apps, a Text/Heading component in others); if the style is genuinely new, add it there first',
     scope: ['app/assets/scss/**/*.scss', 'app/components/**/*.vue'],
+    fixtures: {
+        file: 'app/assets/scss/components/Card.scss',
+        bad: '.card { font-size: 14px; }',
+        good: '.card { @include font(14px, 20px); color: $slate-800; }',
+    },
     check: ({ file, code, settings }) => {
         const source = setting({ settings }, 'typographySource', 'the app\'s shared typography mixins or text components');
         // The files that DEFINE the typography are the one place raw declarations belong:
@@ -207,7 +286,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 — core/R4 polices those blocks.
+        // @font-face declares a face, not a usage — font-face-single-family 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);
@@ -218,12 +297,20 @@ const typographySource = {
     },
 };
 const scriptAttrOrder = {
-    id: 'core/C7',
+    name: 'script-attr-order',
     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',
     fix: 'use the app\'s canonical order everywhere — settings.scriptAttrOrder: \'setup-first\' (default) or \'lang-first\'',
     scope: ['app/**/*.vue'],
+    fixtures: {
+        // 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.
+        file: 'app/components/A.vue',
+        bad: '<script lang="ts" setup>\n</script>\n<script setup lang="ts">\n</script>',
+        good: '<template><div /></template>\n<script setup>\nconst a = 1\n</script>',
+    },
     check: ({ file, source, settings }) => {
         const canonical = settings?.scriptAttrOrder === 'lang-first' ? 'lang-first' : 'setup-first';
         const spell = (order) => (order === 'lang-first' ? '<script lang="ts" setup>' : '<script setup lang="ts">');

package/dist/rules/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The package rule pack — eleven rules by plain name, each carrying its own proof.
+ *
+ * Every rule reads identically in every Brighterly Nuxt app: none names a funnel, a store or
+ * a route. App-specific landmarks arrive through `RuleContext.settings`. Two files by origin:
+ *   regression.ts — it broke production at least once   → a code decision
+ *   convention.ts — a preference we chose               → team consensus
+ *
+ * App rules live in the app's own config and must not reuse a package name: `run()` fails
+ * fast on a duplicate rather than letting a suppression silently cover the wrong rule.
+ */
+import type { Rule } from '../engine/types.js';
+export { eachLine, setting } from './shared.js';
+export type { LineFn } from './shared.js';
+/**
+ * Every package rule name, in report order. Hover a member for what the rule checks, at
+ * which level, and what to do instead. A test pins this list to `packageRules`.
+ */
+export declare const packageRuleNames: readonly ["no-bare-storage", "inline-scss", "guarded-json-parse", "font-face-single-family", "vueuse-first", "ui-kit-unique-names", "scss-tokens", "date-format-enum", "types-layout", "typography-source", "script-attr-order"];
+/** Union of every name the package ships — for typing app config keys. */
+export type PackageRuleName = typeof packageRuleNames[number];
+/** Every package rule, in report order (the order of `packageRuleNames`). */
+export declare const packageRules: Rule[];
+/**
+ * Every 0.5.x id → its 1.0 name. Never delete an entry: a suppression or config key still
+ * naming an old id is reported with the new name instead of "does not name any rule".
+ */
+export declare const renamedRules: Record<string, PackageRuleName>;

package/dist/{invariants/rules → rules}/index.js

@@ -1,53 +1,61 @@
 /**
- * One rule list, assembled from the family files — the same shape each consuming app uses
- * for its own rules.
+ * The package rule pack — eleven rules by plain name, each carrying its own proof.
  *
- * The family letter says where a rule came from and who owns changing it:
- *   R — regression: it broke production at least once   → a code decision
- *   B — business: a data contract                       → NOT shipped here; every app's
- *                                                         contract is its own domain
- *   C — convention: a preference we chose               → team consensus
- *   L — linter: a built-in ESLint rule                  → eslint.config.mjs
+ * Every rule reads identically in every Brighterly Nuxt app: none names a funnel, a store or
+ * a route. App-specific landmarks arrive through `RuleContext.settings`. Two files by origin:
+ *   regression.ts — it broke production at least once   → a code decision
+ *   convention.ts — a preference we chose               → team consensus
  *
- * 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.
+ * App rules live in the app's own config and must not reuse a package name: `run()` fails
+ * fast on a duplicate rather than letting a suppression silently cover the wrong rule.
  */
 import { rRules } from './regression.js';
 import { cRules } from './convention.js';
-export { linterOwnedRules } from './linter.js';
-export { commonFixtures, commonSelfTestSkip } from './fixtures.js';
 export { eachLine, setting } from './shared.js';
-/** Every shared rule, in report order. Hover `sharedRuleIds` members for what each checks. */
-export const commonRules = [...rRules, ...cRules];
 /**
- * The hoverable catalog: every rule this pack ships, id → id. Use these constants for
- * `allowlists` / `levels` keys and `--rule=` values when you want the contract in the
- * IDE — hover any member for what the rule checks, at which level, and what to do
- * instead. A test pins this map to `commonRules`, so it cannot drift.
+ * Every package rule name, in report order. Hover a member for what the rule checks, at
+ * which level, and what to do instead. A test pins this list to `packageRules`.
  */
-export const sharedRuleIds = {
+export const packageRuleNames = [
     /** `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',
+    'no-bare-storage',
     /** `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',
+    'inline-scss',
     /** `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',
+    'guarded-json-parse',
     /** `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',
+    'font-face-single-family',
     /** `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`. */
-    'core/C1': 'core/C1',
+    'vueuse-first',
     /** `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. */
-    'core/C2': 'core/C2',
+    'ui-kit-unique-names',
     /** `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`. */
-    'core/C3': 'core/C3',
+    'scss-tokens',
     /** `warn` — a hand-rolled date format string (`'YYYY-MM-DD'`) or a `toISOString()` whose date part is extracted (`.split('T')[0]`, `.slice(0, 10)`). The date's shape becomes an accident instead of a contract. Fix: the shared enum (`settings.dateFormatModule`). */
-    'core/C4': 'core/C4',
+    'date-format-enum',
     /** `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. */
-    'core/C5': 'core/C5',
+    'types-layout',
     /** `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`). */
-    'core/C6': 'core/C6',
+    'typography-source',
     /** `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. */
-    'core/C7': 'core/C7',
+    'script-attr-order',
+];
+/** Every package rule, in report order (the order of `packageRuleNames`). */
+export const packageRules = [...rRules, ...cRules];
+/**
+ * Every 0.5.x id → its 1.0 name. Never delete an entry: a suppression or config key still
+ * naming an old id is reported with the new name instead of "does not name any rule".
+ */
+export const renamedRules = {
+    'core/R1': 'no-bare-storage',
+    'core/R2': 'inline-scss',
+    'core/R3': 'guarded-json-parse',
+    'core/R4': 'font-face-single-family',
+    'core/C1': 'vueuse-first',
+    'core/C2': 'ui-kit-unique-names',
+    'core/C3': 'scss-tokens',
+    'core/C4': 'date-format-enum',
+    'core/C5': 'types-layout',
+    'core/C6': 'typography-source',
+    'core/C7': 'script-attr-order',
 };

package/dist/{invariants/rules → rules}/regression.d.ts

@@ -9,5 +9,5 @@
  * Changing one is a code decision — but a code decision for FOUR repos now, so making a
  * rule stricter is a major version bump.
  */
-import type { Rule } from '../types.js';
+import type { Rule } from '../engine/types.js';
 export declare const rRules: Rule[];

package/dist/{invariants/rules → rules}/regression.js

@@ -9,10 +9,10 @@
  * Changing one is a code decision — but a code decision for FOUR repos now, so making a
  * rule stricter is a major version bump.
  */
-import { findJsonParseCalls } from '../ast.js';
+import { findJsonParseCalls } from '../engine/ast.js';
 import { eachLine, setting } from './shared.js';
 const bareStorage = {
-    id: 'core/R1',
+    name: 'no-bare-storage',
     title: 'bare localStorage / sessionStorage access',
     // 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
@@ -23,6 +23,11 @@ const bareStorage = {
     fix: 'use the app\'s safe storage wrapper instead of the bare API',
     scope: ['app/**/*.{ts,vue}'],
     exclude: ['app/tests/**', 'app/test/**'],
+    fixtures: {
+        file: 'app/a.ts',
+        bad: 'const t = localStorage.getItem("k")',
+        good: 'const t = safeLocalStorage.getItem("k")',
+    },
     check: ({ file, code, settings }) => {
         // The wrapper itself is the one place bare access belongs — settings-driven, so no
         // consumer has to allowlist its own wrapper.
@@ -41,7 +46,7 @@ const bareStorage = {
     },
 };
 const scssInStyleBlock = {
-    id: 'core/R2',
+    name: 'inline-scss',
     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',
@@ -50,6 +55,11 @@ const scssInStyleBlock = {
     // Dev harness pages are dev tooling, not product surfaces — every app that has them
     // (tutor room-preview, cs-app preview) was allowlisting the same thing (2026-09-25).
     exclude: ['app/pages/dev/**'],
+    fixtures: {
+        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" />',
+    },
     check: ({ file, source }) => {
         const out = [];
         const re = /<style\b[^>]*>([\s\S]*?)<\/style>/g;
@@ -73,15 +83,20 @@ const scssInStyleBlock = {
     },
 };
 const unguardedJsonParse = {
-    id: 'core/R3',
+    name: 'guarded-json-parse',
     title: 'unguarded JSON.parse',
-    // Target level is `error` — see core/R1 above; same interim decision (2026-09-25).
+    // Target level is `error` — see no-bare-storage 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',
     scope: ['app/**/*.{ts,vue}'],
     exclude: ['app/tests/**', 'app/test/**'],
+    fixtures: {
+        file: 'app/a.ts',
+        bad: 'const v = JSON.parse(raw)',
+        good: 'let v = null\ntry { v = JSON.parse(raw) } catch { v = null }',
+    },
     check: async ({ file, source, settings }) => {
         const helper = setting({ settings }, 'safeJsonParse', 'a guarded parse helper');
         const calls = await findJsonParseCalls(file, source);
@@ -91,12 +106,17 @@ const unguardedJsonParse = {
     },
 };
 const fontFaceStack = {
-    id: 'core/R4',
+    name: 'font-face-single-family',
     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',
     fix: 'keep font-family inside @font-face to the single family name; the fallback stack belongs on the selectors that use the font',
     scope: ['app/assets/scss/**/*.scss'],
+    fixtures: {
+        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); }',
+    },
     check: ({ file, code }) => {
         const out = [];
         for (const m of code.matchAll(/@font-face\s*\{([^}]*)\}/g)) {

package/dist/{invariants/rules → rules}/shared.d.ts

@@ -5,7 +5,7 @@
  * through `RuleContext.settings`, which each app fills from `config.settings` — that is why
  * `settings` exists at all, and why the pack needs no factory.
  */
-import type { Finding, RuleContext } from '../types.js';
+import type { Finding, RuleContext } from '../engine/types.js';
 export type LineFn = (line: string, n: number, lines: string[]) => Finding | Finding[] | null;
 export declare const eachLine: (source: string, fn: LineFn) => Finding[];
 /**

package/dist/validate/index.d.ts

@@ -28,7 +28,7 @@ export interface ValidateOptions {
     };
     /** Defaults to process.stdout.write. */
     write?: (s: string) => void;
-    /** Defaults to process.exit. Injectable so tests can assert the code. */
+    /** Defaults to setting `process.exitCode` (never `process.exit()` after output). Injectable so tests can assert the code. */
     exit?: (code: number) => never;
     /** Emit ::group:: markers. Defaults to Boolean(process.env.GITHUB_ACTIONS). */
     ci?: boolean;

package/dist/validate/index.js

@@ -16,7 +16,7 @@ const NAME_WIDTH = 12;
 export const validate = async (steps, options = {}) => {
     const exec = options.exec ?? defaultExec;
     const write = options.write ?? ((s) => { process.stdout.write(s); });
-    const exit = options.exit ?? process.exit;
+    const exit = options.exit ?? ((code) => { process.exitCode = code; });
     const ci = options.ci ?? Boolean(process.env.GITHUB_ACTIONS);
     const results = [];
     for (const step of steps) {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@brighterly/lib-fe-codestyle",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Shared invariant-validator engine, rule pack and ESLint config for Brighterly Nuxt frontend apps",
   "repository": {
     "type": "git",
-    "url": "https://github.com/brighterly/lib-fe-codestyle.git"
+    "url": "git+https://github.com/brighterly/lib-fe-codestyle.git"
   },
   "publishConfig": {
     "access": "public"
@@ -20,20 +20,15 @@
     "README.md"
   ],
   "exports": {
-    "./invariants": {
-      "types": "./dist/invariants/index.d.ts",
-      "default": "./dist/invariants/index.js"
-    },
-    "./invariants/rules": {
-      "types": "./dist/invariants/rules/index.d.ts",
-      "default": "./dist/invariants/rules/index.js"
-    },
-    "./validate": {
-      "types": "./dist/validate/index.d.ts",
-      "default": "./dist/validate/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./eslint": "./eslint/index.mjs"
   },
+  "bin": {
+    "codestyle": "dist/cli.js"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "rm -rf dist",

package/dist/invariants/index.d.ts

@@ -1,7 +0,0 @@
-export { run } from './run.js';
-export type { RunOptions } from './run.js';
-export { runSelfTest } from './self-test.js';
-export type { Fixture, SelfTestInput, SelfTestResult } from './self-test.js';
-export * from './types.js';
-export * from './util.js';
-export * from './ast.js';

package/dist/invariants/index.js

@@ -1,5 +0,0 @@
-export { run } from './run.js';
-export { runSelfTest } from './self-test.js';
-export * from './types.js';
-export * from './util.js';
-export * from './ast.js';

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

@@ -1,18 +0,0 @@
-/**
- * Convention rules — preferences we chose, with no production incident behind them.
- * Advisory by default (`warn`): nudged, not policed, and droppable by team consensus.
- *
- * `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.
- *
- * `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.
- *
- * 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 '../types.js';
-export declare const cRules: Rule[];

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

@@ -1,17 +0,0 @@
-/**
- * Fixtures for the common rule pack — shipped, not test-only.
- *
- * Fixtures travel with their rules. A consuming app runs `--self-test` over the rules it
- * actually loads, so if the pack shipped rules without fixtures every consumer would report
- * "no self-test fixture" for rules it did not write and cannot fix.
- *
- * `bad` must produce at least one finding, `good` none.
- */
-import type { Fixture } from '../self-test.js';
-export declare const commonFixtures: Record<string, 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 declare const commonSelfTestSkip: string[];