@brighterly/lib-fe-codestyle 0.1.0

package/dist/invariants/rules/convention.js

@@ -0,0 +1,226 @@
+/**
+ * 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
+ * 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
+ * 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 { eachLine, setting } from './shared.js';
+const vueUseFirst = {
+    id: '_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',
+    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 }) => {
+        const map = [
+            [/new\s+IntersectionObserver\s*\(/, 'useIntersectionObserver'],
+            [/new\s+ResizeObserver\s*\(/, 'useResizeObserver'],
+            [/\bdocument\s*\.\s*title\s*=/, 'useTitle'],
+            [/\bwindow\s*\.\s*matchMedia\s*\(/, 'useMediaQuery'],
+            [/\b(?:window|document)\s*\.\s*addEventListener\s*\(/, 'useEventListener'],
+            [/\bnavigator\s*\.\s*clipboard\b/, 'useClipboard'],
+            // Nuxt does not auto-import VueUse's `useStorage` — Nitro owns that name.
+            [/\buseStorage\s*\(/, 'useLocalStorage / useSessionStorage (explicitly imported from @vueuse/core)'],
+            [/\bwindow\s*\.\s*inner(?:Width|Height)\b/, 'useWindowSize'],
+            [/\b(?:window\s*\.\s*)?setInterval\s*\(/, 'useIntervalFn'],
+            [/\b(?:window\s*\.\s*)?setTimeout\s*\(/, 'useTimeoutFn'],
+        ];
+        return eachLine(code, (line, n) => {
+            for (const [re, fn] of map) {
+                if (re.test(line))
+                    return { file, line: n, message: `hand-rolled browser API — use ${fn} from @vueuse/core` };
+            }
+            return null;
+        });
+    },
+};
+const uiKitReuseFirst = {
+    id: '_C2',
+    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'],
+    check: ({ allFiles, settings }) => {
+        const files = allFiles ?? [];
+        const uiKitRoot = settings?.uiKitRoot ?? 'app/components/UI';
+        const basename = (f) => f.slice(f.lastIndexOf('/') + 1).replace(/\.vue$/, '');
+        const kit = new Map();
+        for (const f of files) {
+            if (!f.startsWith(`${uiKitRoot}/`) || !f.endsWith('.vue'))
+                continue;
+            kit.set(basename(f).toLowerCase(), f);
+        }
+        if (kit.size === 0)
+            return [];
+        const out = [];
+        for (const f of files) {
+            if (!f.endsWith('.vue') || f.startsWith(`${uiKitRoot}/`))
+                continue;
+            if (!f.startsWith('app/components/'))
+                continue;
+            const hit = kit.get(basename(f).toLowerCase());
+            if (!hit)
+                continue;
+            out.push({ file: f, line: 1, message: `duplicates the UI-kit component of the same name (${hit}) — import or extend it instead of re-creating it` });
+        }
+        return out;
+    },
+};
+const scssColourTokens = {
+    id: '_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',
+    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'],
+    check: ({ file, code, settings }) => {
+        // The palette files DEFINE the literals — they are the one place they belong.
+        const palette = setting({ settings }, 'scssTokensFile', 'app/assets/scss/_colors.scss');
+        const paletteFiles = [palette, 'app/assets/scss/_vars.scss', 'app/assets/scss/_colors.scss'];
+        if (paletteFiles.some(p => file === p))
+            return [];
+        if (/\/_(?:colors|vars|palette|tokens)\.scss$/.test(file))
+            return [];
+        return eachLine(code, (line, n) => {
+            // `rgba($token, .5)` is correct usage — only a NUMERIC first argument is a literal.
+            const hex = /#[0-9a-fA-F]{3,8}\b/.exec(line);
+            const numericRgb = /\brgba?\(\s*\d[^)]*\)/.exec(line);
+            if (!hex && !numericRgb)
+                return null;
+            const what = hex ? hex[0] : (numericRgb?.[0] ?? '').replace(/\s+/g, ' ');
+            return { file, line: n, message: `literal colour ${what} — use a token from ${palette}` };
+        });
+    },
+};
+const dateFormatEnum = {
+    id: '_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',
+    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/**'],
+    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.
+        if (/date[-/]?format|\/date\.ts$|enums\.ts$/i.test(file))
+            return [];
+        // A date pattern: only Y/M/D/H/m/s and separators, and carrying a real token.
+        const FORMAT = /(['"`])((?=[^'"`]*(?:YYYY|DD|MM|HH|mm|ss))[YMDHhmsAaZ\s:/.,-]{5,})\1/;
+        return eachLine(code, (line, n) => {
+            if (/\.toISOString\s*\(/.test(line)) {
+                return { file, line: n, message: `toISOString() is always UTC and always carries a time — it shifts the calendar day; format through ${dateModule}` };
+            }
+            const m = FORMAT.exec(line);
+            if (!m)
+                return null;
+            return { file, line: n, message: `hand-rolled date format ${m[1]}${m[2]}${m[1]} — use a member of ${dateModule}` };
+        });
+    },
+};
+const typesOrganization = {
+    id: '_C5',
+    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'],
+    check: ({ allFiles, settings }) => {
+        const files = allFiles ?? [];
+        const root = settings?.typesRoot ?? 'app/types';
+        const kindFiles = new Set(['enums.ts', 'interfaces.ts', 'types.ts']);
+        const out = [];
+        for (const f of files) {
+            if (!f.startsWith(`${root}/`) || !f.endsWith('.ts'))
+                continue;
+            // Ambient declaration files augment globals; they are not entity types.
+            if (f.endsWith('.d.ts'))
+                continue;
+            const parts = f.slice(root.length + 1).split('/');
+            if (parts.length === 1) {
+                out.push({ file: f, line: 1, message: `type file directly under ${root} — every type belongs to ${root}/<entity>/{enums,interfaces,types}.ts` });
+                continue;
+            }
+            const base = parts[parts.length - 1] ?? '';
+            if (!kindFiles.has(base)) {
+                out.push({ file: f, line: 1, message: `${base} is not a kind file — split an entity's types into enums.ts / interfaces.ts / types.ts (a sub-entity gets its own folder)` });
+            }
+        }
+        return out;
+    },
+};
+const typographySource = {
+    id: '_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 та стилі)',
+    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'],
+    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.
+        if (/\/_?(?:mixins|vars|fonts|typography|colors)\.scss$/.test(file))
+            return [];
+        // @font-face declares a face, not a usage — _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);
+            if (!m)
+                return null;
+            return { file, line: n, message: `raw ${m[0].replace(/\s*:$/, '')} declaration — use ${source}` };
+        });
+    },
+};
+const scriptAttrOrder = {
+    id: '_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',
+    fix: 'use the app\'s canonical order everywhere — settings.scriptAttrOrder: \'setup-first\' (default) or \'lang-first\'',
+    scope: ['app/**/*.vue'],
+    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">');
+        const out = [];
+        for (const m of source.matchAll(/<script\b[^>]*>/g)) {
+            const tag = m[0];
+            const setupIdx = tag.search(/\bsetup\b/);
+            const langIdx = tag.search(/\blang\s*=/);
+            if (setupIdx === -1 || langIdx === -1)
+                continue;
+            const actual = setupIdx < langIdx ? 'setup-first' : 'lang-first';
+            if (actual === canonical)
+                continue;
+            out.push({
+                file,
+                line: source.slice(0, m.index).split('\n').length,
+                message: `${spell(actual)} — this app's canonical order is ${spell(canonical)}`,
+            });
+        }
+        return out;
+    },
+};
+export const cRules = [
+    vueUseFirst,
+    uiKitReuseFirst,
+    scssColourTokens,
+    dateFormatEnum,
+    typesOrganization,
+    typographySource,
+    scriptAttrOrder,
+];

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

