@brighterly/lib-fe-codestyle 0.4.1 → 0.5.1

package/dist/invariants/ast.d.ts

@@ -32,6 +32,43 @@ export declare const findStaticImports: (file: string, source: string) => Promis
     specifier: string;
     line: number;
 }[]>;
+export interface InlineLiteral {
+    line: number;
+    /** What the literal was fed to — the rule picks the fix per kind. */
+    kind: 'copy' | 'test-id' | 'option' | 'tag';
+    /** Source text of the literal, for the message. */
+    text: string;
+    /** The sink method (copy / test-id), `method.key` for an option, `tag` for a tag. */
+    via: string;
+}
+/**
+ * Every place a file addresses the app through an inline literal instead of the
+ * contract: a string, no-substitution template or RegExp literal fed to a
+ * copy sink, a test-id sink, a copy-carrying option (`getByRole` `name`,
+ * `filter` / `locator` `hasText` / `hasNotText`), or a test `tag`. Array
+ * arguments (`toHaveText(['a', 'b'])`, `tag: [...]`) are unwrapped. An
+ * identifier, a member expression (`copy.x`, `StepName.Grade`) and a template
+ * WITH an interpolation are the allowed forms. Facts only — the rule phrases the
+ * finding. Regex cannot do this honestly: the literal may sit inside nested
+ * parentheses or a multi-line options object, and a commented-out call must
+ * stay silent.
+ *
+ * Deliberately broad on `tag:` — it fires in ANY object literal, so
+ * `const opts = { tag: '@x' }; test('t', opts, …)` is caught; a non-Playwright
+ * `{ tag: 'h1' }` inside a test tree is the accepted rare false positive.
+ */
+export declare const findInlineLiterals: (file: string, source: string) => Promise<InlineLiteral[]>;
+/**
+ * `let` / `var` declarations that outlive a single test — at module scope or inside a
+ * `describe` callback. A declaration inside a test body, a `test.step` callback or
+ * a helper function is per-test and ignored; `const` and `using` are ignored everywhere.
+ */
+export declare const findSharedMutables: (file: string, source: string) => Promise<{
+    line: number;
+    kind: "let" | "var";
+    name: string;
+    scope: "module" | "describe";
+}[]>;
 /** 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`. */
@@ -70,3 +107,48 @@ export declare const elementsByTag: (roots: TemplateEl[], tag: string) => Templa
 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;
+export interface OptionLiteral {
+    /** The `id` property's line, or the object's when it has none. */
+    line: number;
+    /** The `value` label when it is a literal — for the message. */
+    value: string | null;
+    /** `missing`: no `id`; `computed`: an `id` that is not a string literal; `literal` otherwise. */
+    kind: 'missing' | 'computed' | 'literal';
+    /** The literal's cooked value, or the expression's source when computed. */
+    id: string | null;
+}
+/**
+ * Every object literal shaped like a `SelectOption` — it has both a `value` and a `selected`
+ * property — with what its `id` is, so a rule can judge the id without re-parsing the file. An
+ * object built from a spread is skipped: its id may well come from the spread, and reporting it
+ * would be a guess.
+ */
+export declare const findOptionLiterals: (file: string, source: string) => Promise<OptionLiteral[]>;
+/**
+ * Module- or describe-scope `const` holding a mutable container — `{}`, `[]`, `new Map()` … — that
+ * nothing freezes: the `let` of shared state under a different keyword. `as const` and
+ * `Object.freeze(…)` clear it.
+ */
+export declare const findSharedContainers: (file: string, source: string) => Promise<{
+    line: number;
+    name: string;
+    scope: "module" | "describe";
+}[]>;
+/**
+ * Calls to the callees `accept` names whose promise is not taken up where it is made: not under
+ * `await`, not returned, not the expression body of an arrow (which hands it to whoever calls the
+ * arrow — `booking.submitted(() => funnel.bookFirstSlot(…))` relies on exactly that). A bare
+ * statement drops it; an assignment or an argument parks it for a later that usually never comes.
+ */
+export declare const findUnawaitedCalls: (file: string, source: string, accept: (callee: string) => boolean) => Promise<{
+    line: number;
+    callee: string;
+    how: "dropped" | "assigned" | "passed";
+}[]>;
+/**
+ * `test(…)` calls (also `.only` / `.fixme`) declared inside a loop or a `forEach` / `map` callback:
+ * generated tests, which a textual count of `test(` sees as one.
+ */
+export declare const findGeneratedTests: (file: string, source: string) => Promise<{
+    line: number;
+}[]>;

package/dist/invariants/ast.js

@@ -107,6 +107,119 @@ export const findStaticImports = async (file, source) => {
     }
     return out;
 };
