@blumintinc/eslint-plugin-blumint 1.20.41 → 1.20.42

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.42',
     },
     parseOptions: {
         ecmaVersion: 2020,

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/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.42",
   "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",

package/release-manifest.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "1.20.42",
+    "date": "2026-07-31T04:16:11.179Z",
+    "rules": [
+      {
+        "name": "logical-top-to-bottom-grouping",
+        "changeType": "fix",
+        "issues": [
+          1493
+        ],
+        "summary": "stop hoisting effects above captured state (closes #1493)"
+      },
+      {
+        "name": "memo-nested-react-components",
+        "changeType": "fix",
+        "issues": [
+          1491,
+          1494,
+          1495
+        ],
+        "summary": "exempt stubs inside test helper functions (closes #1495); exempt components defined in test bodies (closes #1494); exempt components defined in jest.mock factories (closes #1491)"
+      }
+    ]
+  },
   {
     "version": "1.20.41",
     "date": "2026-07-31T01:39:15.741Z",