@@ -0,0 +1,17 @@
+/**
+ * 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>;
+/**
+ * `_C2` and `_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[];

package/dist/invariants/rules/fixtures.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+export const commonFixtures = {
+    '_R1': {
+        file: 'app/a.ts',
+        bad: 'const t = localStorage.getItem("k")',
+        good: 'const t = safeLocalStorage.getItem("k")',
+    },
+    '_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': {
+        file: 'app/a.ts',
+        bad: 'const v = JSON.parse(raw)',
+        good: 'let v = null\ntry { v = JSON.parse(raw) } catch { v = null }',
+    },
+    '_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': {
+        file: 'app/a.ts',
+        bad: 'window.addEventListener("resize", onResize)',
+        good: 'useEventListener(window, "resize", onResize)',
+    },
+    '_C3': {
+        file: 'app/assets/scss/components/Card.scss',
+        bad: '.card { color: #1f2937; }',
+        good: '.card { color: $slate-800; }',
+    },
+    '_C4': {
+        file: 'app/a.ts',
+        bad: "const d = dayjs().format('YYYY-MM-DD')",
+        good: 'const d = dayjs().format(DateFormat.DefaultDate)',
+    },
+    '_C6': {
+        file: 'app/assets/scss/components/Card.scss',
+        bad: '.card { font-size: 14px; }',
+        good: '.card { @include font(14px, 20px); color: $slate-800; }',
+    },
+    '_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.
+        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>',
+    },
+};
+/**
+ * `_C2` and `_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'];

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

@@ -0,0 +1,55 @@
+/**
+ * One rule list, assembled from the family files — the same shape each consuming app uses
+ * for its own rules.
+ *
+ * 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
+ *
+ * Shared rule ids carry the underscore prefix (`_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.
+ */
+import type { Rule } from '../types.js';
+export { linterOwnedRules } from './linter.js';
+export { commonFixtures, commonSelfTestSkip } from './fixtures.js';
+export { eachLine, setting } from './shared.js';
+export type { LineFn } from './shared.js';
+/** Every shared rule, in report order. Hover `sharedRuleIds` members for what each checks. */
+export declare const commonRules: Rule[];
+/**
+ * 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.
+ */
+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";
+    /** `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";
+    /** `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";
+    /** `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";
+    /** `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";
+    /** `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";
+    /** `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";
+    /** `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";
+    /** `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";
+    /** `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";
+};
+/** 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

@@ -0,0 +1,53 @@
+/**
+ * One rule list, assembled from the family files — the same shape each consuming app uses
+ * for its own rules.
+ *
+ * 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
+ *
+ * Shared rule ids carry the underscore prefix (`_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.
+ */
+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.
+ */
+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',
+    /** `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',
+    /** `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',
+    /** `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',
+    /** `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',
+    /** `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',
+    /** `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',
+    /** `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',
+    /** `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',
+    /** `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',
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Linter rules — invariants a built-in ESLint rule already covers better than we could.
+ *
+ * Declared here, configured in each app\'s `eslint.config.mjs`, so the generated inventory
+ * is complete and nobody re-implements one by accident. Empty today: a declaration here
+ * asserts the rule IS configured, and claiming coverage the linter does not provide is the
+ * exact failure this directory exists to prevent.
+ */
+import type { LinterOwnedRule } from '../types.js';
+export declare const linterOwnedRules: LinterOwnedRule[];