+/** Locator / matcher methods whose first argument is user-visible copy. */
+const COPY_SINKS = new Set(['getByText', 'getByLabel', 'getByPlaceholder', 'getByTitle', 'getByAltText', 'toHaveText', 'toContainText', 'toHaveTitle', 'toHaveAccessibleName', 'toHaveAccessibleDescription', 'toHaveAccessibleErrorMessage']);
+/** Methods whose first argument is a test id — a different fix (the enum / qa name), so a different kind. */
+const ID_SINKS = new Set(['getByTestId']);
+/**
+ * Option keys that carry copy, per method. A Map, not an object: a plain object
+ * resolves prototype members, so `toLocaleString(locale, { timeZone })` would
+ * look up a Function as its key list and crash the whole run.
+ */
+const COPY_OPTION_KEYS = new Map([
+    ['getByRole', ['name']],
+    ['filter', ['hasText', 'hasNotText']],
+    ['locator', ['hasText', 'hasNotText']],
+]);
+/**
+ * Every place a file addresses the app through an inline literal instead of the
+ * contract: a string, no-substitution template or RegExp literal fed to a
+ * copy sink, a test-id sink, a copy-carrying option (`getByRole` `name`,
+ * `filter` / `locator` `hasText` / `hasNotText`), or a test `tag`. Array
+ * arguments (`toHaveText(['a', 'b'])`, `tag: [...]`) are unwrapped. An
+ * identifier, a member expression (`copy.x`, `StepName.Grade`) and a template
+ * WITH an interpolation are the allowed forms. Facts only — the rule phrases the
+ * finding. Regex cannot do this honestly: the literal may sit inside nested
+ * parentheses or a multi-line options object, and a commented-out call must
+ * stay silent.
+ *
+ * Deliberately broad on `tag:` — it fires in ANY object literal, so
+ * `const opts = { tag: '@x' }; test('t', opts, …)` is caught; a non-Playwright
+ * `{ tag: 'h1' }` inside a test tree is the accepted rare false positive.
+ */
+export const findInlineLiterals = 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 lineAt = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 + script.lineOffset;
+        const isLiteral = (n) => t.isStringLiteral(n) || t.isNoSubstitutionTemplateLiteral(n) || t.isRegularExpressionLiteral(n);
+        // `name`, `'name'` and `"name"` are the same key; `getText` would keep the quotes.
+        const keyOf = (n) => (t.isIdentifier(n) || t.isStringLiteral(n) ? n.text : n.getText(sf));
+        const unwrap = (n) => (t.isArrayLiteralExpression(n) ? [...n.elements] : [n]);
+        const visit = (node) => {
+            if (t.isCallExpression(node) && t.isPropertyAccessExpression(node.expression)) {
+                const method = node.expression.name.text;
+                const [first] = node.arguments;
+                const sinkKind = COPY_SINKS.has(method) ? 'copy' : ID_SINKS.has(method) ? 'test-id' : null;
+                if (sinkKind && first) {
+                    for (const v of unwrap(first))
+                        if (isLiteral(v))
+                            out.push({ line: lineAt(v), kind: sinkKind, text: v.getText(sf), via: method });
+                }
+                const keys = COPY_OPTION_KEYS.get(method);
+                if (keys) {
+                    for (const arg of node.arguments) {
+                        if (!t.isObjectLiteralExpression(arg))
+                            continue;
+                        for (const p of arg.properties) {
+                            if (t.isPropertyAssignment(p) && keys.includes(keyOf(p.name)) && isLiteral(p.initializer)) {
+                                out.push({ line: lineAt(p.initializer), kind: 'option', text: p.initializer.getText(sf), via: `${method}.${keyOf(p.name)}` });
+                            }
+                        }
+                    }
+                }
+            }
+            if (t.isPropertyAssignment(node) && keyOf(node.name) === 'tag') {
+                for (const v of unwrap(node.initializer)) {
+                    // `.text` is the cooked value: '@smoke', "@smoke" and `@smoke` all pass; /@smoke/ does not.
+                    if (isLiteral(v) && v.text !== '@smoke')
+                        out.push({ line: lineAt(v), kind: 'tag', text: v.getText(sf), via: 'tag' });
+                }
+            }
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return out;
+};
+/**
+ * `let` / `var` declarations that outlive a single test — at module scope or inside a
+ * `describe` callback. A declaration inside a test body, a `test.step` callback or
+ * a helper function is per-test and ignored; `const` and `using` are ignored everywhere.
+ */
+export const findSharedMutables = 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 isFn = (n) => t.isArrowFunction(n) || t.isFunctionExpression(n) || t.isFunctionDeclaration(n) || t.isMethodDeclaration(n);
+        /** 'module' when no function encloses the statement, 'describe' when the nearest one is a describe callback, else null. */
+        const sharedScope = (st) => {
+            let p = st.parent;
+            while (p && !isFn(p))
+                p = p.parent;
+            if (!p)
+                return 'module';
+            const call = p.parent;
+            return call && t.isCallExpression(call) && /\bdescribe\b/.test(call.expression.getText(sf)) ? 'describe' : null;
+        };
+        const visit = (node) => {
+            if (t.isVariableStatement(node) && !(node.declarationList.flags & (t.NodeFlags.Const | t.NodeFlags.Using))) {
+                const scope = sharedScope(node);
+                if (scope) {
+                    const kind = node.declarationList.flags & t.NodeFlags.Let ? 'let' : 'var';
+                    for (const d of node.declarationList.declarations) {
+                        out.push({ line: sf.getLineAndCharacterOfPosition(d.getStart(sf)).line + 1 + script.lineOffset, kind, name: d.name.getText(sf), scope });
+                    }
+                }
+            }
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return out;
+};
 // ── Vue template AST ───────────────────────────────────────────────────────
 let sfcModule = null;
 const sfc = async () => {
@@ -193,3 +306,160 @@ export const allElements = (roots) => {
 };
 /** An element's attribute by name, static or bound. */
 export const attrOf = (el, name) => el.attrs.find(a => a.name === name);
+/**
+ * Every object literal shaped like a `SelectOption` — it has both a `value` and a `selected`
+ * property — with what its `id` is, so a rule can judge the id without re-parsing the file. An
+ * object built from a spread is skipped: its id may well come from the spread, and reporting it
+ * would be a guess.
+ */
+export const findOptionLiterals = 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 lineAt = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 + script.lineOffset;
+        const keyOf = (n) => (t.isIdentifier(n) || t.isStringLiteral(n) ? n.text : null);
+        const isText = (n) => t.isStringLiteral(n) || t.isNoSubstitutionTemplateLiteral(n);
+        const visit = (node) => {
+            if (t.isObjectLiteralExpression(node) && !node.properties.some(p => t.isSpreadAssignment(p))) {
+                const named = new Map();
+                for (const p of node.properties) {
+                    const key = t.isPropertyAssignment(p) || t.isShorthandPropertyAssignment(p) ? keyOf(p.name) : null;
+                    if (key !== null)
+                        named.set(key, p);
+                }
+                if (named.has('value') && named.has('selected')) {
+                    const valueProp = named.get('value');
+                    const value = valueProp && t.isPropertyAssignment(valueProp) && isText(valueProp.initializer) ? valueProp.initializer.text : null;
+                    const idProp = named.get('id');
+                    if (!idProp)
+                        out.push({ line: lineAt(node), value, kind: 'missing', id: null });
+                    else if (t.isPropertyAssignment(idProp) && isText(idProp.initializer))
+                        out.push({ line: lineAt(idProp), value, kind: 'literal', id: idProp.initializer.text });
+                    else
+                        out.push({ line: lineAt(idProp), value, kind: 'computed', id: idProp.getText(sf) });
+                }
+            }
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return out;
+};
+/**
+ * Module- or describe-scope `const` holding a mutable container — `{}`, `[]`, `new Map()` … — that
+ * nothing freezes: the `let` of shared state under a different keyword. `as const` and
+ * `Object.freeze(…)` clear it.
+ */
+export const findSharedContainers = 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 lineAt = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 + script.lineOffset;
+        const isDescribeCall = (n) => n !== undefined && t.isCallExpression(n) && /(?:^|\.)describe$/.test(n.expression.getText(sf));
+        const scopeOf = (statement) => {
+            const parent = statement.parent;
+            if (t.isSourceFile(parent))
+                return 'module';
+            const fn = t.isBlock(parent) ? parent.parent : undefined;
+            if (fn !== undefined && (t.isArrowFunction(fn) || t.isFunctionExpression(fn)) && isDescribeCall(fn.parent))
+                return 'describe';
+            return null;
+        };
+        const isContainer = (init) => {
+            if (t.isObjectLiteralExpression(init) || t.isArrayLiteralExpression(init))
+                return true;
+            return t.isNewExpression(init) && /^(?:Map|Set|WeakMap|WeakSet|Array)$/.test(init.expression.getText(sf));
+        };
+        const isAsConst = (n) => t.isAsExpression(n) && t.isTypeReferenceNode(n.type) && n.type.typeName.getText(sf) === 'const';
+        const isFrozen = (init) => isAsConst(init) || (t.isCallExpression(init) && init.expression.getText(sf) === 'Object.freeze');
+        /** `[] as string[]`, `({}) satisfies X`, `<T>[]` — the wrapper changes the type, not the mutability. */
+        const unwrap = (init) => {
+            let e = init;
+            for (;;) {
+                if (t.isParenthesizedExpression(e) || t.isSatisfiesExpression(e) || t.isTypeAssertionExpression(e) || (t.isAsExpression(e) && !isAsConst(e)))
+                    e = e.expression;
+                else
+                    return e;
+            }
+        };
+        const visit = (node) => {
+            if (t.isVariableStatement(node) && (node.declarationList.flags & t.NodeFlags.Const) !== 0) {
+                const scope = scopeOf(node);
+                if (scope !== null) {
+                    for (const decl of node.declarationList.declarations) {
+                        const init = decl.initializer;
+                        if (init !== undefined && !isFrozen(init) && isContainer(unwrap(init)))
+                            out.push({ line: lineAt(decl), name: decl.name.getText(sf), scope });
+                    }
+                }
+            }
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return out;
+};
+/**
+ * Calls to the callees `accept` names whose promise is not taken up where it is made: not under
+ * `await`, not returned, not the expression body of an arrow (which hands it to whoever calls the
+ * arrow — `booking.submitted(() => funnel.bookFirstSlot(…))` relies on exactly that). A bare
+ * statement drops it; an assignment or an argument parks it for a later that usually never comes.
+ */
+export const findUnawaitedCalls = async (file, source, accept) => {
+    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 lineAt = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 + script.lineOffset;
+        const visit = (node) => {
+            if (t.isCallExpression(node) && accept(node.expression.getText(sf))) {
+                let outer = node;
+                while (t.isParenthesizedExpression(outer.parent))
+                    outer = outer.parent;
+                const parent = outer.parent;
+                const takenUp = t.isAwaitExpression(parent) || t.isReturnStatement(parent) || (t.isArrowFunction(parent) && parent.body === outer);
+                if (!takenUp) {
+                    const how = t.isExpressionStatement(parent) || t.isVoidExpression(parent)
+                        ? 'dropped'
+                        : t.isVariableDeclaration(parent) || (t.isBinaryExpression(parent) && parent.operatorToken.kind === t.SyntaxKind.EqualsToken)
+                            ? 'assigned'
+                            : 'passed';
+                    out.push({ line: lineAt(node), callee: node.expression.getText(sf), how });
+                }
+            }
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return out;
+};
+/**
+ * `test(…)` calls (also `.only` / `.fixme`) declared inside a loop or a `forEach` / `map` callback:
+ * generated tests, which a textual count of `test(` sees as one.
+ */
+export const findGeneratedTests = 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 lineAt = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 + script.lineOffset;
+        const isLoop = (n) => t.isForStatement(n) || t.isForOfStatement(n) || t.isForInStatement(n) || t.isWhileStatement(n) || t.isDoStatement(n);
+        const isIteratorCallback = (n) => (t.isArrowFunction(n) || t.isFunctionExpression(n)) && t.isCallExpression(n.parent) && t.isPropertyAccessExpression(n.parent.expression) && /^(?:forEach|map|flatMap|each)$/.test(n.parent.expression.name.text);
+        const generated = (call) => {
+            for (let p = call.parent; p !== undefined && !t.isSourceFile(p); p = p.parent) {
+                if (isLoop(p) || isIteratorCallback(p))
+                    return true;
+            }
+            return false;
+        };
+        const visit = (node) => {
+            if (t.isCallExpression(node) && /^test(?:\.(?:only|fixme))?$/.test(node.expression.getText(sf)) && generated(node))
+                out.push({ line: lineAt(node) });
+            t.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    return out;
+};

package/dist/invariants/rules/regression.js

@@ -47,6 +47,9 @@ const scssInStyleBlock = {
     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'],
+    // 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/**'],
     check: ({ file, source }) => {
         const out = [];
         const re = /<style\b[^>]*>([\s\S]*?)<\/style>/g;

package/dist/invariants/run.d.ts

@@ -13,6 +13,7 @@
  *   2 — the validator itself failed
  */
 import type { Allowlists, Levels, LinterOwnedRule, RetiredRules, Rule, Unmaintained } from './types.js';
+import type { Fixture } from './self-test.js';
 export interface RunOptions {
     /** Repo root. Passed, never derived — import.meta.url here resolves into node_modules. */
     root: string;
@@ -39,11 +40,7 @@ export interface RunOptions {
     /** Config file a dangling allowlist/levels key is reported against. */
     configFile?: string;
     /** Fixtures for --self-test, keyed by rule id. Omit to skip the self-test entirely. */
-    fixtures?: Record<string, {
-        file: string;
-        bad: string;
-        good: string;
-    }>;
+    fixtures?: Record<string, Fixture>;
     /** Repo-specific self-test assertions; each returns failure messages. */
     extraChecks?: (() => string[] | Promise<string[]>)[];
     /** Rule ids exempt from the fixture requirement — registry rules a fixture cannot express. */