@blumintinc/eslint-plugin-blumint 1.20.0 → 1.20.2

package/lib/rules/react-memoize-literals.js

@@ -265,14 +265,95 @@ function getFunctionName(fn) {
     }
     return findNameInAncestors(parent);
 }
+/**
+ * Locates the ancestor that supplies a function's name, mirroring the walk
+ * `getFunctionName` performs through `findNameInAncestors` but yielding the
+ * NODE instead of the string, so callers can tell an object-property key apart
+ * from a variable or assignment binding.
+ */
+function findNamingNode(fn) {
+    let current = fn.parent;
+    while (current) {
+        if (getNameFromNode(current)) {
+            return current;
+        }
+        if (!isTransparentNode(current)) {
+            return null;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * True when a function expression is passed directly as an argument to a call
+ * (after unwrapping assertion/parenthesis wrappers). Function declarations are
+ * excluded because a declaration is a statement, never an argument.
+ */
+function isCallbackArgument(fn) {
+    if (fn.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+        return false;
+    }
+    let parent = fn.parent;
+    while (parent && isExpressionWrapper(parent)) {
+        parent = parent.parent;
+    }
+    return (parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        parent.arguments.some((arg) => unwrapNestedExpressions(arg) === fn));
+}
+/**
+ * True when a function's only claim to component/hook status is an object
+ * property key, and that object is assembled inside an anonymous callback which
+ * is itself neither a component nor a hook — the shape of a module factory
+ * (`jest.mock('m', () => ({ useThing: … }))`,
+ * `registerModule('m', () => ({ useThing: … }))`). Such a factory builds a
+ * value; React never renders it, so a `use*`/PascalCase key inside it names a
+ * member of that value rather than a render body. This is the same reasoning
+ * that makes `isComponentName` reject SCREAMING_SNAKE_CASE and that makes
+ * `isIterationMethodCallback` exempt discarded callbacks: a name match in a
+ * non-render context is not a render body.
+ *
+ * Requiring the enclosing function to be an anonymous CALL ARGUMENT is the
+ * deliberate narrowing that preserves genuine hook factories
+ * (`export function createApi(client) { return { useUser: … }; }`), whose
+ * returned hook really is consumed by React and really does need referential
+ * stability.
+ */
+function isFactoryObjectMember(fn) {
+    const namingNode = findNamingNode(fn);
+    if (!namingNode || namingNode.type !== utils_1.AST_NODE_TYPES.Property) {
+        return false;
+    }
+    const objectLiteral = namingNode.parent;
+    if (!objectLiteral ||
+        objectLiteral.type !== utils_1.AST_NODE_TYPES.ObjectExpression) {
+        return false;
+    }
+    let current = objectLiteral.parent;
+    while (current) {
+        if (isFunctionNode(current)) {
+            return isCallbackArgument(current) && !isComponentOrHookFunction(current);
+        }
+        current = current.parent;
+    }
+    return false;
+}
 /**
  * Checks whether a function should be treated as a React component or hook
  * based on naming conventions. Enables the rule to limit reports to user-facing
  * components and hooks rather than arbitrary functions.
+ *
+ * The name match is disqualified for members of a factory-built object (see
+ * `isFactoryObjectMember`). Disqualifying at the classifier — rather than
+ * skipping the report — keeps `findEnclosingComponentOrHook` walking outward,
+ * so a literal inside a factory nested in a real component is still attributed
+ * to that component.
  */
 function isComponentOrHookFunction(fn) {
     const name = getFunctionName(fn);
-    return isComponentName(name) || isHookName(name);
+    if (!isComponentName(name) && !isHookName(name)) {
+        return false;
+    }
+    return !isFactoryObjectMember(fn);
 }
 /**
  * Checks whether a function node represents a hook by name.
@@ -329,6 +410,54 @@ function getLiteralDescriptor(node) {
     const descriptor = LITERAL_DESCRIPTOR_BY_TYPE[node.type] ?? null;
     return descriptor;
 }
+/**
+ * Jest APIs whose second argument is a module factory: a function executed to
+ * BUILD a replacement module, hoisted above imports by `babel-plugin-jest-hoist`.
+ */
+const JEST_MOCK_FACTORY_METHODS = new Set(['mock', 'doMock', 'setMock']);
+/**
+ * True when `node` sits anywhere inside a jest module factory
+ * (`jest.mock('m', () => ({ … }))`). A factory is executed to build a
+ * replacement module, never rendered by React, so the rule's "on each render"
+ * premise does not hold for the test doubles it defines.
+ *
+ * Beyond the premise, neither remediation the rule advises is legal here:
+ * `babel-plugin-jest-hoist` rejects every out-of-scope reference inside a
+ * factory except `mock`-prefixed names, so `useMemo` cannot be imported or
+ * called, and hoisting to a module constant changes behaviour because the
+ * double must rebuild per call for tests to vary its result. This mirrors
+ * `isInsideIterationMethodCallback`, which exempts literals whose remediation
+ * is unfollowable at the literal.
+ *
+ * The walk is lexical, so a hook declared outside the factory in the same file
+ * stays analyzed.
+ */
+function isInsideJestMockFactory(node) {
+    let current = node;
+    while (current) {
+        if (isFunctionNode(current) &&
+            current.type !== utils_1.AST_NODE_TYPES.FunctionDeclaration) {
+            let parent = current.parent;
+            while (parent && isExpressionWrapper(parent)) {
+                parent = parent.parent;
+            }
+            if (parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                parent.arguments.some((arg) => unwrapNestedExpressions(arg) === current)) {
+                const { callee } = parent;
+                if (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 &&
+                    JEST_MOCK_FACTORY_METHODS.has(callee.property.name)) {
+                    return true;
+                }
+            }
+        }
+        current = current.parent;
+    }
+    return false;
+}
 /**
  * Finds the nearest ancestor function considered a React component or hook.
  * @param node Starting node for the search.
@@ -862,6 +991,329 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             }
             return usages.every((ref) => isStyleJSXAttributeValue(ref.identifier));
         }
+        const PRIMITIVE_TYPE_KEYWORDS = new Set([
+            utils_1.AST_NODE_TYPES.TSBooleanKeyword,
+            utils_1.AST_NODE_TYPES.TSStringKeyword,
+            utils_1.AST_NODE_TYPES.TSNumberKeyword,
+            utils_1.AST_NODE_TYPES.TSBigIntKeyword,
+            utils_1.AST_NODE_TYPES.TSSymbolKeyword,
+            utils_1.AST_NODE_TYPES.TSVoidKeyword,
+            utils_1.AST_NODE_TYPES.TSNullKeyword,
+            utils_1.AST_NODE_TYPES.TSUndefinedKeyword,
+            utils_1.AST_NODE_TYPES.TSNeverKeyword,
+            utils_1.AST_NODE_TYPES.TSTypePredicate,
+            utils_1.AST_NODE_TYPES.TSTemplateLiteralType,
+        ]);
+        const NON_PRIMITIVE_EXPRESSION_TYPES = new Set([
+            utils_1.AST_NODE_TYPES.ObjectExpression,
+            utils_1.AST_NODE_TYPES.ArrayExpression,
+            utils_1.AST_NODE_TYPES.ArrowFunctionExpression,
+            utils_1.AST_NODE_TYPES.FunctionExpression,
+            utils_1.AST_NODE_TYPES.ClassExpression,
+            utils_1.AST_NODE_TYPES.NewExpression,
+            utils_1.AST_NODE_TYPES.JSXElement,
+            utils_1.AST_NODE_TYPES.JSXFragment,
+        ]);
+        const COMPARISONISH_BINARY_OPERATORS = new Set([
+            '===',
+            '!==',
+            '==',
+            '!=',
+            '<',
+            '>',
+            '<=',
+            '>=',
+            'in',
+            'instanceof',
+        ]);
+        /**
+         * Innermost scope containing `node`. Resolved from the source code rather
+         * than `context.getScope()` because the latter is deprecated in ESLint 9
+         * and reports the traversal position instead of the node's own scope.
+         */
+        function scopeOf(node) {
+            const sourceCode = context.getSourceCode();
+            return sourceCode.getScope ? sourceCode.getScope(node) : null;
+        }
+        function findVariableInScopes(name, startScope) {
+            let currentScope = startScope;
+            while (currentScope) {
+                const variable = currentScope.variables.find((v) => v.name === name);
+                if (variable)
+                    return variable;
+                currentScope = currentScope.upper;
+            }
+            return undefined;
+        }
+        function isConstAssertion(typeNode) {
+            return (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+                typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+                typeNode.typeName.name === 'const');
+        }
+        function classifyTypeAnnotation(typeNode) {
+            if (PRIMITIVE_TYPE_KEYWORDS.has(typeNode.type)) {
+                return 'primitive';
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSLiteralType) {
+                return 'primitive';
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+                const members = typeNode.types.map(classifyTypeAnnotation);
+                if (members.every((m) => m === 'primitive'))
+                    return 'primitive';
+                return members.some((m) => m === 'nonPrimitive')
+                    ? 'nonPrimitive'
+                    : 'indeterminate';
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeLiteral ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSArrayType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSTupleType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSFunctionType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSConstructorType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSObjectKeyword ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSIntersectionType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSMappedType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+                return 'nonPrimitive';
+            }
+            return 'indeterminate';
+        }
+        function combineReturnEvaluations(entries) {
+            if (entries.length === 0)
+                return 'indeterminate';
+            if (entries.every((e) => e === 'primitive'))
+                return 'primitive';
+            return entries.some((e) => e === 'nonPrimitive')
+                ? 'nonPrimitive'
+                : 'indeterminate';
+        }
+        function classifyReturnExpression(expression) {
+            if (!expression)
+                return 'primitive';
+            if (expression.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+                expression.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression ||
+                expression.type === utils_1.AST_NODE_TYPES.TSTypeAssertion) {
+                const annotation = expression.typeAnnotation;
+                if (annotation && !isConstAssertion(annotation)) {
+                    const classified = classifyTypeAnnotation(annotation);
+                    if (classified !== 'indeterminate')
+                        return classified;
+                }
+                return classifyReturnExpression(expression.expression);
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.ChainExpression ||
+                expression.type === utils_1.AST_NODE_TYPES.TSNonNullExpression) {
+                return classifyReturnExpression(expression.expression);
+            }
+            if (expression.type === PARENTHESIZED_EXPRESSION_TYPE) {
+                return classifyReturnExpression(expression
+                    .expression);
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.SequenceExpression) {
+                return classifyReturnExpression(expression.expressions[expression.expressions.length - 1]);
+            }
+            if (NON_PRIMITIVE_EXPRESSION_TYPES.has(expression.type)) {
+                return 'nonPrimitive';
+            }
+            // Literals, template literals and update expressions are primitives by
+            // construction.
+            if (expression.type === utils_1.AST_NODE_TYPES.Literal ||
+                expression.type === utils_1.AST_NODE_TYPES.TemplateLiteral ||
+                expression.type === utils_1.AST_NODE_TYPES.UpdateExpression) {
+                return 'primitive';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.Identifier &&
+                expression.name === 'undefined') {
+                return 'primitive';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.UnaryExpression) {
+                // `!`, `typeof`, `void`, `-`, `+`, `~`, `delete` all yield primitives.
+                return 'primitive';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.BinaryExpression) {
+                return COMPARISONISH_BINARY_OPERATORS.has(expression.operator)
+                    ? 'primitive'
+                    : 'indeterminate';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
+                return combineReturnEvaluations([
+                    classifyReturnExpression(expression.consequent),
+                    classifyReturnExpression(expression.alternate),
+                ]);
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.LogicalExpression) {
+                return combineReturnEvaluations([
+                    classifyReturnExpression(expression.left),
+                    classifyReturnExpression(expression.right),
+                ]);
+            }
+            return 'indeterminate';
+        }
+        function collectReturnArgumentsOf(body) {
+            const found = [];
+            const walk = (node) => {
+                if (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                    node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                    node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                    return;
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
+                    found.push(node.argument ?? null);
+                    return;
+                }
+                for (const key of Object.keys(node)) {
+                    if (key === 'parent')
+                        continue;
+                    const value = node[key];
+                    if (Array.isArray(value)) {
+                        for (const entry of value) {
+                            if (ASTHelpers_1.ASTHelpers.isNode(entry))
+                                walk(entry);
+                        }
+                    }
+                    else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                        walk(value);
+                    }
+                }
+            };
+            for (const statement of body.body) {
+                walk(statement);
+            }
+            return found;
+        }
+        function classifyFunctionReturn(functionLike) {
+            const annotation = functionLike.returnType?.typeAnnotation;
+            if (annotation) {
+                const classified = classifyTypeAnnotation(annotation);
+                if (classified !== 'indeterminate')
+                    return classified;
+            }
+            // Async/generator calls hand back a promise or an iterator object.
+            if (functionLike.async || functionLike.generator) {
+                return 'nonPrimitive';
+            }
+            if (functionLike.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+                functionLike.expression) {
+                return classifyReturnExpression(functionLike.body);
+            }
+            if (functionLike.body?.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+                return 'indeterminate';
+            }
+            const returnArguments = collectReturnArgumentsOf(functionLike.body);
+            if (returnArguments.length === 0) {
+                // Falls off the end: yields undefined.
+                return 'primitive';
+            }
+            const combined = combineReturnEvaluations(returnArguments.map((arg) => classifyReturnExpression(arg)));
+            // An unclassifiable return is still safe when no return expression can
+            // syntactically reach a whole-parameter binding: the argument's reference
+            // then has no path out through the result.
+            if (combined === 'indeterminate' &&
+                !returnArguments.some((arg) => expressionReachesParameters(arg, functionLike))) {
+                return 'primitive';
+            }
+            return combined;
+        }
+        function parameterNamesOf(functionLike) {
+            // Only a whole-parameter binding can carry the argument object's identity
+            // out. A destructured binding holds a PROPERTY of the argument, so
+            // returning it never exposes the literal's own identity.
+            const names = new Set();
+            const unwrap = (node) => {
+                if (node.type === utils_1.AST_NODE_TYPES.AssignmentPattern) {
+                    return unwrap(node.left);
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.RestElement) {
+                    return unwrap(node.argument);
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.TSParameterProperty) {
+                    return unwrap(node.parameter);
+                }
+                return node;
+            };
+            for (const param of functionLike.params) {
+                const bare = unwrap(param);
+                if (bare.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    names.add(bare.name);
+                }
+            }
+            return names;
+        }
+        function expressionReachesParameters(expression, functionLike) {
+            if (!expression)
+                return false;
+            const names = parameterNamesOf(functionLike);
+            let reaches = false;
+            const walk = (node) => {
+                if (reaches)
+                    return;
+                if (node.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    // `arguments` exposes the raw argument list, so it can carry the
+                    // literal's identity out even when every parameter is destructured.
+                    (names.has(node.name) || node.name === 'arguments')) {
+                    reaches = true;
+                    return;
+                }
+                for (const key of Object.keys(node)) {
+                    if (key === 'parent')
+                        continue;
+                    const value = node[key];
+                    if (Array.isArray(value)) {
+                        for (const entry of value) {
+                            if (ASTHelpers_1.ASTHelpers.isNode(entry))
+                                walk(entry);
+                        }
+                    }
+                    else if (ASTHelpers_1.ASTHelpers.isNode(value)) {
+                        walk(value);
+                    }
+                }
+            };
+            walk(expression);
+            return reaches;
+        }
+        function functionOfDefinition(definition) {
+            if (definition.type === 'FunctionName') {
+                return definition.node;
+            }
+            if (definition.type === 'Variable') {
+                const init = definition.node
+                    .init;
+                if (init?.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                    init?.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+                    return init;
+                }
+            }
+            return undefined;
+        }
+        /**
+         * True when every declaration bound to `calleeName` provably returns a
+         * primitive, so invoking it cannot hand an argument's reference back.
+         *
+         * The analysis never follows a call inside the callee's body — a returned
+         * CallExpression classifies as indeterminate — so it terminates on
+         * self-recursive and mutually recursive callees without a re-entrancy guard.
+         */
+        function calleeReturnIsPrimitive(calleeName, startScope) {
+            const variable = findVariableInScopes(calleeName, startScope);
+            if (!variable || variable.defs.length === 0)
+                return false;
+            // A binding written again after initialization may hold a different
+            // function by the time the call runs, so the declaration on record no
+            // longer proves anything about the value actually invoked.
+            if (variable.references.some((ref) => ref.isWrite() && !ref.init)) {
+                return false;
+            }
+            const classifications = [];
+            for (const definition of variable.defs) {
+                const functionLike = functionOfDefinition(definition);
+                // Imports, parameters and aliases hide the implementation.
+                if (!functionLike)
+                    return false;
+                classifications.push(classifyFunctionReturn(functionLike));
+            }
+            return combineReturnEvaluations(classifications) === 'primitive';
+        }
         /**
          * True when `expr` — a plain function call's result, or a reference to the
          * variable holding that result — is consumed only for its primitive value,
@@ -931,14 +1383,22 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             }
         }
         /**
-         * True when the literal is a direct argument of a plain function call whose
-         * result is only ever consumed primitively (see isPrimitivelyConsumed). In
-         * that case the literal's identity provably never reaches a memoization
-         * boundary — it is neither a JSX prop, nor a hook dependency, nor captured
-         * by an effect — so re-creating it each render costs nothing and memoizing
-         * it buys nothing. The callee must be a plain Identifier: member calls
-         * (`obj.method({...})`) are excluded because the receiver could retain the
-         * reference, and this keeps the guard to plain, non-hook synchronous calls.
+         * True when the literal is a direct argument of a plain function call and
+         * its identity provably cannot reach a memoization boundary — it is then
+         * neither a JSX prop, nor a hook dependency, nor captured by an effect, so
+         * re-creating it each render costs nothing and memoizing it buys nothing.
+         *
+         * Two independent conditions each suffice. The result is only ever consumed
+         * primitively (see isPrimitivelyConsumed), which reasons from the CALL SITE.
+         * Or the callee is locally declared and cannot hand the reference back (see
+         * calleeReturnIsPrimitive), which reasons from the CALLEE. The call-site
+         * condition covers callees that are imported or otherwise opaque; the callee
+         * condition covers results consumed in positions no whitelist can prove
+         * primitive, such as an object member or a hook dependency array.
+         *
+         * The callee must be a plain Identifier: member calls (`obj.method({...})`)
+         * are excluded because the receiver could retain the reference, and this
+         * keeps the guard to plain, non-hook synchronous calls.
          */
         function isPrimitiveConsumedCallArgument(node) {
             // Walk up through transparent wrappers to the position the literal
@@ -962,7 +1422,12 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             if (parent.callee.type !== utils_1.AST_NODE_TYPES.Identifier) {
                 return false;
             }
-            return isPrimitivelyConsumed(parent);
+            // Either sufficient condition exempts: a provably primitive consumption
+            // site, or a callee that cannot hand the reference back.
+            if (isPrimitivelyConsumed(parent)) {
+                return true;
+            }
+            return calleeReturnIsPrimitive(parent.callee.name, scopeOf(node));
         }
         function reportLiteral(node) {
             const descriptor = getLiteralDescriptor(node);
@@ -977,6 +1442,12 @@ exports.reactMemoizeLiterals = (0, createRule_1.createRule)({
             if (isTerminalUsage(node)) {
                 return;
             }
+            // A jest module factory builds a replacement module; React never renders
+            // it, and jest's out-of-scope-variable restriction makes the rule's own
+            // remediations illegal inside it.
+            if (isInsideJestMockFactory(node)) {
+                return;
+            }
             // A function literal passed directly as the callback to an Array
             // iteration method (.map/.filter/.reduce/.forEach/...) is invoked
             // synchronously during render and then discarded, so its identity is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.0",
+  "version": "1.20.2",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,49 @@
 [
+  {
+    "version": "1.20.2",
+    "date": "2026-07-25T02:42:18.863Z",
+    "rules": [
+      {
+        "name": "no-unnecessary-verb-suffix",
+        "changeType": "fix",
+        "issues": [
+          1350
+        ],
+        "summary": "exempt member names dictated by a declared contract (closes #1350)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.1",
+    "date": "2026-07-24T22:02:37.444Z",
+    "rules": [
+      {
+        "name": "enforce-boolean-naming-prefixes",
+        "changeType": "fix",
+        "issues": [
+          1346
+        ],
+        "summary": "skip boolean-prefixed callees whose return is demonstrably non-boolean (closes #1346)"
+      },
+      {
+        "name": "enforce-firestore-facade",
+        "changeType": "fix",
+        "issues": [
+          1348
+        ],
+        "summary": "classify batches by import origin, not variable name (closes #1348)"
+      },
+      {
+        "name": "react-memoize-literals",
+        "changeType": "fix",
+        "issues": [
+          1347,
+          1349
+        ],
+        "summary": "exempt argument literals whose callee cannot return their reference (closes #1349); skip hook names resolved inside jest.mock and factory callbacks (closes #1347)"
+      }
+    ]
+  },
   {
     "version": "1.20.0",
     "date": "2026-07-24T15:36:40.953Z",