@blumintinc/eslint-plugin-blumint 1.20.0 → 1.20.1

package/lib/index.js

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

package/lib/rules/enforce-boolean-naming-prefixes.js

@@ -296,7 +296,7 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                         if (lowerCallee.startsWith('assert')) {
                             return identifierReturnsBoolean(calleeName);
                         }
-                        return isPrefixedByBooleanKeyword(calleeName, approvedPrefixesWithoutAsserts);
+                        return calleeNameImpliesBoolean(calleeName, approvedPrefixesWithoutAsserts);
                     }
                     // Default to false for other cases with || to avoid false positives
                     return false;
@@ -316,7 +316,7 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                         return identifierReturnsBoolean(calleeName);
                     }
                     // Check if the function name suggests it returns a boolean
-                    return isPrefixedByBooleanKeyword(calleeName, approvedPrefixes.filter((p) => p !== 'asserts'));
+                    return calleeNameImpliesBoolean(calleeName, approvedPrefixesWithoutAsserts);
                 }
             }
             return false;
@@ -418,7 +418,12 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
                 ];
                 const matchesPrefix = isPrefixedByBooleanKeyword(calleeName, calleeBooleanPrefixes);
                 if (matchesPrefix) {
-                    return 'boolean';
+                    // The callee's declaration outranks its name: a resolvable predicate
+                    // that demonstrably returns a verdict object, a string or a Promise
+                    // yields a non-boolean value no matter how it is named.
+                    return calleeReturnEvaluation(calleeName) === 'nonBoolean'
+                        ? 'nonBoolean'
+                        : 'boolean';
                 }
                 if (lowerCallee.startsWith('get') ||
                     lowerCallee.startsWith('fetch') ||
@@ -565,6 +570,238 @@ exports.enforceBooleanNamingPrefixes = (0, createRule_1.createRule)({
             }
             return false;
         }
+        // Predicates that call themselves (or each other) would otherwise recurse
+        // forever while their returns are classified.
+        const calleesUnderEvaluation = new Set();
+        const NON_BOOLEAN_TYPE_KEYWORDS = new Set([
+            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.TSObjectKeyword,
+            utils_1.AST_NODE_TYPES.TSVoidKeyword,
+            utils_1.AST_NODE_TYPES.TSNullKeyword,
+            utils_1.AST_NODE_TYPES.TSUndefinedKeyword,
+            utils_1.AST_NODE_TYPES.TSTypeLiteral,
+            utils_1.AST_NODE_TYPES.TSArrayType,
+            utils_1.AST_NODE_TYPES.TSTupleType,
+            utils_1.AST_NODE_TYPES.TSFunctionType,
+            utils_1.AST_NODE_TYPES.TSConstructorType,
+            utils_1.AST_NODE_TYPES.TSIntersectionType,
+            utils_1.AST_NODE_TYPES.TSTemplateLiteralType,
+            utils_1.AST_NODE_TYPES.TSMappedType,
+        ]);
+        const NON_BOOLEAN_EXPRESSION_TYPES = new Set([
+            utils_1.AST_NODE_TYPES.ObjectExpression,
+            utils_1.AST_NODE_TYPES.ArrayExpression,
+            utils_1.AST_NODE_TYPES.TemplateLiteral,
+            utils_1.AST_NODE_TYPES.TaggedTemplateExpression,
+            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.UpdateExpression,
+            utils_1.AST_NODE_TYPES.JSXElement,
+            utils_1.AST_NODE_TYPES.JSXFragment,
+        ]);
+        // `as const` preserves the operand's shape, so the assertion says nothing
+        // about booleanness and the operand must be classified instead.
+        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 (typeNode.type === utils_1.AST_NODE_TYPES.TSBooleanKeyword ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSTypePredicate) {
+                return 'boolean';
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSLiteralType) {
+                const literal = typeNode.literal;
+                return literal.type === utils_1.AST_NODE_TYPES.Literal &&
+                    typeof literal.value === 'boolean'
+                    ? 'boolean'
+                    : 'nonBoolean';
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+                const members = typeNode.types.map(classifyTypeAnnotation);
+                if (members.every((member) => member === 'boolean')) {
+                    return 'boolean';
+                }
+                // A union that mixes boolean with anything else cannot be trusted to
+                // hold a boolean; the repository prefers false negatives here.
+                return members.some((member) => member === 'nonBoolean')
+                    ? 'nonBoolean'
+                    : 'indeterminate';
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
+                if (typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    typeNode.typeName.name === 'Boolean') {
+                    return 'boolean';
+                }
+                // Named types (including `Promise<boolean>`, whose call site yields a
+                // promise rather than a boolean) are treated as non-boolean values.
+                return 'nonBoolean';
+            }
+            if (NON_BOOLEAN_TYPE_KEYWORDS.has(typeNode.type)) {
+                return 'nonBoolean';
+            }
+            // `any`, `unknown`, generics, conditional and indexed-access types carry
+            // no reliable syntactic verdict.
+            return 'indeterminate';
+        }
+        function classifyReturnExpression(expression) {
+            // A bare `return;` (or a fall-through) produces undefined.
+            if (!expression)
+                return 'nonBoolean';
+            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 === utils_1.AST_NODE_TYPES.SequenceExpression) {
+                return classifyReturnExpression(expression.expressions[expression.expressions.length - 1]);
+            }
+            if (NON_BOOLEAN_EXPRESSION_TYPES.has(expression.type)) {
+                return 'nonBoolean';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.Literal) {
+                return typeof expression.value === 'boolean' ? 'boolean' : 'nonBoolean';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.Identifier &&
+                expression.name === 'undefined') {
+                return 'nonBoolean';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.UnaryExpression) {
+                if (expression.operator === '!' || expression.operator === 'delete') {
+                    return 'boolean';
+                }
+                return 'nonBoolean';
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.BinaryExpression &&
+                !BOOLEANISH_BINARY_OPERATORS.has(expression.operator)) {
+                return 'nonBoolean';
+            }
+            // Branching expressions are classified from their branches so a mix of a
+            // boolean and an object (or two objects) is recognized as non-boolean.
+            if (expression.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
+                return combineClassifications([
+                    classifyReturnExpression(expression.consequent),
+                    classifyReturnExpression(expression.alternate),
+                ]);
+            }
+            if (expression.type === utils_1.AST_NODE_TYPES.LogicalExpression) {
+                return combineClassifications([
+                    classifyReturnExpression(expression.left),
+                    classifyReturnExpression(expression.right),
+                ]);
+            }
+            const evaluation = evaluateBooleanishExpression(expression);
+            if (evaluation === 'boolean')
+                return 'boolean';
+            if (evaluation === 'nonBoolean')
+                return 'nonBoolean';
+            return 'indeterminate';
+        }
+        function combineClassifications(classifications) {
+            if (classifications.length === 0)
+                return 'indeterminate';
+            if (classifications.every((entry) => entry === 'boolean')) {
+                return 'boolean';
+            }
+            return classifications.some((entry) => entry === 'nonBoolean')
+                ? 'nonBoolean'
+                : 'indeterminate';
+        }
+        function classifyFunctionReturn(functionLike) {
+            const annotation = functionLike.returnType?.typeAnnotation;
+            if (annotation) {
+                const classified = classifyTypeAnnotation(annotation);
+                if (classified !== 'indeterminate') {
+                    return classified;
+                }
+            }
+            // Calling an async or generator function hands back a promise or an
+            // iterator, never the boolean produced inside the body.
+            if (functionLike.async || functionLike.generator) {
+                return 'nonBoolean';
+            }
+            if (functionLike.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+                functionLike.expression) {
+                return classifyReturnExpression(functionLike.body);
+            }
+            // Overload signatures and ambient declarations expose no body to inspect.
+            if (functionLike.body?.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+                return 'indeterminate';
+            }
+            const returnArguments = collectReturnArguments(functionLike.body);
+            if (returnArguments.length === 0) {
+                return 'nonBoolean';
+            }
+            return combineClassifications(returnArguments.map(classifyReturnExpression));
+        }
+        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;
+        }
+        /**
+         * Resolve a callee identifier through the scope chain and classify the value
+         * its calls produce, without a type checker.
+         */
+        function calleeReturnEvaluation(name) {
+            if (calleesUnderEvaluation.has(name))
+                return 'indeterminate';
+            const variable = findVariableInScopes(name);
+            if (!variable || variable.defs.length === 0)
+                return 'indeterminate';
+            calleesUnderEvaluation.add(name);
+            try {
+                const classifications = [];
+                for (const definition of variable.defs) {
+                    const functionLike = functionOfDefinition(definition);
+                    // Imports, parameters and aliases hide the implementation, so the
+                    // name heuristic must keep its reach across module boundaries.
+                    if (!functionLike)
+                        return 'indeterminate';
+                    classifications.push(classifyFunctionReturn(functionLike));
+                }
+                return combineClassifications(classifications);
+            }
+            finally {
+                calleesUnderEvaluation.delete(name);
+            }
+        }
+        /**
+         * Decide whether a call to `calleeName` yields a boolean, giving the callee's
+         * resolvable declaration the final say over its name.
+         */
+        function calleeNameImpliesBoolean(calleeName, prefixes) {
+            if (!isPrefixedByBooleanKeyword(calleeName, prefixes)) {
+                return false;
+            }
+            return calleeReturnEvaluation(calleeName) !== 'nonBoolean';
+        }
         /**
          * Check if a variable is used in a while loop condition and is likely a DOM element or tree node
          * This helps identify variables like 'parent', 'element', 'node', etc. that are used

package/lib/rules/enforce-firestore-facade.js

@@ -6,6 +6,23 @@ const createRule_1 = require("../utils/createRule");
 const FIRESTORE_METHODS = new Set(['get', 'set', 'update', 'delete']);
 const COLLECTION_CONSTRUCTORS = new Set(['Set', 'Map', 'WeakSet', 'WeakMap']);
 const KNOWN_FIRESTORE_ROOTS = new Set(['db', 'firestore']);
+// The modular client SDK. DocSetter/DocSetterTransaction wrap
+// firebase-admin/firestore and cannot be imported from frontend code, so a
+// client-SDK batch or transaction has no facade to route through and must not
+// be reported.
+const CLIENT_SDK_MODULES = new Set([
+    'firebase/firestore',
+    '@firebase/firestore',
+    'firebase/firestore/lite',
+]);
+// firebase-admin/firestore exposes no `writeBatch` export at all (the admin
+// API is `db.batch()`), so this spelling identifies the client SDK with
+// certainty even when the binding's origin cannot be traced.
+const CLIENT_BATCH_FACTORY = 'writeBatch';
+// Shared spelling: the client SDK exports a free `runTransaction(db, cb)`
+// while the admin SDK only exposes the `db.runTransaction(cb)` method, so the
+// callee shape, not the name, decides which SDK a transaction belongs to.
+const TRANSACTION_RUNNER = 'runTransaction';
 const isMemberExpression = (node) => node.type === utils_1.AST_NODE_TYPES.MemberExpression;
 const isCallExpression = (node) => node.type === utils_1.AST_NODE_TYPES.CallExpression;
 const isIdentifier = (node) => node.type === utils_1.AST_NODE_TYPES.Identifier;
@@ -94,6 +111,16 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
         const firestoreTransactionVariables = new Set();
         const docSetterVariables = new Set();
         const batchManagerVariables = new Set();
+        // local name -> imported name, for bindings that come from the modular
+        // client SDK (covers `import { writeBatch as wb }` aliases).
+        const clientSdkImportedLocals = new Map();
+        // Namespace bindings for the client SDK (`import * as fs`).
+        const clientSdkNamespaceLocals = new Set();
+        // Bindings that demonstrably come from some other module, so a local
+        // helper named `writeBatch` is not mistaken for the SDK export.
+        const nonClientImportedLocals = new Set();
+        // Batches/transactions proven to originate from the client SDK.
+        const clientFirestoreVariables = new Set();
         const sourceCode = context.sourceCode;
         const clearFirestoreTrackingFor = (name) => {
             firestoreDocRefVariables.delete(name);
@@ -102,7 +129,36 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             firestoreTransactionVariables.delete(name);
             docSetterVariables.delete(name);
             batchManagerVariables.delete(name);
+            clientFirestoreVariables.delete(name);
         };
+        const isClientSdkExportReference = (node, exportName, allowUntracedSpelling) => {
+            const callee = unwrapTSAsExpression(node);
+            if (isIdentifier(callee)) {
+                if (clientSdkImportedLocals.get(callee.name) === exportName) {
+                    return true;
+                }
+                return (allowUntracedSpelling &&
+                    callee.name === exportName &&
+                    !nonClientImportedLocals.has(callee.name));
+            }
+            if (isMemberExpression(callee) &&
+                isIdentifier(callee.property) &&
+                callee.property.name === exportName) {
+                const base = getLeftmostIdentifier(callee.object);
+                return !!base && clientSdkNamespaceLocals.has(base.name);
+            }
+            return false;
+        };
+        // `writeBatch(firestore)` / `fs.writeBatch(firestore)` — client SDK only.
+        const isClientBatchFactoryCall = (node) => {
+            const candidate = unwrapTSAsExpression(node);
+            return (isCallExpression(candidate) &&
+                isClientSdkExportReference(candidate.callee, CLIENT_BATCH_FACTORY, true));
+        };
+        // `runTransaction(firestore, cb)` — the free-function form only exists in
+        // the client SDK. The name alone is not enough, because a project helper
+        // could share it, so the binding must be traced back to the SDK.
+        const isClientTransactionRunnerCall = (node) => isClientSdkExportReference(node.callee, TRANSACTION_RUNNER, false);
         const recordFirestoreVariable = (varName, expression) => {
             const target = unwrapTSAsExpression(expression);
             if (target.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
@@ -131,6 +187,10 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
                 batchManagerVariables.add(varName);
                 return true;
             }
+            if (isClientBatchFactoryCall(target)) {
+                clientFirestoreVariables.add(varName);
+                return true;
+            }
             if (isFirestoreDocumentReference(target)) {
                 firestoreDocRefVariables.add(varName);
                 return true;
@@ -143,8 +203,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
                 isMemberExpression(target.callee) &&
                 isIdentifier(target.callee.property) &&
                 target.callee.property.name === 'batch' &&
-                isIdentifier(target.callee.object) &&
-                target.callee.object.name === 'db') {
+                isFirestoreRoot(target.callee.object, firestoreCollectionVariables, firestoreDocRefVariables)) {
                 firestoreBatchVariables.add(varName);
                 return true;
             }
@@ -214,6 +273,110 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             clearFirestoreTrackingFor(varName);
             recordFirestoreVariable(varName, right);
         };
+        const recordImportBinding = (localName, importedName, isClientSource) => {
+            if (!isClientSource) {
+                nonClientImportedLocals.add(localName);
+                return;
+            }
+            if (importedName === null) {
+                clientSdkNamespaceLocals.add(localName);
+                return;
+            }
+            clientSdkImportedLocals.set(localName, importedName);
+        };
+        const recordImportPattern = (pattern, source) => {
+            const isClientSource = CLIENT_SDK_MODULES.has(source);
+            if (pattern.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
+                for (const property of pattern.properties) {
+                    if (property.type !== utils_1.AST_NODE_TYPES.Property)
+                        continue;
+                    if (!isIdentifier(property.key) || !isIdentifier(property.value)) {
+                        continue;
+                    }
+                    recordImportBinding(property.value.name, property.key.name, isClientSource);
+                }
+                return;
+            }
+            if (isIdentifier(pattern)) {
+                recordImportBinding(pattern.name, null, isClientSource);
+            }
+        };
+        const getImportExpressionSource = (node) => {
+            const expression = unwrapTSAsExpression(node);
+            if (expression.type !== utils_1.AST_NODE_TYPES.ImportExpression)
+                return null;
+            const source = expression.source;
+            return source.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof source.value === 'string'
+                ? source.value
+                : null;
+        };
+        const isPromiseAllCall = (node) => isCallExpression(node) &&
+            isMemberExpression(node.callee) &&
+            isIdentifier(node.callee.object) &&
+            node.callee.object.name === 'Promise' &&
+            isIdentifier(node.callee.property) &&
+            node.callee.property.name === 'all';
+        // Frontend Firebase access is required to be dynamically imported, so
+        // `await import(...)` — including the correlated `Promise.all` array form —
+        // is the ordinary client-SDK call site rather than an edge case.
+        const recordDynamicImportBindings = (node) => {
+            const init = node.init;
+            if (!init || init.type !== utils_1.AST_NODE_TYPES.AwaitExpression)
+                return;
+            const awaited = unwrapTSAsExpression(init.argument);
+            const directSource = getImportExpressionSource(awaited);
+            if (directSource !== null) {
+                recordImportPattern(node.id, directSource);
+                return;
+            }
+            if (!isPromiseAllCall(awaited) ||
+                node.id.type !== utils_1.AST_NODE_TYPES.ArrayPattern) {
+                return;
+            }
+            const promises = awaited.arguments[0];
+            if (!promises || promises.type !== utils_1.AST_NODE_TYPES.ArrayExpression)
+                return;
+            node.id.elements.forEach((element, index) => {
+                const promise = promises.elements[index];
+                if (!element || !promise)
+                    return;
+                const source = getImportExpressionSource(promise);
+                if (source === null)
+                    return;
+                recordImportPattern(element, source);
+            });
+        };
+        const getCallbackFirstParam = (node) => {
+            const callback = node.arguments.find((argument) => argument.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                argument.type === utils_1.AST_NODE_TYPES.FunctionExpression);
+            const param = callback?.params[0];
+            return param && isIdentifier(param) ? param : null;
+        };
+        // Binds the transaction callback parameter to the SDK that produced it, so
+        // classification rests on origin rather than on the parameter being
+        // spelled `transaction`.
+        const recordTransactionCallback = (node) => {
+            if (isClientTransactionRunnerCall(node)) {
+                const param = getCallbackFirstParam(node);
+                if (param) {
+                    clearFirestoreTrackingFor(param.name);
+                    clientFirestoreVariables.add(param.name);
+                }
+                return;
+            }
+            const callee = node.callee;
+            if (!isMemberExpression(callee) ||
+                !isIdentifier(callee.property) ||
+                callee.property.name !== TRANSACTION_RUNNER ||
+                !isFirestoreRoot(callee.object, firestoreCollectionVariables, firestoreDocRefVariables)) {
+                return;
+            }
+            const param = getCallbackFirstParam(node);
+            if (param && !clientFirestoreVariables.has(param.name)) {
+                firestoreTransactionVariables.add(param.name);
+            }
+        };
         const isRealtimeDbRefAssignment = (node) => {
             if (node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator)
                 return false;
@@ -282,7 +445,8 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             const object = node.callee.object;
             if (isIdentifier(object)) {
                 const name = object.name;
-                if (docSetterVariables.has(name) ||
+                if (clientFirestoreVariables.has(name) ||
+                    docSetterVariables.has(name) ||
                     batchManagerVariables.has(name) ||
                     realtimeDbRefVariables.has(name) ||
                     realtimeDbChildVariables.has(name) ||
@@ -304,7 +468,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
                 }
                 return false;
             }
-            if (isRealtimeDbReference(object)) {
+            if (isRealtimeDbReference(object) || isClientBatchFactoryCall(object)) {
                 return false;
             }
             if (isFirestoreDocumentReference(object)) {
@@ -374,7 +538,19 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
             });
         };
         return {
+            ImportDeclaration(node) {
+                const source = node.source.value;
+                const isClientSource = typeof source === 'string' && CLIENT_SDK_MODULES.has(source);
+                for (const specifier of node.specifiers) {
+                    if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                        recordImportBinding(specifier.local.name, specifier.imported.name, isClientSource);
+                        continue;
+                    }
+                    recordImportBinding(specifier.local.name, null, isClientSource);
+                }
+            },
             VariableDeclarator(node) {
+                recordDynamicImportBindings(node);
                 isRealtimeDbRefAssignment(node);
                 isCollectionObjectAssignment(node);
                 isFirestoreAssignment(node);
@@ -383,6 +559,7 @@ exports.enforceFirestoreFacade = (0, createRule_1.createRule)({
                 handleAssignmentExpression(node);
             },
             CallExpression(node) {
+                recordTransactionCallback(node);
                 if (!isFirestoreMethodCall(node))
                     return;
                 const callee = node.callee;

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.1",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,35 @@
 [
+  {
+    "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",