@brighterly/lib-fe-codestyle 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# `@brighterly/lib-fe-codestyle`
+
+Shared, deterministic code-review machinery for the Brighterly Nuxt apps — land-app,
+cs-app, app-tutor, app-admin.
+
+It holds the **mechanisms**. Domain rules stay in each app.
+
+## Subpaths
+
+| Import | What it is |
+|---|---|
+| `@brighterly/lib-fe-codestyle/invariants` | the invariants engine — `run(options)`, the rule contract, AST helpers, util |
+| `@brighterly/lib-fe-codestyle/invariants/rules` | the common rule pack, portable across all apps |
+| `@brighterly/lib-fe-codestyle/eslint` | the shared flat config, its seven local rules, and the maps behind them |
+| `@brighterly/lib-fe-codestyle/validate` | the aggregating runner behind `pnpm validate` |
+
+`exports` **is** the public surface. Anything not listed is private — a linked package
+resolves deep paths that break the moment it is published.
+
+## The one design rule: export data, never factories
+
+Consumers compose. There is no `defineBrighterlyEslint({...})`, and there never will be —
+the four apps' configs are ~95% identical and the variance is mostly drift, so a factory
+would parameterise accidental difference.
+
+```js
+// an app that needs nothing extra
+import brighterly from '@brighterly/lib-fe-codestyle/eslint'
+export default [...brighterly]
+```
+
+```js
+// an app extending a map — plain object spread, no API to learn
+import brighterly, { checkFileFolders } from '@brighterly/lib-fe-codestyle/eslint'
+
+export default [
+  ...brighterly,
+  { rules: { 'check-file/folder-naming-convention': ['error', {
+      ...checkFileFolders,
+      'app/components/pages/**/': 'KEBAB_CASE',
+  }] } },
+]
+```
+
+ESLint **replaces** rule options rather than merging them, so appending an override without
+spreading the shared map silently discards every shared entry. That is why the maps are
+exported as data.
+
+
+## What the rule pack ships
+
+### Invariants — `@brighterly/lib-fe-codestyle/invariants/rules`
+
+| 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`) |
+
+`_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
+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.
+
+Fixtures ship with the rules (`commonFixtures`), so `--self-test` works in any consumer
+without it having to write fixtures for rules it did not author.
+
+### ESLint — `@brighterly/lib-fe-codestyle/eslint`
+
+Seven local rules: `padding-after-macros`, `async-components-after-macros`,
+`no-import-group-labels`, `ref-prefix-prop-mirrors`, `require-component-name`,
+`on-prefixed-callbacks`, and `optional-callback-chaining` (new — an optional callback
+invoked without `?.` throws for the first caller that omits it).
+
+Plus the shared flat config: restricted syntax, restricted imports, the types-organization
+blocks, and the `check-file` naming maps — all exported as data so a consumer can spread
+and extend them.
+
+## App-specific paths: `settings`, not parameters
+
+A shared rule must not hardcode a consuming app's paths. Each app declares them once:
+
+```ts
+// invariants/config.mts
+export const settings = {
+  safeStorageModule: 'safeLocalStorage from @helpers/safe-local-storage',
+  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')
+}
+```
+
+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
+default above, so leaving them unset still never silences the rule.
+
+## What consumers see in the IDE
+
+Three hover surfaces, so "what rules do we have and what do they look for" never
+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
+  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
+  `scriptAttrOrder` value.
+- **ESLint squiggles** — every local rule ships `meta.docs.description`, which is what
+  the editor shows on hover over a violation.
+
+PhpStorm / WebStorm notes: the IDE runs the **project's own ESLint binary** against the
+flat `eslint.config.mjs`, so rules defined inside this package just work — nothing to
+install or configure beyond the default "Automatic ESLint configuration". Two real
+behaviours to know: the ESLint daemon caches the resolved config, so after upgrading
+this package run *ESLint: Restart Service* (or reopen the project) to pick up new
+rules; and the invariants engine is **not** an IDE inspection — its findings appear in
+the terminal (`pnpm validate:invariants`) and the pre-commit hook only.
+
+## Wiring a consumer
+
+1. `pnpm add -D @brighterly/lib-fe-codestyle` — plus, if not already direct devDeps,
+   `@vue/compiler-sfc` and `typescript`. Both are **peers, not dependencies**, on
+   purpose: the validator must parse your files with the *same* compiler instance your
+   build uses, so the package dedupes onto the app's copy instead of carrying its own.
+   Every Brighterly Nuxt app already has both in the store — the devDep line adds a
+   symlink, not a download.
+2. An `invariants/` directory with `cli.mts` (a ~20-line composition root — copy
+   land-app's), `config.mts` (allowlists, levels, retired, unmaintained, `settings` —
+   see above), your app-local rules, and `specs/` for checks needing real module
+   resolution.
+3. A missing peer is loud, never silent: pnpm warns at install (and auto-installs by
+   default), and the engine's lazy `import()` throws on the first AST rule otherwise.
+4. Arm the pre-commit hook from install, not by hand: keep the hook script in a tracked
+   directory and add `git config core.hooksPath <that-dir> || true` to `postinstall`
+   (the `|| true` keeps .git-less installs — Docker builds — green). Setup stays
+   `pnpm i && pnpm dev`; a hand-made `.git/hooks` symlink dies with every fresh clone.
+
+An app with a pre-extraction fork of the engine (app-funnels) deletes its copied
+`ast/util/run/self-test` plumbing and keeps only domain rules + config; its existing
+compiler-sfc devDep already satisfies the peer.
+
+## Why `src/` is compiled but `eslint/` is not
+
+Node refuses to strip types inside `node_modules`
+(`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so the TypeScript half ships as `dist/`.
+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
+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
+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."
+
+## Versioning is about blocking power
+
+One question decides the bump: **can this change turn a green consumer red, or break
+something a consumer wrote against a rule id?** Yes → major. Adds signal without
+blocking → minor. Everything else → patch.
+
+| Change | Bump | Why |
+|---|---|---|
+| New invariant rule at `error` | **major** | can turn a green repo red on install |
+| Promoting a rule `warn` → `error` | **major** | same — new blocking power |
+| Widening a rule's `scope`, narrowing its `exclude`, or making its match stricter | **major** | existing code that passed now fails |
+| Renaming, renumbering or removing a rule id | **major** | breaks every `invariant-ignore:` comment, `allowlists`/`levels` key and doc that names the token — `IG1` starts firing in every consumer |
+| New ESLint rule at `error`, or adding a selector to `restrictedSyntax` / `restrictedImports` / the `check-file` maps | **major** | the shared config is spread into every app's lint gate |
+| Engine behavior change (`run()` exit codes, finding shape, config contract) | **major** | consumers' composition roots are written against it |
+| New invariant rule at `warn` | minor | new signal, blocks nothing |
+| New ESLint rule at `warn` | minor | same |
+| New export (a map, a helper, a settings key a rule *optionally* reads) | minor | additive surface |
+| Demoting a rule `error` → `warn`, or narrowing its scope | patch | strictly relaxing |
+| Bug fix that removes false positives, message/`why`/`fix` wording, fixture improvements | patch | nothing new fires |
+
+Two edges worth naming: a bug fix that removes **false negatives** (the rule now
+catches what it always claimed to) is still **major** — correctness of intent does not
+change what happens in a consumer's CI. And a new `settings` key a rule *requires* is
+major; one it merely reads for a better message is minor (a missing key degrades the
+message, never the firing — see above).
+
+## Publishing
+
+The package is published **publicly** to npmjs.org under the `@brighterly` org — the
+same channel as `@brighterly/lib-lumee-ui`, so consumers need no registry config or
+token. `publishConfig.access: "public"` in `package.json` makes the scoped publish
+work without a paid org plan.
+
+```bash
+npm login                 # must be a member of the @brighterly org
+npm version <patch|minor|major>   # per the blocking-power table above
+npm publish               # prepublishOnly rebuilds dist and runs the tests first
+git push && git push --tags
+```
+
+`dist/` is gitignored; `prepublishOnly` (`clean → build → test`) guarantees the
+tarball is built from the current sources, never a stale artifact.
+
+## Design
+
+`land-app/docs/superpowers/specs/2026-09-22-fe-codestyle-design.md`

package/dist/invariants/ast.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Real ASTs for the rules that regex cannot express honestly.
+ *
+ * Two parsers, both direct devDependencies, both loaded lazily so a `--rule=R2`
+ * run pays for neither:
+ *   typescript          102 ms load · 153 ms for all 423 app .ts files
+ *   @vue/compiler-sfc    92 ms load · 156 ms for all 398 app .vue files (template AST)
+ *
+ * compiler-sfc was already in the pnpm store transitively (vue-router, vue-gtm,
+ * eslint-processor-vue-blocks); making it explicit added a symlink, not a
+ * download. It exists because four checks in R12/R16 could not be expressed
+ * honestly on lines: a file-wide `data-qa` grep passed when the attribute sat on
+ * an inner <div>, a nested child component's `<template #body>` tripped the
+ * ordering check, `class="bold indigo"` slipped past a `class="indigo"` regex,
+ * and a multi-line `:title` binding hid a <br> from a per-line scan.
+ */
+/**
+ * Every `JSON.parse(...)` call with a flag for whether a real TryStatement
+ * encloses it — an ancestor walk, not a guess about nearby lines.
+ */
+export declare const findJsonParseCalls: (file: string, source: string) => Promise<{
+    line: number;
+    guarded: boolean;
+}[]>;
+/**
+ * Every static import that survives compilation: default, named, namespace and bare side-effect
+ * imports plus `export … from` re-exports, in .ts files and in every script block of a .vue file.
+ * Only `import type` / `export type` declarations are dropped — with `verbatimModuleSyntax` (the Nuxt
+ * default) an inline `import { type X } from 'pkg'` still loads the module, so it counts.
+ */
+export declare const findStaticImports: (file: string, source: string) => Promise<{
+    specifier: string;
+    line: number;
+}[]>;
+/** One attribute or binding, normalised so a rule need not know the node types. */
+export interface TemplateAttr {
+    /** Attribute name without the `:` / `v-bind:` prefix — `data-qa`, `class`, `title`. */
+    name: string;
+    /** Static value, or the raw expression source for a binding. Null for a bare attribute. */
+    value: string | null;
+    /** True for `:title` / `v-bind:title`, false for `title`. */
+    bound: boolean;
+    line: number;
+}
+/**
+ * An element in a Vue template, flattened to what invariant rules actually ask
+ * about. Deliberately not a re-export of compiler-sfc's node types: rules stay
+ * readable, and a compiler upgrade changes this file only.
+ */
+export interface TemplateEl {
+    tag: string;
+    line: number;
+    attrs: TemplateAttr[];
+    /** Element and <template> children, in document order. Text nodes dropped. */
+    children: TemplateEl[];
+    /** For `<template #title>` / `#[slotName]` — the slot name or expression. */
+    slot: string | null;
+    /** True when this element carries a `v-for`. */
+    vFor: boolean;
+}
+/**
+ * Root elements of a .vue file's <template>. Empty array when the file has no
+ * template or the template does not parse — a rule must treat that as "nothing
+ * to say", never as "compliant".
+ */
+export declare const templateElements: (file: string, source: string) => Promise<TemplateEl[]>;
+/** Every element with the given tag, at any depth, in document order. */
+export declare const elementsByTag: (roots: TemplateEl[], tag: string) => TemplateEl[];
+/** Every element at any depth, in document order. */
+export declare const allElements: (roots: TemplateEl[]) => TemplateEl[];
+/** An element's attribute by name, static or bound. */
+export declare const attrOf: (el: TemplateEl, name: string) => TemplateAttr | undefined;

package/dist/invariants/ast.js

@@ -0,0 +1,195 @@
+/**
+ * Real ASTs for the rules that regex cannot express honestly.
+ *
+ * Two parsers, both direct devDependencies, both loaded lazily so a `--rule=R2`
+ * run pays for neither:
+ *   typescript          102 ms load · 153 ms for all 423 app .ts files
+ *   @vue/compiler-sfc    92 ms load · 156 ms for all 398 app .vue files (template AST)
+ *
+ * compiler-sfc was already in the pnpm store transitively (vue-router, vue-gtm,
+ * eslint-processor-vue-blocks); making it explicit added a symlink, not a
+ * download. It exists because four checks in R12/R16 could not be expressed
+ * honestly on lines: a file-wide `data-qa` grep passed when the attribute sat on
+ * an inner <div>, a nested child component's `<template #body>` tripped the
+ * ordering check, `class="bold indigo"` slipped past a `class="indigo"` regex,
+ * and a multi-line `:title` binding hid a <br> from a per-line scan.
+ */
+let tsModule = null;
+const ts = async () => {
+    if (!tsModule)
+        tsModule = (await import('typescript')).default;
+    return tsModule;
+};
+/**
+ * EVERY script body of a .vue file, so the same AST rules work on SFCs.
+ *
+ * Plural on purpose: an SFC may carry both `<script>` and `<script setup>`. A
+ * non-global match returned only the first, so anything in the second block was
+ * invisible — and a rule that silently stops matching looks exactly like a clean
+ * file, which is the failure mode this directory exists to prevent.
+ *
+ * The offset is computed from the match geometry (`index` + the opening tag's
+ * length), not by searching for the body inside the match: a body that happens to
+ * repeat its own opening tag would resolve to the wrong position.
+ */
+const scriptsOf = (file, source) => {
+    if (!file.endsWith('.vue'))
+        return [{ code: source, lineOffset: 0 }];
+    const out = [];
+    const re = /<script[^>]*>([\s\S]*?)<\/script>/g;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        if (m[1] === undefined)
+            continue;
+        const bodyStart = m.index + m[0].length - m[1].length - '</script>'.length;
+        out.push({ code: m[1], lineOffset: source.slice(0, bodyStart).split('\n').length - 1 });
+    }
+    return out;
+};
+/**
+ * Every `JSON.parse(...)` call with a flag for whether a real TryStatement
+ * encloses it — an ancestor walk, not a guess about nearby lines.
+ */
+export const findJsonParseCalls = async (file, source) => {
+    const t = await ts();
+    const out = [];
+    for (const script of scriptsOf(file, source)) {
+        const sf = t.createSourceFile(file, script.code, t.ScriptTarget.Latest, true);
+        const visit = (node) => {
+            if (t.isCallExpression(node)) {
+                const callee = node.expression;
+                const isJsonParse = t.isPropertyAccessExpression(callee)
+                    && callee.name.text === 'parse'
+                    && callee.expression.getText(sf) === 'JSON';
+                if (isJsonParse) {
+                    let parent = node.parent;
+                    let guarded = false;
+                    while (parent) {
+                        if (t.isTryStatement(parent)) {
+                            guarded = true;
+                            break;
+                        }
+                        parent = parent.parent;
+                    }
+                    out.push({
+                        line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 + script.lineOffset,
+                        guarded,
+                    });
+                }
+            }
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return out;
+};
+/**
+ * Every static import that survives compilation: default, named, namespace and bare side-effect
+ * imports plus `export … from` re-exports, in .ts files and in every script block of a .vue file.
+ * Only `import type` / `export type` declarations are dropped — with `verbatimModuleSyntax` (the Nuxt
+ * default) an inline `import { type X } from 'pkg'` still loads the module, so it counts.
+ */
+export const findStaticImports = async (file, source) => {
+    const t = await ts();
+    const out = [];
+    for (const script of scriptsOf(file, source)) {
+        const sf = t.createSourceFile(file, script.code, t.ScriptTarget.Latest, true);
+        for (const node of sf.statements) {
+            const isImport = t.isImportDeclaration(node) && !node.importClause?.isTypeOnly;
+            const isReExport = t.isExportDeclaration(node) && node.moduleSpecifier !== undefined && !node.isTypeOnly;
+            if (!isImport && !isReExport)
+                continue;
+            const specifier = node.moduleSpecifier;
+            if (specifier === undefined || !t.isStringLiteral(specifier))
+                continue;
+            out.push({ specifier: specifier.text, line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 + script.lineOffset });
+        }
+    }
+    return out;
+};
+// ── Vue template AST ───────────────────────────────────────────────────────
+let sfcModule = null;
+const sfc = async () => {
+    if (!sfcModule)
+        sfcModule = await import('@vue/compiler-sfc');
+    return sfcModule;
+};
+const ELEMENT = 1;
+const ATTRIBUTE = 6;
+const DIRECTIVE = 7;
+const normalise = (node) => {
+    if (!node || node.type !== ELEMENT)
+        return null;
+    const attrs = [];
+    let slot = null;
+    let vFor = false;
+    for (const p of node.props ?? []) {
+        const line = p.loc?.start?.line ?? node.loc?.start?.line ?? 1;
+        if (p.type === ATTRIBUTE) {
+            attrs.push({ name: p.name ?? '', value: p.value?.content ?? null, bound: false, line });
+            continue;
+        }
+        if (p.type !== DIRECTIVE)
+            continue;
+        if (p.name === 'for') {
+            vFor = true;
+            continue;
+        }
+        if (p.name === 'slot') {
+            // `#title` → arg.content 'title'; `#[slotName]` → dynamic, keep the source
+            slot = p.arg ? String(p.arg.content ?? p.arg.loc?.source ?? '') : 'default';
+            continue;
+        }
+        if (p.name === 'bind' && p.arg) {
+            attrs.push({ name: String(p.arg.content ?? ''), value: p.exp?.content ?? p.exp?.loc?.source ?? null, bound: true, line });
+        }
+    }
+    return {
+        tag: node.tag ?? '',
+        line: node.loc?.start?.line ?? 1,
+        attrs,
+        children: (node.children ?? []).map(c => normalise(c)).filter((c) => c !== null),
+        slot,
+        vFor,
+    };
+};
+/**
+ * Root elements of a .vue file's <template>. Empty array when the file has no
+ * template or the template does not parse — a rule must treat that as "nothing
+ * to say", never as "compliant".
+ */
+export const templateElements = async (file, source) => {
+    if (!file.endsWith('.vue'))
+        return [];
+    const { parse } = await sfc();
+    let ast;
+    try {
+        ast = parse(source, { filename: file }).descriptor.template?.ast;
+    }
+    catch {
+        return [];
+    }
+    if (!ast)
+        return [];
+    return (ast.children ?? []).map(c => normalise(c)).filter((c) => c !== null);
+};
+/** Every element with the given tag, at any depth, in document order. */
+export const elementsByTag = (roots, tag) => {
+    const out = [];
+    const visit = (el) => {
+        if (el.tag === tag)
+            out.push(el);
+        el.children.forEach(visit);
+    };
+    roots.forEach(visit);
+    return out;
+};
+/** Every element at any depth, in document order. */
+export const allElements = (roots) => {
+    const out = [];
+    const visit = (el) => { out.push(el); el.children.forEach(visit); };
+    roots.forEach(visit);
+    return out;
+};
+/** An element's attribute by name, static or bound. */
+export const attrOf = (el, name) => el.attrs.find(a => a.name === name);

package/dist/invariants/index.d.ts

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,18 @@
+/**
+ * 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 type { Rule } from '../types.js';
+export declare const cRules: Rule[];