@brighterly/lib-fe-codestyle 0.3.0 → 0.5.1

package/dist/invariants/types.d.ts

@@ -14,19 +14,21 @@ export type Level = 'error' | 'warn' | 'off';
  *   B — business:   the funnel-data contract, confirmed by PMM
  *   C — convention: a preference we chose, advisory by default
  *   L — linter:     covered by a built-in ESLint rule, configured elsewhere
+ *   E — e2e:        end-to-end test authoring standards
  * IDs are load-bearing (`--rule=`, `invariant-ignore:`, allowlists, levels) —
  * retire one, never recycle it.
  */
 /** App-local ids are bare; shared-pack ids carry the `core/` prefix (`core/R1`). */
-export type RuleId = `${'' | 'core/'}${'R' | 'B' | 'C' | 'L'}${number}`;
+export type RuleId = `${'' | 'core/'}${'R' | 'B' | 'C' | 'L' | 'E'}${number}`;
 /**
  * Meta rules. They police the escape hatch rather than the app, so they have no
  * family letter — but they are addressable exactly like any other rule
  * (`allowlists`, `levels`, `invariant-ignore`), so they belong in the ID space.
  *   IG0 — an `invariant-ignore` with no reason
  *   IG1 — a reference to a rule ID that no longer exists
+ *   IG2 — an `invariant-ignore` naming a rule declared `noIgnore`
  */
-export type MetaRuleId = 'IG0' | 'IG1';
+export type MetaRuleId = 'IG0' | 'IG1' | 'IG2';
 /** Anything addressable in config or a suppression comment. */
 export type AnyRuleId = RuleId | MetaRuleId;
 /** One violation. `line` is 1-based. */