package/dist/invariants/rules/linter.js

@@ -0,0 +1,9 @@
+/**
+ * Linter rules — invariants a built-in ESLint rule already covers better than we could.
+ *
+ * Declared here, configured in each app\'s `eslint.config.mjs`, so the generated inventory
+ * is complete and nobody re-implements one by accident. Empty today: a declaration here
+ * asserts the rule IS configured, and claiming coverage the linter does not provide is the
+ * exact failure this directory exists to prevent.
+ */
+export const linterOwnedRules = [];

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

@@ -0,0 +1,13 @@
+/**
+ * Regression rules — each one broke production at least once, and SILENTLY. No test failed,
+ * no type error, no lint warning.
+ *
+ * Ported from land-app, where they were scars first. They are here rather than there
+ * because each reads identically in every Brighterly Nuxt app: none names a funnel, a store
+ * or a route. App-specific landmarks arrive through `RuleContext.settings`.
+ *
+ * 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';
+export declare const rRules: Rule[];

package/dist/invariants/rules/regression.js

@@ -0,0 +1,109 @@
+/**
+ * Regression rules — each one broke production at least once, and SILENTLY. No test failed,
+ * no type error, no lint warning.
+ *
+ * Ported from land-app, where they were scars first. They are here rather than there
+ * because each reads identically in every Brighterly Nuxt app: none names a funnel, a store
+ * or a route. App-specific landmarks arrive through `RuleContext.settings`.
+ *
+ * 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 { eachLine, setting } from './shared.js';
+const bareStorage = {
+    id: '_R1',
+    title: 'bare localStorage / sessionStorage access',
+    level: 'error',
+    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}'],
+    exclude: ['app/tests/**', 'app/test/**'],
+    check: ({ file, code, settings }) => {
+        const wrapper = setting({ settings }, 'safeStorageModule', 'the safe storage helper');
+        return eachLine(code, (line, n) => {
+            if (/\b(?:window\s*\.\s*)?(?:local|session)Storage\s*[.[]/.test(line)) {
+                return { file, line: n, message: `bare ${line.match(/(local|session)Storage/)?.[0] ?? 'storage'} access — use ${wrapper}` };
+            }
+            if (/if\s*\(\s*(?:window\s*\.\s*)?(?:local|session)Storage\s*\)/.test(line)) {
+                return { file, line: n, message: 'storage existence guard — the accessor itself throws, the guard does not help' };
+            }
+            return null;
+        });
+    },
+};
+const scssInStyleBlock = {
+    id: '_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',
+    fix: 'move the rules to a dedicated .scss file and reference it with <style scoped lang="scss" src="…" />',
+    scope: ['app/**/*.vue'],
+    check: ({ file, source }) => {
+        const out = [];
+        const re = /<style\b[^>]*>([\s\S]*?)<\/style>/g;
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const body = (m[1] ?? '').trim();
+            if (body.length === 0)
+                continue;
+            // `@forward`/`@use`/`@import`-only blocks declare no rules of their own — the
+            // canonical way to pull a third-party library's styles in unscoped.
+            const withoutAtRules = body.replace(/@(?:use|forward|import)[^;]*;/g, '').trim();
+            if (withoutAtRules.length === 0)
+                continue;
+            out.push({
+                file,
+                line: source.slice(0, m.index).split('\n').length,
+                message: 'SCSS rules declared inline — move them to a .scss file and use <style src="…" />',
+            });
+        }
+        return out;
+    },
+};
+const unguardedJsonParse = {
+    id: '_R3',
+    title: 'unguarded JSON.parse',
+    level: 'error',
+    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/**'],
+    check: async ({ file, source, settings }) => {
+        const helper = setting({ settings }, 'safeJsonParse', 'a guarded parse helper');
+        const calls = await findJsonParseCalls(file, source);
+        return calls
+            .filter(c => !c.guarded)
+            .map(c => ({ file, line: c.line, message: `JSON.parse with no enclosing try/catch — use ${helper}` }));
+    },
+};
+const fontFaceStack = {
+    id: '_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',
+    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'],
+    check: ({ file, code }) => {
+        const out = [];
+        for (const m of code.matchAll(/@font-face\s*\{([^}]*)\}/g)) {
+            const family = m[1]?.match(/font-family\s*:\s*([^;]+);/)?.[1] ?? '';
+            const outsideQuotes = family.replace(/(['"])(?:(?!\1).)*\1/g, '');
+            if (outsideQuotes.includes(',')) {
+                out.push({
+                    file,
+                    line: code.slice(0, m.index).split('\n').length,
+                    message: `@font-face declares font-family: ${family.trim()} — a stack, so the face is dropped`,
+                });
+            }
+        }
+        return out;
+    },
+};
+export const rRules = [
+    bareStorage,
+    scssInStyleBlock,
+    unguardedJsonParse,
+    fontFaceStack,
+];

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

@@ -0,0 +1,18 @@
+/**
+ * Building blocks for the common rule pack.
+ *
+ * A shared rule must not hardcode a consuming app's paths. Anything app-specific arrives
+ * 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';
+export type LineFn = (line: string, n: number, lines: string[]) => Finding | Finding[] | null;
+export declare const eachLine: (source: string, fn: LineFn) => Finding[];
+/**
+ * A setting, or a readable fallback when the app has not declared it.
+ *
+ * Never throws: a missing setting must degrade the MESSAGE, never silence the rule. A rule
+ * that stops firing because a path is unset is exactly the silent failure this repo exists
+ * to prevent.
+ */
+export declare const setting: (ctx: Pick<RuleContext, "settings">, key: string, fallback: string) => string;

package/dist/invariants/rules/shared.js

@@ -0,0 +1,25 @@
+/**
+ * Building blocks for the common rule pack.
+ *
+ * A shared rule must not hardcode a consuming app's paths. Anything app-specific arrives
+ * through `RuleContext.settings`, which each app fills from `config.settings` — that is why
+ * `settings` exists at all, and why the pack needs no factory.
+ */
+export const eachLine = (source, fn) => {
+    const lines = source.split('\n');
+    const out = [];
+    lines.forEach((line, i) => {
+        const r = fn(line, i + 1, lines);
+        if (r)
+            out.push(...(Array.isArray(r) ? r : [r]));
+    });
+    return out;
+};
+/**
+ * A setting, or a readable fallback when the app has not declared it.
+ *
+ * Never throws: a missing setting must degrade the MESSAGE, never silence the rule. A rule
+ * that stops firing because a path is unset is exactly the silent failure this repo exists
+ * to prevent.
+ */
+export const setting = (ctx, key, fallback) => ctx.settings?.[key] ?? fallback;