@brighterly/lib-fe-codestyle 0.1.2 → 0.2.0

package/README.md

@@ -65,6 +65,13 @@ exported as data.
 | `_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.
+Underscore-prefixed SCSS partials (`_extends.scss`, `_colors-*.scss`, …) are declaration
+files by convention in every Brighterly app and are exempt from `_C3`/`_C6` wholesale.
+
 `_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
@@ -93,6 +100,7 @@ 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
   safeJsonParse:     'parseStoredJson() from @helpers/safe-local-storage',
   scssTokensFile:    'app/assets/scss/_colors.scss',
   uiKitRoot:         'app/components/UI',

package/dist/invariants/rules/convention.js

@@ -88,13 +88,13 @@ const scssColourTokens = {
     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))
+        // Underscore-prefixed partials are DECLARATION files by SCSS convention in every
+        // Brighterly app (_colors, _vars, _extends, _mixins, brand variants, …) — they are
+        // where the literals belong, so the whole class is exempt (decided 2026-09-24).
+        if (/\/_[^/]*\.scss$/.test(file))
             return [];
-        // `[\w-]*` covers brand variants like _colors-smartestminds.scss (cs-app is multi-brand).
-        if (/\/_(?:colors|vars|palette|tokens)[\w-]*\.scss$/.test(file))
+        const palette = setting({ settings }, 'scssTokensFile', 'app/assets/scss/_colors.scss');
+        if (file === palette)
             return [];
         return eachLine(code, (line, n) => {
             // `rgba($token, .5)` is correct usage — only a NUMERIC first argument is a literal.
@@ -174,9 +174,10 @@ const typographySource = {
     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.
-        // `[\w-]*` covers brand variants like _vars-smartestminds.scss (cs-app is multi-brand).
-        if (/\/_?(?:mixins|vars|fonts|typography|colors)[\w-]*\.scss$/.test(file))
+        // The files that DEFINE the typography are the one place raw declarations belong:
+        // every underscore-prefixed partial (declaration files by SCSS convention in the
+        // 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.
         const stripped = code.replace(/@font-face\s*\{[^}]*\}/g, m => m.replace(/[^\n]/g, ' '));

package/dist/invariants/rules/regression.js

@@ -20,6 +20,10 @@ const bareStorage = {
     scope: ['app/**/*.{ts,vue}'],
     exclude: ['app/tests/**', 'app/test/**'],
     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.
+        if (settings?.safeStorageFile && file === settings.safeStorageFile)
+            return [];
         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)) {

package/dist/invariants/types.d.ts

@@ -58,6 +58,8 @@ export interface ReportedFinding extends Finding {
 export interface SharedRuleSettings {
     /** `_R1`/`_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'. */
+    safeStorageFile?: string;
     /** `_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'. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brighterly/lib-fe-codestyle",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Shared invariant-validator engine, rule pack and ESLint config for Brighterly Nuxt frontend apps",
@@ -61,4 +61,4 @@
     "typescript-eslint": "^8.70.1",
     "vitest": "^4.1.10"
   }
-}
+}