@@ -74,6 +76,8 @@ export interface SharedRuleSettings {
     typographySource?: string;
     /** `core/C7`: which `<script>` attribute order is canonical in this app. Default 'setup-first' (`<script setup lang="ts">`). */
     scriptAttrOrder?: 'setup-first' | 'lang-first';
+    /** The consumer file whose `invariant-ignore:` strings are self-test FIXTURE DATA, not real suppressions — the engine skips ignore-parsing it entirely, replacing per-file IG0/IG1 allowlist boilerplate. E.g. 'invariants/self-test.mts'. */
+    selfTestFile?: string;
 }
 /** What a rule's `check` receives. */
 export interface RuleContext {
@@ -85,8 +89,14 @@ export interface RuleContext {
     code: string;
     /** Read any other repo-relative file (cached). Returns null if unreadable. */
     read: (rel: string) => string | null;
-    /** Every scanned file in the repo — for rules that resolve references. */
+    /** Every scanned file in the repo minus the `unmaintained` paths — for rules that resolve references. */
     allFiles: string[];
+    /**
+     * Every scanned file INCLUDING the `unmaintained` paths. Undefined unless the rule declares
+     * `seesUnmaintained` — the exclusion is meant to be invisible to a rule, and this is the one
+     * declared way through it.
+     */
+    scanned?: string[];
     /**
      * App-specific paths a SHARED rule needs, supplied by `config.settings`. This is how a
      * portable rule learns where this app keeps its SCSS tokens or its UI-kit root, without
@@ -95,7 +105,7 @@ export interface RuleContext {
     settings: Readonly<SharedRuleSettings & Record<string, string>>;
 }
 /** A `once: true` rule reads its own inputs, so it gets no per-file fields. */
-export type OnceRuleContext = Pick<RuleContext, 'read' | 'allFiles'> & Partial<RuleContext>;
+export type OnceRuleContext = Pick<RuleContext, 'read' | 'allFiles' | 'scanned'> & Partial<RuleContext>;
 interface BaseRule {
     id: RuleId;
     /** Short description — appears in the report and the README inventory. */
@@ -109,8 +119,24 @@ interface BaseRule {
     scope: string[];
     /** Glob patterns to skip within scope. */
     exclude?: string[];
+    /**
+     * The rule cannot be suppressed with `invariant-ignore`; a comment naming it is
+     * itself a finding (IG2). For rules whose author is an AI: exceptions are made by
+     * a human in the rulebook (rule + fixture), never by the agent in the file under
+     * check — an AI writes a plausible reason for free.
+     * Honoured by the runner: the suppression lookup skips such rules, and the IG2
+     * block reports the attempt.
+     */
+    noIgnore?: boolean;
     /** Set when `check` returns a promise, so the runner awaits it. */
     async?: boolean;
+    /**
+     * Hand this rule `scanned` — every file, the `unmaintained` paths included — where every other
+     * rule gets only `allFiles`. The exclusion exists so rules that model the component contract
+     * never meet a tree that does not follow it; a rule asking a different question may opt out,
+     * and says so here.
+     */
+    seesUnmaintained?: boolean;
 }
 /** Runs once per matching file. */
 export interface FileRule extends BaseRule {
@@ -164,6 +190,8 @@ export interface DanglingRefInput {
     configFile?: string;
     /** Contents of `configFile`, so a stale key can be reported on its own line. */
     configSource?: string;
+    /** Answers "does this repo-relative file exist?" — enables the allowlist-path staleness check. */
+    pathExists?: (path: string) => boolean;
 }
 /** An invariant a built-in ESLint rule already covers. */
 export interface LinterOwnedRule {

package/dist/invariants/util.d.ts

@@ -4,7 +4,7 @@
  *
  * No dependencies — this runs in pre-commit, so it must not need an install.
  */
-import type { DanglingRefInput, Finding, Level, Levels } from './types.js';
+import type { DanglingRefInput, Finding, Level, Levels, MetaRuleId } from './types.js';
 /**
  * Minimal glob → RegExp. Supports `**`, `*`, `?` and `{a,b}`.
  * Deliberately not a full glob implementation: rule scopes are simple by
@@ -37,14 +37,22 @@ export declare const parseIgnores: (source: string) => {
     }[];
 };
 /**
- * Blank out comment bodies while preserving every line number and offset, so a
- * rule that greps for an identifier does not fire on prose. Handles `//`,
- * block comments and HTML comments.
+ * Blanks comment bodies in place: every line and every non-comment character stays where it was,
+ * so line numbers and offsets survive. Two grammars:
  *
- * Known limitation: a `//` inside a string literal (a URL) blanks the rest of
- * that line. Harmless for identifier scans; do not use this for parsing.
+ * - script (TS/JS/JSON): a tokenizer that knows string literals, template literals with `${}`
+ *   nesting and regex literals, so `'…/**'` in a glob or `'http://'` in a URL opens nothing. The
+ *   regex version this replaces turned the first such glob in a rule file into an open block
+ *   comment and hid the rest of the file from every rule that reads `code` (land-app, 2026-09-23);
+ * - the template part of a .vue file: HTML comments only — a script tokenizer over prose would take
+ *   "child's" as an open string. Script blocks inside the SFC get the script grammar.
+ *
+ * Markdown and HTML get HTML comments only; no rule reads code out of them. The regex-vs-division
+ * call for `/` is the usual heuristic (what precedes it); a regex right after `)` reads as division,
+ * which leaves its body unparsed — never blanked, so the failure mode is a missed comment, not
+ * hidden code.
  */
-export declare const stripCodeComments: (source: string) => string;
+export declare const stripCodeComments: (source: string, file?: string) => string;
 /** Line number (1-based) of a character offset. */
 export declare const lineOf: (source: string, index: number) => number;
 /**
@@ -67,6 +75,17 @@ export declare const stringKeysOf: (literal: string) => Set<string>;
  * self-test can exercise it without touching the repo.
  */
 export declare const findDanglingRuleRefs: (input: DanglingRefInput) => Finding[];
+/**
+ * `invariant-ignore` comments that name a rule declared `noIgnore` (IG2). The
+ * runner never honours such a comment; reporting it makes the attempt visible so a
+ * reviewer sees the intent and an AI author learns the rule cannot be argued with
+ * in the file under check.
+ */
+export declare const findForbiddenSuppressions: (ignores: {
+    file: string;
+    line: number;
+    ids: string[];
+}[], noIgnoreIds: Set<string>) => Finding[];
 /**
  * Severity of one finding, from three inputs that used to be one.
  *
@@ -101,7 +120,7 @@ export declare const knownRuleIds: (parts: {
     fileScan: string[];
     specs: string[];
     linter: string[];
-    meta?: string[];
+    meta?: MetaRuleId[];
 }) => Set<string>;
 /**
  * The severity override for a rule, or undefined.
@@ -111,3 +130,9 @@ export declare const knownRuleIds: (parts: {
  * accessor keeps every caller from having to care.
  */
 export declare const levelOverrideOf: (levels: Levels, id: string) => Level | undefined;
+/**
+ * The `until YYYY-MM-DD` an allowlist reason may carry. A rule may require one — a coverage gap is
+ * a debt with a date, not a permanent exemption — and report the entry once the date has passed.
+ * ISO dates compare as strings, so the caller needs no Date arithmetic.
+ */
+export declare const exemptionExpiry: (reason: string) => string | null;

package/dist/invariants/util.js

@@ -135,19 +135,166 @@ export const parseIgnores = (source) => {
     return { suppressions, unreasoned, comments };
 };
 /**
- * Blank out comment bodies while preserving every line number and offset, so a
- * rule that greps for an identifier does not fire on prose. Handles `//`,
- * block comments and HTML comments.
+ * Blanks comment bodies in place: every line and every non-comment character stays where it was,
+ * so line numbers and offsets survive. Two grammars:
  *
- * Known limitation: a `//` inside a string literal (a URL) blanks the rest of
- * that line. Harmless for identifier scans; do not use this for parsing.
+ * - script (TS/JS/JSON): a tokenizer that knows string literals, template literals with `${}`
+ *   nesting and regex literals, so `'…/**'` in a glob or `'http://'` in a URL opens nothing. The
+ *   regex version this replaces turned the first such glob in a rule file into an open block
+ *   comment and hid the rest of the file from every rule that reads `code` (land-app, 2026-09-23);
+ * - the template part of a .vue file: HTML comments only — a script tokenizer over prose would take
+ *   "child's" as an open string. Script blocks inside the SFC get the script grammar.
+ *
+ * Markdown and HTML get HTML comments only; no rule reads code out of them. The regex-vs-division
+ * call for `/` is the usual heuristic (what precedes it); a regex right after `)` reads as division,
+ * which leaves its body unparsed — never blanked, so the failure mode is a missed comment, not
+ * hidden code.
  */
-export const stripCodeComments = (source) => {
-    const blank = (m) => m.replace(/[^\n]/g, ' ');
-    return source
-        .replace(/<!--[\s\S]*?-->/g, blank)
-        .replace(/\/\*[\s\S]*?\*\//g, blank)
-        .replace(/(^|[^:])\/\/[^\n]*/g, (m, pre) => pre + blank(m.slice(pre.length)));
+export const stripCodeComments = (source, file = '') => {
+    if (/\.vue$/.test(file) || (file === '' && /<template[\s>]/.test(source) && /<script[\s>]/.test(source)))
+        return stripSfc(source);
+    if (/\.(?:md|html)$/.test(file))
+        return blankHtmlComments(source);
+    return stripScript(source);
+};
+const blankRun = (text) => text.replace(/[^\n]/g, ' ');
+const blankHtmlComments = (source) => source.replace(/<!--[\s\S]*?-->/g, blankRun);
+const stripSfc = (source) => {
+    let out = '';
+    let last = 0;
+    const re = /<script\b[^>]*>([\s\S]*?)<\/script>/g;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const body = m[1] ?? '';
+        const bodyStart = m.index + m[0].length - body.length - '</script>'.length;
+        out += blankHtmlComments(source.slice(last, bodyStart));
+        out += stripScript(body);
+        last = bodyStart + body.length;
+    }
+    return out + blankHtmlComments(source.slice(last));
+};
+/** After one of these a `/` starts a regex literal, not a division. */
+const REGEX_PRECEDER = /[(,=:[!&|?{};+\-*%<>~^]$/;
+const REGEX_KEYWORD = /(?:^|[^\w$])(?:return|typeof|case|do|else|in|instanceof|new|throw|void|yield|await|delete)$/;
+const stripScript = (code) => {
+    const out = code.split('');
+    const n = code.length;
+    const blankAt = (i) => {
+        if (out[i] !== '\n')
+            out[i] = ' ';
+    };
+    const regexAllowed = (i) => {
+        let j = i - 1;
+        while (j >= 0 && /\s/.test(out[j] ?? ''))
+            j--;
+        if (j < 0)
+            return true;
+        const before = out.slice(Math.max(0, j - 12), j + 1).join('');
+        return REGEX_PRECEDER.test(before) || REGEX_KEYWORD.test(before);
+    };
+    const skipString = (start, quote) => {
+        let i = start + 1;
+        while (i < n && code[i] !== quote && code[i] !== '\n') {
+            if (code[i] === '\\')
+                i++;
+            i++;
+        }
+        return i + 1;
+    };
+    const skipRegex = (start) => {
+        let i = start + 1;
+        let inClass = false;
+        while (i < n && code[i] !== '\n') {
+            const ch = code[i];
+            if (ch === '\\') {
+                i += 2;
+                continue;
+            }
+            if (ch === '[')
+                inClass = true;
+            else if (ch === ']')
+                inClass = false;
+            else if (ch === '/' && !inClass) {
+                i++;
+                break;
+            }
+            i++;
+        }
+        while (i < n && /[a-z]/i.test(code[i] ?? ''))
+            i++;
+        return i;
+    };
+    // Returns the index it stopped at: `n`, or the `}` that closes a `${` when `untilBrace` is set.
+    const scan = (start, untilBrace) => {
+        let i = start;
+        let depth = 0;
+        while (i < n) {
+            const c = code[i];
+            const next = code[i + 1];
+            if (c === '"' || c === '\'') {
+                i = skipString(i, c);
+                continue;
+            }
+            if (c === '`') {
+                i = skipTemplate(i);
+                continue;
+            }
+            if (c === '/' && next === '/') {
+                while (i < n && code[i] !== '\n') {
+                    blankAt(i);
+                    i++;
+                }
+                continue;
+            }
+            if (c === '/' && next === '*') {
+                blankAt(i);
+                blankAt(i + 1);
+                i += 2;
+                while (i < n && !(code[i] === '*' && code[i + 1] === '/')) {
+                    blankAt(i);
+                    i++;
+                }
+                if (i < n) {
+                    blankAt(i);
+                    blankAt(i + 1);
+                    i += 2;
+                }
+                continue;
+            }
+            if (c === '/' && regexAllowed(i)) {
+                i = skipRegex(i);
+                continue;
+            }
+            if (untilBrace) {
+                if (c === '{')
+                    depth++;
+                else if (c === '}') {
+                    if (depth === 0)
+                        return i;
+                    depth--;
+                }
+            }
+            i++;
+        }
+        return i;
+    };
+    const skipTemplate = (start) => {
+        let i = start + 1;
+        while (i < n && code[i] !== '`') {
+            if (code[i] === '\\') {
+                i += 2;
+                continue;
+            }
+            if (code[i] === '$' && code[i + 1] === '{') {
+                i = scan(i + 2, true) + 1;
+                continue;
+            }
+            i++;
+        }
+        return i + 1;
+    };
+    scan(0, false);
+    return out.join('');
 };
 /** Line number (1-based) of a character offset. */
 export const lineOf = (source, index) => source.slice(0, index).split('\n').length;
@@ -214,6 +361,21 @@ export const findDanglingRuleRefs = (input) => {
             continue;
         out.push({ file: configFile, line: lineOfKey('levels', id), message: `levels names "${id}", but ${explain(id)} — the severity override does nothing; drop it` });
     }
+    // Allowlist PATHS had no staleness guard: an entry whose file is gone (or renamed)
+    // is inert and silent. Found live in app-funnels — a dead BtnAuthGoogle.vue entry
+    // survived a fork divergence (2026-09-25). Checked only when the caller can answer
+    // existence, so the self-test can still exercise this function without a filesystem.
+    if (input.pathExists) {
+        for (const [id, entries] of Object.entries(allowlists)) {
+            if (!live.has(id))
+                continue; // the dead-id finding above already covers the whole entry
+            for (const path of Object.keys(entries ?? {})) {
+                if (input.pathExists(path))
+                    continue;
+                out.push({ file: configFile, line: lineOfKey('allowlists', path), message: `allowlists["${id}"] names "${path}", but no such file exists — the exemption is inert; drop it or fix the path` });
+            }
+        }
+    }
     for (const { file, line, ids } of ignores) {
         for (const id of ids) {
             if (live.has(id))
@@ -223,6 +385,17 @@ export const findDanglingRuleRefs = (input) => {
     }
     return out;
 };
+/**
+ * `invariant-ignore` comments that name a rule declared `noIgnore` (IG2). The
+ * runner never honours such a comment; reporting it makes the attempt visible so a
+ * reviewer sees the intent and an AI author learns the rule cannot be argued with
+ * in the file under check.
+ */
+export const findForbiddenSuppressions = (ignores, noIgnoreIds) => ignores.flatMap(({ file, line, ids }) => ids.filter(id => noIgnoreIds.has(id)).map(id => ({
+    file,
+    line,
+    message: `invariant-ignore names "${id}", a noIgnore rule — this suppression is inert and the attempt is reported`,
+})));
 const LEVEL_RANK = { off: 0, warn: 1, error: 2 };
 /**
  * Severity of one finding, from three inputs that used to be one.
@@ -269,3 +442,9 @@ export const knownRuleIds = (parts) => new Set([...parts.fileScan, ...parts.spec
  * accessor keeps every caller from having to care.
  */
 export const levelOverrideOf = (levels, id) => levels[id]?.level;
+/**
+ * The `until YYYY-MM-DD` an allowlist reason may carry. A rule may require one — a coverage gap is
+ * a debt with a date, not a permanent exemption — and report the entry once the date has passed.
+ * ISO dates compare as strings, so the caller needs no Date arithmetic.
+ */
+export const exemptionExpiry = (reason) => reason.match(/\buntil\s+(\d{4}-\d{2}-\d{2})\b/)?.[1] ?? null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brighterly/lib-fe-codestyle",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Shared invariant-validator engine, rule pack and ESLint config for Brighterly Nuxt frontend apps",