@blumintinc/eslint-plugin-blumint 1.20.41 → 1.20.43

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.41',
+        version: '1.20.43',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/enforce-callback-memo.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const createRule_1 = require("../utils/createRule");
 const utils_1 = require("@typescript-eslint/utils");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 exports.default = (0, createRule_1.createRule)({
     name: 'enforce-callback-memo',
     meta: {
@@ -194,6 +195,14 @@ exports.default = (0, createRule_1.createRule)({
                 node.value.type !== utils_1.AST_NODE_TYPES.JSXExpressionContainer) {
                 return;
             }
+            // The only remediation this rule offers is a hook call, which is legal
+            // solely inside a component or a hook. Module-scope JSX, a plain helper
+            // that happens to build JSX, and JSX rendered from a test body are all
+            // outside any render path, so wrapping there would throw
+            // "Invalid hook call" while saving no re-render.
+            if (!ASTHelpers_1.ASTHelpers.isInsideComponentOrHook(node, context)) {
+                return;
+            }
             // Props of JSX built inside a useMemo factory inherit the memo's stability
             if (isInsideUseMemoFactory(node)) {
                 return;

package/lib/rules/logical-top-to-bottom-grouping.js

@@ -663,7 +663,43 @@ function statementDeclaresAny(statement, names) {
     }
     return false;
 }
-function findEarliestSafeIndex(body, startIndex, dependencies, { allowHooks }) {
+/**
+ * Whether the subtree contains a property read. `parent` is skipped because it
+ * points back up the tree and would make this walk unbounded.
+ */
+function containsMemberRead(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        return true;
+    }
+    return Object.entries(node).some(([key, value]) => {
+        if (key === 'parent') {
+            return false;
+        }
+        if (Array.isArray(value)) {
+            return value.some((item) => ASTHelpers_1.ASTHelpers.isNode(item) && containsMemberRead(item));
+        }
+        return ASTHelpers_1.ASTHelpers.isNode(value) && containsMemberRead(value);
+    });
+}
+/**
+ * Whether a declaration captures a value read off some object's property.
+ *
+ * Such a read is side-effect-*free*, which is what `isPureDeclaration` answers,
+ * but it is not order-*independent*: the value is whatever that property held at
+ * this point in the block. Those are different questions, and only the second
+ * licenses moving an effect across the declaration. Conflating them let a
+ * hoisted call land above a deliberate before-snapshot, turning a before/after
+ * comparison into a self-referential one that still type-checks and still lints
+ * clean.
+ */
+function capturesObservableState(statement) {
+    if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
+        return false;
+    }
+    return statement.declarations.some((declarator) => Boolean(declarator.init) &&
+        containsMemberRead(declarator.init));
+}
+function findEarliestSafeIndex(body, startIndex, dependencies, { allowHooks, stopAtObservableState = false, }) {
     // Reuse the backward scan so guard/side-effect movers stop before impure work or any declaration/reference of tracked dependencies.
     let targetIndex = startIndex;
     for (let cursor = startIndex - 1; cursor >= 0; cursor -= 1) {
@@ -677,6 +713,9 @@ function findEarliestSafeIndex(body, startIndex, dependencies, { allowHooks }) {
         if (statementReferencesAny(candidate, dependencies)) {
             break;
         }
+        if (stopAtObservableState && capturesObservableState(candidate)) {
+            break;
+        }
         targetIndex = cursor;
     }
     return targetIndex;
@@ -1354,6 +1393,7 @@ function handleSideEffects(sink, body) {
         }
         const targetIndex = findEarliestSafeIndex(body, index, dependencies, {
             allowHooks: false,
+            stopAtObservableState: true,
         });
         if (targetIndex === index) {
             return;

package/lib/rules/memo-nested-react-components.js

@@ -329,6 +329,16 @@ const returnExpressionIsComponent = (expression, reactImports) => {
     if (isFunctionExpression(unwrapped)) {
         return Boolean(functionCreatesComponent(unwrapped, reactImports));
     }
+    // A factory that hands its component back inside an object is still an HOC
+    // factory, not a render body — the ES-module interop shape
+    // `{ __esModule: true, default: Component }` that every `jest.mock()` factory
+    // uses puts the component one property deep. Recursing covers nesting; render
+    // bodies return JSX rather than object literals, so this does not blur the
+    // two.
+    if (unwrapped.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+        return unwrapped.properties.some((property) => property.type === utils_1.AST_NODE_TYPES.Property &&
+            returnExpressionIsComponent(property.value, reactImports));
+    }
     return false;
 };
 const returnExpressionIsJsx = (expression) => {
@@ -420,6 +430,107 @@ const collectDirectReturnExpressions = (fn) => {
     fn.body.body.forEach(visitStatement);
     return returns;
 };
+/** Module-mock registrars whose factory argument runs at registration time. */
+const MODULE_MOCK_REGISTRARS = new Set(['mock', 'doMock']);
+/**
+ * Test-runner callbacks. A `describe` body runs once at collection time and an
+ * `it`/hook body once per test — neither re-renders, so a component defined
+ * directly in one has an identity as stable as a module-scope export.
+ */
+const TEST_RUNNER_NAMES = new Set([
+    'describe',
+    'it',
+    'test',
+    'beforeEach',
+    'beforeAll',
+    'afterEach',
+    'afterAll',
+]);
+/**
+ * The identifier a callee is rooted at, so `it`, `it.only`, `it.each(...)` and
+ * `describe.each`...`` all resolve to the runner's own name.
+ */
+const calleeRootName = (callee) => {
+    switch (callee.type) {
+        case utils_1.AST_NODE_TYPES.Identifier:
+            return callee.name;
+        case utils_1.AST_NODE_TYPES.MemberExpression:
+            return calleeRootName(callee.object);
+        case utils_1.AST_NODE_TYPES.CallExpression:
+            return calleeRootName(callee.callee);
+        case utils_1.AST_NODE_TYPES.TaggedTemplateExpression:
+            return calleeRootName(callee.tag);
+        default:
+            return undefined;
+    }
+};
+/**
+ * True when `fn` is a callback handed to a test-runner call.
+ *
+ * Requiring the call to stand alone as a statement keeps an ordinary helper that
+ * merely shares a name — a `test(...)` used for its return value, say — from
+ * collecting the exemption, since runner calls are always statements.
+ */
+const isTestRunnerCallback = (fn) => {
+    const call = fn.parent;
+    if (!call || call.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+        return false;
+    }
+    if (!call.arguments.includes(fn)) {
+        return false;
+    }
+    if (call.parent?.type !== utils_1.AST_NODE_TYPES.ExpressionStatement) {
+        return false;
+    }
+    const root = calleeRootName(call.callee);
+    return root !== undefined && TEST_RUNNER_NAMES.has(root);
+};
+/**
+ * True when `fn` is the factory argument of a `jest.mock()` / `jest.doMock()`
+ * call.
+ *
+ * Such a factory runs once when the module registry resolves the mock, never
+ * per render, so a component defined inside it is as identity-stable as a
+ * module-scope export and the remount harm this rule describes cannot occur.
+ * Keyed on the call rather than on what the factory returns because the
+ * component is often unreachable from the return expression — the common
+ * registry shape hands it back through
+ * `Object.fromEntries(ids.map((id) => [id, Stub]))`, where no amount of
+ * unwrapping the returned object literal finds it.
+ */
+const isModuleMockFactory = (fn) => {
+    const call = fn.parent;
+    if (!call || call.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+        return false;
+    }
+    if (!call.arguments.includes(fn)) {
+        return false;
+    }
+    const { callee } = call;
+    return (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !callee.computed &&
+        callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+        callee.object.name === 'jest' &&
+        callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        MODULE_MOCK_REGISTRARS.has(callee.property.name));
+};
+/**
+ * Whether `fn` sits lexically inside a test-runner callback, at any depth.
+ *
+ * Unlike {@link isTestRunnerCallback}, which asks whether the function *is* the
+ * callback, this reaches helpers declared within one. Safe to widen this far
+ * only because the caller pairs it with "does not return JSX".
+ */
+const isWithinTestRunnerCallback = (fn) => {
+    let current = fn;
+    while (current) {
+        if (isTestRunnerCallback(current)) {
+            return true;
+        }
+        current = current.parent;
+    }
+    return false;
+};
 /**
  * True when the nearest enclosing function is an HOC factory—it returns a
  * component (memo/forwardRef/component reference) and never returns JSX. Such
@@ -432,10 +543,25 @@ const isInsideHocFactory = (node, reactImports) => {
     if (!enclosing) {
         return false;
     }
+    // Both checks look only at the NEAREST enclosing function, so a component
+    // nested inside another component that itself sits in an it() body is still
+    // reported — the exemption does not leak down the tree.
+    if (isModuleMockFactory(enclosing) || isTestRunnerCallback(enclosing)) {
+        return true;
+    }
+    // A helper *declared* in a test body — `renderUpdater` and friends, which
+    // build a tree and hand it to `render()` — runs once per test rather than per
+    // render. It is only scaffolding if it is not itself a component, which the
+    // `returnsJsx` check below establishes; a real component in the same describe
+    // body still returns JSX and is still reported.
+    const withinTest = isWithinTestRunnerCallback(enclosing);
     const returns = collectDirectReturnExpressions(enclosing);
     const returnsComponent = returns.some((expression) => returnExpressionIsComponent(expression, reactImports));
     const returnsJsx = returns.some((expression) => returnExpressionIsJsx(expression));
-    return returnsComponent && !returnsJsx;
+    if (returnsJsx) {
+        return false;
+    }
+    return returnsComponent || withinTest;
 };
 exports.memoNestedReactComponents = (0, createRule_1.createRule)({
     name: 'memo-nested-react-components',

package/lib/utils/ASTHelpers.d.ts

@@ -61,6 +61,47 @@ export declare class ASTHelpers {
      * parenthesized expressions to get to the underlying expression.
      */
     static unwrapTSAssertions(node: TSESTree.Node): TSESTree.Node;
+    /**
+     * Calls that wrap a component/hook definition without renaming it, so the
+     * binding they are assigned to still names the wrapped function
+     * (`const Component = memo(() => ...)`).
+     */
+    private static readonly TRANSPARENT_WRAPPER_CALLEES;
+    private static isFunctionNode;
+    private static isTransparentWrapperCall;
+    private static staticPropertyName;
+    /**
+     * Resolves the name a function is known by: its own identifier, or the
+     * binding it is assigned to (variable, object property, class field,
+     * assignment target). Returns null only when the function is truly
+     * anonymous, e.g. an inline callback argument such as `items.map(() => ...)`.
+     */
+    static inferFunctionName(node: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression | TSESTree.FunctionDeclaration): string | null;
+    /**
+     * React's universal convention: only PascalCase-initial identifiers are
+     * components, and only `use`-prefixed ones are hooks. A camelCase name is a
+     * plain helper or a render-prop callback.
+     */
+    private static isComponentOrHookName;
+    /**
+     * Reports whether a node sits anywhere inside a React component or hook, so a
+     * rule whose remediation is a hook call (useCallback/useMemo/useState) can
+     * stay silent where that call would be a Rules-of-Hooks violation: module
+     * scope, a plain helper function, or a test body such as `it(() => ...)`.
+     *
+     * The whole enclosing-function ancestry is consulted, not just the nearest
+     * function: a `.map()` render callback inside a component is still a render
+     * path and must stay reportable.
+     *
+     * Classification is name-first. A function the developer named is judged by
+     * that name alone — `buildTree` is not a component even though it returns
+     * JSX, because the name is an explicit signal about its role. Only a truly
+     * anonymous function falls back to "does it return JSX", which is what makes
+     * `memo(() => <div />)` a component. That fallback is suppressed when some
+     * enclosing function carries a non-component name, since a callback nested in
+     * a plain helper is no more of a render path than the helper itself.
+     */
+    static isInsideComponentOrHook(node: TSESTree.Node, context?: Readonly<TSESLint.RuleContext<string, readonly unknown[]>>): boolean;
     /**
      * Helper to get ancestors of a node in a way that is compatible with both ESLint v8 and v9.
      * In ESLint v9, context.getAncestors() is deprecated and moved to context.sourceCode.getAncestors(node).

package/lib/utils/ASTHelpers.js

@@ -661,6 +661,140 @@ class ASTHelpers {
         }
         return inner;
     }
+    static isFunctionNode(node) {
+        return (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+            node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+            node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration);
+    }
+    static isTransparentWrapperCall(node) {
+        const { callee } = node;
+        if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return this.TRANSPARENT_WRAPPER_CALLEES.has(callee.name);
+        }
+        return (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+            !callee.computed &&
+            callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+            this.TRANSPARENT_WRAPPER_CALLEES.has(callee.property.name));
+    }
+    static staticPropertyName(key, computed) {
+        if (computed) {
+            return null;
+        }
+        if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+            return key.name;
+        }
+        if (key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === 'string') {
+            return key.value;
+        }
+        return null;
+    }
+    /**
+     * Resolves the name a function is known by: its own identifier, or the
+     * binding it is assigned to (variable, object property, class field,
+     * assignment target). Returns null only when the function is truly
+     * anonymous, e.g. an inline callback argument such as `items.map(() => ...)`.
+     */
+    static inferFunctionName(node) {
+        if (node.id?.name) {
+            return node.id.name;
+        }
+        let child = node;
+        let parent = node.parent;
+        while (parent) {
+            switch (parent.type) {
+                case utils_1.AST_NODE_TYPES.VariableDeclarator:
+                    return parent.id.type === utils_1.AST_NODE_TYPES.Identifier
+                        ? parent.id.name
+                        : null;
+                case utils_1.AST_NODE_TYPES.Property:
+                    return this.staticPropertyName(parent.key, parent.computed);
+                case utils_1.AST_NODE_TYPES.PropertyDefinition:
+                case utils_1.AST_NODE_TYPES.MethodDefinition:
+                    return this.staticPropertyName(parent.key, parent.computed);
+                case utils_1.AST_NODE_TYPES.AssignmentExpression: {
+                    const { left } = parent;
+                    if (left.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        return left.name;
+                    }
+                    if (left.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                        return this.staticPropertyName(left.property, left.computed);
+                    }
+                    return null;
+                }
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+                    child = parent;
+                    parent = parent.parent;
+                    continue;
+                case utils_1.AST_NODE_TYPES.CallExpression:
+                    // Only step through wrappers that preserve identity; an arbitrary
+                    // callback argument (`items.map(fn)`) is not named by whatever the
+                    // call's result is assigned to.
+                    if (parent.arguments.includes(child) &&
+                        this.isTransparentWrapperCall(parent)) {
+                        child = parent;
+                        parent = parent.parent;
+                        continue;
+                    }
+                    return null;
+                default:
+                    return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * React's universal convention: only PascalCase-initial identifiers are
+     * components, and only `use`-prefixed ones are hooks. A camelCase name is a
+     * plain helper or a render-prop callback.
+     */
+    static isComponentOrHookName(name) {
+        return /^[A-Z]/.test(name) || /^use[A-Z0-9_]/.test(name);
+    }
+    /**
+     * Reports whether a node sits anywhere inside a React component or hook, so a
+     * rule whose remediation is a hook call (useCallback/useMemo/useState) can
+     * stay silent where that call would be a Rules-of-Hooks violation: module
+     * scope, a plain helper function, or a test body such as `it(() => ...)`.
+     *
+     * The whole enclosing-function ancestry is consulted, not just the nearest
+     * function: a `.map()` render callback inside a component is still a render
+     * path and must stay reportable.
+     *
+     * Classification is name-first. A function the developer named is judged by
+     * that name alone — `buildTree` is not a component even though it returns
+     * JSX, because the name is an explicit signal about its role. Only a truly
+     * anonymous function falls back to "does it return JSX", which is what makes
+     * `memo(() => <div />)` a component. That fallback is suppressed when some
+     * enclosing function carries a non-component name, since a callback nested in
+     * a plain helper is no more of a render path than the helper itself.
+     */
+    static isInsideComponentOrHook(node, context) {
+        const anonymousFunctions = [];
+        let hasNamedNonComponent = false;
+        let current = node.parent;
+        while (current) {
+            if (this.isFunctionNode(current)) {
+                const name = this.inferFunctionName(current);
+                if (name === null) {
+                    anonymousFunctions.push(current);
+                }
+                else if (this.isComponentOrHookName(name)) {
+                    return true;
+                }
+                else {
+                    hasNamedNonComponent = true;
+                }
+            }
+            current = current.parent;
+        }
+        if (hasNamedNonComponent) {
+            return false;
+        }
+        return anonymousFunctions.some((fn) => this.returnsJSX(fn, context));
+    }
     /**
      * Helper to get ancestors of a node in a way that is compatible with both ESLint v8 and v9.
      * In ESLint v9, context.getAncestors() is deprecated and moved to context.sourceCode.getAncestors(node).
@@ -671,5 +805,17 @@ class ASTHelpers {
             (context.getAncestors ? context.getAncestors() : []));
     }
 }
+/**
+ * Calls that wrap a component/hook definition without renaming it, so the
+ * binding they are assigned to still names the wrapped function
+ * (`const Component = memo(() => ...)`).
+ */
+ASTHelpers.TRANSPARENT_WRAPPER_CALLEES = new Set([
+    'forwardRef',
+    'memo',
+    'observer',
+    'useCallback',
+    'useMemo',
+]);
 exports.ASTHelpers = ASTHelpers;
 //# sourceMappingURL=ASTHelpers.js.map

package/lib/utils/installValidCaseGuard.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/utils/installValidCaseGuard.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const eslint_1 = require("eslint");
+const validCaseFalsifiability_1 = require("./validCaseFalsifiability");
+/** Marks a prototype as patched so a re-import cannot double-wrap `run`. */
+const INSTALLED = Symbol.for('blumint.validCaseGuard.installed');
+function install(prototype) {
+    if (!prototype || prototype[INSTALLED]) {
+        return;
+    }
+    const original = prototype.run;
+    prototype.run = function patchedRun(...args) {
+        const [name, , tests] = args;
+        (0, validCaseFalsifiability_1.assertValidCasesCanFail)(name, tests?.valid ?? []);
+        return original.apply(this, args);
+    };
+    prototype[INSTALLED] = true;
+}
+// Both are patched because the typescript-eslint tester does not necessarily
+// inherit `run` from the core one; whichever a suite reaches for is covered.
+install(utils_1.ESLintUtils.RuleTester?.prototype);
+install(eslint_1.RuleTester?.prototype);
+//# sourceMappingURL=installValidCaseGuard.js.map

package/lib/utils/validCaseFalsifiability.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `RuleTester` registers the rule under exactly the bare name passed to `run()`,
+ * so a block `eslint-disable` written *inside a test fixture* silences the very
+ * rule the case is asserting about. A `valid` case carrying one passes for every
+ * possible implementation — including one that reports on every node — so it
+ * proves nothing while looking like false-positive protection.
+ *
+ * That is the worst place to lose coverage: CLAUDE.md ranks a false positive
+ * above a false negative, and agora disables a rule outright on any report, so
+ * `valid` cases are what stand between a regression and a rule being switched
+ * off downstream.
+ *
+ * Line-scoped directives (`eslint-disable-line`, `eslint-disable-next-line`) are
+ * deliberately not treated this way. They pin suppression to one line, so a rule
+ * that moved or widened its report still escapes them and fails the case.
+ * Likewise a plugin-prefixed id (`@blumintinc/blumint/<name>`) does not suppress
+ * anything under `RuleTester`, which knows the rule only by its bare name.
+ *
+ * Known blind spot: a fixture whose line-scoped directives happen to cover
+ * *every* reportable line is inert too, and this check does not see it —
+ * deciding that needs to know which lines a rule would report on, which is a
+ * whole-suite mutation run rather than something a per-suite check can afford.
+ * Two such cases exist (both in `prefer-fragment-component`'s suppression
+ * matrix). `.claude/tmp/vacuous-sweep.sh` is the exhaustive dynamic check and
+ * puts the true total at 23 against the 21 counted here.
+ */
+/** Whether `code` blanket-disables `ruleName` somewhere in the fixture. */
+export declare function suppressesRuleUnderTest(code: string, ruleName: string): boolean;
+type ValidCase = string | {
+    code?: string;
+};
+/**
+ * Cases that carry a blanket disable *on purpose*: they exist to prove a rule
+ * honours suppression (the #1404 import-carrier class), so the directive is the
+ * subject of the test rather than an accident.
+ *
+ * Counts are exact — not a minimum — so a newly added inert case fails here
+ * instead of shipping. Resolving #1489, which decides whether these are
+ * redundant with the guards already in each rule's `invalid` array, is what
+ * removes entries; the map should only ever shrink.
+ */
+export declare const CASES_ALLOWED_TO_SUPPRESS: Readonly<Record<string, number>>;
+/**
+ * Throws when a rule's `valid` array contains more blanket-suppressed cases than
+ * are deliberately allowed.
+ */
+export declare function assertValidCasesCanFail(ruleName: string, valid: readonly ValidCase[]): void;
+export {};

package/lib/utils/validCaseFalsifiability.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * `RuleTester` registers the rule under exactly the bare name passed to `run()`,
+ * so a block `eslint-disable` written *inside a test fixture* silences the very
+ * rule the case is asserting about. A `valid` case carrying one passes for every
+ * possible implementation — including one that reports on every node — so it
+ * proves nothing while looking like false-positive protection.
+ *
+ * That is the worst place to lose coverage: CLAUDE.md ranks a false positive
+ * above a false negative, and agora disables a rule outright on any report, so
+ * `valid` cases are what stand between a regression and a rule being switched
+ * off downstream.
+ *
+ * Line-scoped directives (`eslint-disable-line`, `eslint-disable-next-line`) are
+ * deliberately not treated this way. They pin suppression to one line, so a rule
+ * that moved or widened its report still escapes them and fails the case.
+ * Likewise a plugin-prefixed id (`@blumintinc/blumint/<name>`) does not suppress
+ * anything under `RuleTester`, which knows the rule only by its bare name.
+ *
+ * Known blind spot: a fixture whose line-scoped directives happen to cover
+ * *every* reportable line is inert too, and this check does not see it —
+ * deciding that needs to know which lines a rule would report on, which is a
+ * whole-suite mutation run rather than something a per-suite check can afford.
+ * Two such cases exist (both in `prefer-fragment-component`'s suppression
+ * matrix). `.claude/tmp/vacuous-sweep.sh` is the exhaustive dynamic check and
+ * puts the true total at 23 against the 21 counted here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidCasesCanFail = exports.CASES_ALLOWED_TO_SUPPRESS = exports.suppressesRuleUnderTest = void 0;
+/** ESLint separates a directive's rule list from its justification with ` -- `. */
+const JUSTIFICATION = /\s--\s[\s\S]*$/;
+/**
+ * Block-form disables only. `eslint-disable` written as a line comment is not a
+ * directive at all, and the `-line` / `-next-line` forms are line-scoped.
+ */
+const BLOCK_DISABLE = /\/\*\s*eslint-disable(?!-next-line\b|-line\b)([\s\S]*?)\*\//g;
+/**
+ * The rule ids a block disable turns off, or `null` for a bare directive, which
+ * turns off everything.
+ */
+function disabledRules(directiveBody) {
+    const body = directiveBody.replace(JUSTIFICATION, '').trim();
+    if (body === '') {
+        return null;
+    }
+    return new Set(body
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean));
+}
+/** Whether `code` blanket-disables `ruleName` somewhere in the fixture. */
+function suppressesRuleUnderTest(code, ruleName) {
+    BLOCK_DISABLE.lastIndex = 0;
+    let match = BLOCK_DISABLE.exec(code);
+    while (match !== null) {
+        const rules = disabledRules(match[1]);
+        if (rules === null || rules.has(ruleName)) {
+            return true;
+        }
+        match = BLOCK_DISABLE.exec(code);
+    }
+    return false;
+}
+exports.suppressesRuleUnderTest = suppressesRuleUnderTest;
+function codeOf(testCase) {
+    if (typeof testCase === 'string') {
+        return testCase;
+    }
+    return testCase?.code ?? '';
+}
+/**
+ * Cases that carry a blanket disable *on purpose*: they exist to prove a rule
+ * honours suppression (the #1404 import-carrier class), so the directive is the
+ * subject of the test rather than an accident.
+ *
+ * Counts are exact — not a minimum — so a newly added inert case fails here
+ * instead of shipping. Resolving #1489, which decides whether these are
+ * redundant with the guards already in each rule's `invalid` array, is what
+ * removes entries; the map should only ever shrink.
+ */
+exports.CASES_ALLOWED_TO_SUPPRESS = Object.freeze({
+    'enforce-assert-safe-object-key': 2,
+    'enforce-memoize-async': 2,
+    'enforce-memoize-getters': 2,
+    'enforce-querykey-ts': 2,
+    'enforce-stable-hash-spread-props': 2,
+    'fast-deep-equal-over-microdiff': 2,
+    'no-array-length-in-deps': 2,
+    'prefer-fragment-component': 3,
+    'prefer-usecallback-over-usememo-for-functions': 2,
+    'require-memoize-jsx-returners': 2,
+});
+/**
+ * Throws when a rule's `valid` array contains more blanket-suppressed cases than
+ * are deliberately allowed.
+ */
+function assertValidCasesCanFail(ruleName, valid) {
+    const suppressed = valid.filter((testCase) => suppressesRuleUnderTest(codeOf(testCase), ruleName));
+    const allowed = exports.CASES_ALLOWED_TO_SUPPRESS[ruleName] ?? 0;
+    if (suppressed.length <= allowed) {
+        return;
+    }
+    const excerpts = suppressed
+        .map((testCase) => codeOf(testCase).trim().split('\n')[0])
+        .map((line) => `    ${line.slice(0, 100)}`)
+        .join('\n');
+    throw new Error(`${ruleName}: ${suppressed.length} valid case(s) blanket-disable the rule ` +
+        `under test, but only ${allowed} are allowed.\n` +
+        `RuleTester registers this rule as '${ruleName}', so a block ` +
+        `/* eslint-disable */ (bare or naming it) inside the fixture silences it ` +
+        `— the case then passes for every possible implementation and asserts ` +
+        `nothing.\n` +
+        `Remove the directive (the case should pass on its own), or use a ` +
+        `line-scoped eslint-disable-next-line, which still pins the report ` +
+        `location.\nOffending case(s):\n${excerpts}`);
+}
+exports.assertValidCasesCanFail = assertValidCasesCanFail;
+//# sourceMappingURL=validCaseFalsifiability.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.41",
+  "version": "1.20.43",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",
@@ -42,7 +42,7 @@
     "resolve-comments": "./scripts/pr-resolve-comments.sh",
     "apply-comment-decisions": "./scripts/pr-apply-comment-decisions.sh",
     "docs": "./scripts/make-docs.sh && npm run update:eslint-docs",
-    "update:eslint-docs": "eslint-doc-generator --init-rule-docs",
+    "update:eslint-docs": "eslint-doc-generator --init-rule-docs || true; eslint-doc-generator",
     "build": "tsc",
     "prepare": "husky install && npm run build",
     "version": "git add -A src",