@blumintinc/eslint-plugin-blumint 1.20.115 → 1.20.116

package/lib/index.js

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

package/lib/rules/enforce-firestore-doc-ref-generic.js

@@ -11,6 +11,33 @@ exports.enforceFirestoreDocRefGeneric = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+/** The Firestore reference types that carry a document-shape generic. */
+const REFERENCE_TYPE_NAMES = new Set([
+    'DocumentReference',
+    'CollectionReference',
+    'CollectionGroup',
+]);
+/**
+ * The final segment of a type reference's name, so `FirebaseFirestore.
+ * DocumentReference` is recognized as the same type as `DocumentReference`.
+ *
+ * The rightmost segment is the right granularity because the namespace is
+ * arbitrary — `FirebaseFirestore.`, `admin.firestore.` and any
+ * `import * as fs from 'firebase-admin/firestore'` alias all name these types —
+ * while the names themselves are specific enough that an unrelated module's
+ * `DocumentReference` is not a realistic collision.
+ */
+const referenceTypeNameOf = (typeName) => {
+    if (typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return REFERENCE_TYPE_NAMES.has(typeName.name) ? typeName.name : undefined;
+    }
+    if (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName &&
+        typeName.right.type === utils_1.AST_NODE_TYPES.Identifier &&
+        REFERENCE_TYPE_NAMES.has(typeName.right.name)) {
+        return typeName.right.name;
+    }
+    return undefined;
+};
 /**
  * @type {import('eslint').Rule.RuleModule}
  */
@@ -655,11 +682,7 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
         }
         function hasCollectionReferenceType(typeNode) {
             if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
-                ((typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    typeNode.typeName.name === 'CollectionReference') ||
-                    (typeNode.typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName &&
-                        typeNode.typeName.right.type === utils_1.AST_NODE_TYPES.Identifier &&
-                        typeNode.typeName.right.name === 'CollectionReference')) &&
+                referenceTypeNameOf(typeNode.typeName) === 'CollectionReference' &&
                 typeNode.typeParameters &&
                 typeNode.typeParameters.params.length > 0) {
                 return true;
@@ -860,11 +883,8 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
         }
         return {
             TSTypeReference(node) {
-                if (node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    (node.typeName.name === 'DocumentReference' ||
-                        node.typeName.name === 'CollectionReference' ||
-                        node.typeName.name === 'CollectionGroup')) {
-                    const typeName = node.typeName.name;
+                const typeName = referenceTypeNameOf(node.typeName);
+                if (typeName) {
                     // Check if generic type argument is missing
                     if (!node.typeParameters || node.typeParameters.params.length === 0) {
                         context.report({

package/lib/rules/extract-global-constants.js

@@ -186,10 +186,15 @@ exports.extractGlobalConstants = (0, createRule_1.createRule)({
                 }
             },
             FunctionDeclaration(node) {
-                if (node.parent &&
-                    (node.parent.type === 'FunctionDeclaration' ||
-                        node.parent.type === 'FunctionExpression' ||
-                        node.parent.type === 'ArrowFunctionExpression')) {
+                /**
+                 * The enclosing function, not the immediate parent. A
+                 * FunctionDeclaration is a Statement, so its parent is always a
+                 * statement container — Program, BlockStatement, StaticBlock,
+                 * SwitchCase, an export, an IfStatement. It is never a direct child of
+                 * a function node, which made the previous `node.parent.type` check
+                 * unsatisfiable and this whole branch dead.
+                 */
+                if (node.parent && isInsideFunction(node.parent)) {
                     const scope = context.getScope();
                     const hasDependencies = ASTHelpers_1.ASTHelpers.blockIncludesIdentifier(node.body);
                     if (!hasDependencies && scope.type === 'function') {

package/lib/rules/prefer-batch-operations.js

@@ -261,17 +261,45 @@ function isMapInstance(node) {
     }
     return false;
 }
+/** Statements a declaration can be a direct child of, innermost outward. */
+function statementsOf(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Program:
+        case utils_1.AST_NODE_TYPES.BlockStatement:
+        case utils_1.AST_NODE_TYPES.TSModuleBlock:
+        case utils_1.AST_NODE_TYPES.StaticBlock:
+            return node.body;
+        case utils_1.AST_NODE_TYPES.SwitchCase:
+            return node.consequent;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Lexical lookup of a local declaration, innermost scope outward.
+ *
+ * The walk used to climb the parent chain but only inspect `Program.body`,
+ * which meant a setter constructed inside the function that uses it — how
+ * essentially all production code is written — was never found, so the caller
+ * bailed and the rule reported nothing. Every enclosing statement container is
+ * searched instead, and the first match wins, which is what shadowing requires.
+ */
 function findVariableDeclaration(node, varName) {
     let current = node;
     while (current) {
-        if (current.type === utils_1.AST_NODE_TYPES.Program) {
-            for (const statement of current.body) {
-                if (statement.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
-                    for (const decl of statement.declarations) {
-                        if (decl.id.type === utils_1.AST_NODE_TYPES.Identifier &&
-                            decl.id.name === varName) {
-                            return decl;
-                        }
+        const statements = statementsOf(current);
+        if (statements) {
+            for (const statement of statements) {
+                const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                    statement.declaration
+                    ? statement.declaration
+                    : statement;
+                if (declaration.type !== utils_1.AST_NODE_TYPES.VariableDeclaration)
+                    continue;
+                for (const decl of declaration.declarations) {
+                    if (decl.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        decl.id.name === varName) {
+                        return decl;
                     }
                 }
             }
@@ -403,8 +431,19 @@ exports.preferBatchOperations = (0, createRule_1.createRule)({
                             });
                         }
                     }
-                    // For array methods, report on the first occurrence
-                    else if (loopInfo.isArrayMethod) {
+                    /**
+                     * For array methods, report on the first occurrence — one syntactic
+                     * call inside a `map` callback still runs once per element.
+                     *
+                     * A direct `Promise.all([...])` is not that: its elements are written
+                     * out, so a lone `set()` is a single write and the docs call it
+                     * valid. `findLoopNode` stamps `isArrayMethod: 'map'` onto the
+                     * Promise.all result, which used to route it here and report on the
+                     * first call — and, by adding the node to `reportedLoops`, made the
+                     * deferred second-occurrence branch below unreachable for every
+                     * input. Excluding it hands the decision back to that branch.
+                     */
+                    else if (loopInfo.isArrayMethod && !loopInfo.isPromiseAll) {
                         if (!reportedLoops.has(loopInfo.node)) {
                             reportedLoops.add(loopInfo.node);
                             context.report({

package/lib/rules/require-hooks-default-params.js

@@ -22,6 +22,50 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
         function isHookName(name) {
             return name.startsWith('use') && name[3]?.toUpperCase() === name[3];
         }
+        /** The declaration a statement introduces, looking through `export`. */
+        function typeDeclarationNamed(statement, name) {
+            const declared = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                statement.declaration
+                ? statement.declaration
+                : statement;
+            if ((declared.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+                declared.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) &&
+                declared.id.name === name) {
+                return declared;
+            }
+            return undefined;
+        }
+        /**
+         * Lexical resolution of a type name, innermost scope outward.
+         *
+         * `context.getScope()` returns the scope of the node being visited and
+         * `scope.variables` is own-scope-only, so a type declared anywhere above
+         * the hook is invisible to it — and when a *value* of the same name is
+         * bound nearby, the lookup succeeds with a non-type definition and the
+         * whole check is abandoned. Walking the enclosing statement containers
+         * answers the question the rule actually asks, and a name that resolves to
+         * something other than a type declaration simply keeps searching.
+         */
+        function resolveTypeDeclaration(from, name) {
+            let current = from;
+            while (current) {
+                const body = current.type === utils_1.AST_NODE_TYPES.Program ||
+                    current.type === utils_1.AST_NODE_TYPES.BlockStatement ||
+                    current.type === utils_1.AST_NODE_TYPES.TSModuleBlock
+                    ? current.body
+                    : undefined;
+                if (body) {
+                    for (const statement of body) {
+                        const found = typeDeclarationNamed(statement, name);
+                        if (found) {
+                            return found;
+                        }
+                    }
+                }
+                current = current.parent;
+            }
+            return undefined;
+        }
         function hasAllOptionalProperties(typeNode) {
             // Handle type literals directly
             if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
@@ -38,29 +82,10 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                 if (typeName.type !== utils_1.AST_NODE_TYPES.Identifier) {
                     return false;
                 }
-                const scope = context.getScope();
-                const variable = scope.variables.find((v) => v.name === typeName.name);
-                if (!variable || !variable.defs[0]?.node) {
-                    // If we can't find the type definition, assume it's a type with required properties
-                    // This handles cases where the type is imported from another module
-                    return false;
-                }
-                const def = variable.defs[0].node;
-                if (def.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
-                    return hasAllOptionalProperties(def.typeAnnotation);
-                }
-                else if (def.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) {
-                    return def.body.body.every((member) => {
-                        if (member.type !== utils_1.AST_NODE_TYPES.TSPropertySignature) {
-                            return false;
-                        }
-                        return member.optional === true;
-                    });
-                }
-                // If we found the type definition but it's not a type alias or interface declaration,
-                // assume it's a type with required properties
-                // This handles cases where the type is imported from another module
-                return false;
+                const declaration = resolveTypeDeclaration(typeNode, typeName.name);
+                // An unresolved name is an imported type whose shape is unknowable
+                // here, so it is treated as carrying required properties.
+                return declaration ? hasAllOptionalProperties(declaration) : false;
             }
             // Handle type alias declarations
             if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
@@ -113,114 +138,16 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
                 if (param.type === utils_1.AST_NODE_TYPES.ObjectPattern &&
                     param.typeAnnotation) {
                     const typeAnnotation = param.typeAnnotation.typeAnnotation;
-                    if (typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
-                        const typeName = typeAnnotation.typeName;
-                        if (typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
-                            const scope = context.getScope();
-                            const variable = scope.variables.find((v) => v.name === typeName.name);
-                            if (variable && variable.defs[0]?.node) {
-                                const def = variable.defs[0].node;
-                                if (def.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
-                                    if (hasAllOptionalProperties(def.typeAnnotation)) {
-                                        context.report({
-                                            node: param,
-                                            messageId: 'requireDefaultParams',
-                                            data: messageData,
-                                            fix(fixer) {
-                                                const paramText = context.sourceCode.getText(param);
-                                                return fixer.replaceText(param, `${paramText} = {}`);
-                                            },
-                                        });
-                                    }
-                                }
-                                else if (def.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) {
-                                    if (def.body.body.every((member) => {
-                                        if (member.type !== utils_1.AST_NODE_TYPES.TSPropertySignature) {
-                                            return false;
-                                        }
-                                        return member.optional === true;
-                                    })) {
-                                        context.report({
-                                            node: param,
-                                            messageId: 'requireDefaultParams',
-                                            data: messageData,
-                                            fix(fixer) {
-                                                const paramText = context.sourceCode.getText(param);
-                                                return fixer.replaceText(param, `${paramText} = {}`);
-                                            },
-                                        });
-                                    }
-                                }
-                            }
-                            else {
-                                // If we can't find the type definition, check if it's defined in the same file
-                                const program = context.sourceCode.ast;
-                                const typeDefinitions = program.body.filter((node) => {
-                                    if (node.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
-                                        node.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) {
-                                        if (node.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
-                                            return node.id.name === typeName.name;
-                                        }
-                                        else {
-                                            return node.id.name === typeName.name;
-                                        }
-                                    }
-                                    return false;
-                                });
-                                if (typeDefinitions.length > 0) {
-                                    const def = typeDefinitions[0];
-                                    if (def.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
-                                        if (hasAllOptionalProperties(def.typeAnnotation)) {
-                                            context.report({
-                                                node: param,
-                                                messageId: 'requireDefaultParams',
-                                                data: messageData,
-                                                fix(fixer) {
-                                                    const paramText = context.sourceCode.getText(param);
-                                                    return fixer.replaceText(param, `${paramText} = {}`);
-                                                },
-                                            });
-                                        }
-                                    }
-                                    else if (def.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) {
-                                        if (def.body.body.every((member) => {
-                                            if (member.type !== utils_1.AST_NODE_TYPES.TSPropertySignature) {
-                                                return false;
-                                            }
-                                            return member.optional === true;
-                                        })) {
-                                            context.report({
-                                                node: param,
-                                                messageId: 'requireDefaultParams',
-                                                data: messageData,
-                                                fix(fixer) {
-                                                    const paramText = context.sourceCode.getText(param);
-                                                    return fixer.replaceText(param, `${paramText} = {}`);
-                                                },
-                                            });
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    }
-                    else if (typeAnnotation.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
-                        if (typeAnnotation.members.every((member) => {
-                            if (member.type !== utils_1.AST_NODE_TYPES.TSPropertySignature) {
-                                return false;
-                            }
-                            return member.optional === true;
-                        })) {
-                            context.report({
-                                node: param,
-                                messageId: 'requireDefaultParams',
-                                data: messageData,
-                                fix(fixer) {
-                                    const paramText = context.sourceCode.getText(param);
-                                    return fixer.replaceText(param, `${paramText} = {}`);
-                                },
-                            });
-                        }
+                    if (hasAllOptionalProperties(typeAnnotation)) {
+                        context.report({
+                            node: param,
+                            messageId: 'requireDefaultParams',
+                            data: messageData,
+                            fix(fixer) {
+                                const paramText = context.sourceCode.getText(param);
+                                return fixer.replaceText(param, `${paramText} = {}`);
+                            },
+                        });
                     }
                 }
             },

package/lib/rules/require-server-timestamp-for-firestore-dates.js

@@ -95,8 +95,16 @@ function typeAnnotationReferencesFirestoreType(typeAnnotation, firestoreTypeName
  * True for the assertion wrappers that leave the underlying expression intact:
  * `x as T` and `x satisfies T`.
  */
+/**
+ * Wrappers that change only the static type, never the runtime value. A
+ * non-null assertion belongs here for the same reason `as` does — `new Date()!`
+ * still constructs a client-clock Date — and it is exactly what a developer
+ * reaches for when silencing a nullability complaint, so leaving it wrapped
+ * turns an accident into a bypass.
+ */
 function isCastExpression(node) {
     return (node.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+        node.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
         node.type ===
             utils_1.AST_NODE_TYPES
                 .TSSatisfiesExpression);
@@ -175,19 +183,15 @@ context) {
         else if (value.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
             reportNewDatesInObject(value, context);
         }
-        else if (value.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
-            value.type ===
-                utils_1.AST_NODE_TYPES
-                    .TSSatisfiesExpression) {
-            // The cast may wrap a new Date() OR an object literal we need to recurse into
+        else if (isCastExpression(value)) {
+            /**
+             * A cast can wrap an object literal that still needs recursion. It cannot
+             * wrap a `new Date()` that reaches here: `isNewDate` unwraps casts before
+             * answering, so the branch above has already reported that shape and this
+             * one is only ever entered when it did not.
+             */
             const inner = unwrapCast(value);
-            if (isNewDate(inner)) {
-                context.report({
-                    node: value,
-                    messageId: 'useServerTimestamp',
-                });
-            }
-            else if (inner.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+            if (inner.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
                 reportNewDatesInObject(inner, context);
             }
         }

package/lib/utils/ASTHelpers.js

@@ -186,6 +186,83 @@ class ASTHelpers {
             case 'TSTypeLiteral':
                 // Handle type constraints and literals
                 return false;
+            /**
+             * Loops, switches and the remaining compound forms. Every node type this
+             * switch omits falls to `default: false` — "references nothing" — so an
+             * omission is not a missed detection but an inverted answer: a function
+             * whose only dependencies sit inside a `for` body reads as free-standing.
+             */
+            case 'ForStatement':
+                return (this.declarationIncludesIdentifier(node.init) ||
+                    this.declarationIncludesIdentifier(node.test) ||
+                    this.declarationIncludesIdentifier(node.update) ||
+                    this.declarationIncludesIdentifier(node.body));
+            case 'ForOfStatement':
+            case 'ForInStatement':
+                return (this.declarationIncludesIdentifier(node.left) ||
+                    this.declarationIncludesIdentifier(node.right) ||
+                    this.declarationIncludesIdentifier(node.body));
+            case 'WhileStatement':
+            case 'DoWhileStatement':
+                return (this.declarationIncludesIdentifier(node.test) ||
+                    this.declarationIncludesIdentifier(node.body));
+            case 'SwitchStatement':
+                return (this.declarationIncludesIdentifier(node.discriminant) ||
+                    node.cases.some((switchCase) => this.declarationIncludesIdentifier(switchCase)));
+            case 'SwitchCase':
+                return (this.declarationIncludesIdentifier(node.test) ||
+                    node.consequent.some((statement) => this.declarationIncludesIdentifier(statement)));
+            case 'LabeledStatement':
+                return this.declarationIncludesIdentifier(node.body);
+            case 'SequenceExpression':
+                return node.expressions.some((expression) => this.declarationIncludesIdentifier(expression));
+            case 'TaggedTemplateExpression':
+                return (this.declarationIncludesIdentifier(node.tag) ||
+                    this.declarationIncludesIdentifier(node.quasi));
+            case 'YieldExpression':
+                return this.declarationIncludesIdentifier(node.argument);
+            case 'ClassDeclaration':
+            case 'ClassExpression':
+                return (this.declarationIncludesIdentifier(node.superClass) ||
+                    this.declarationIncludesIdentifier(node.body));
+            case 'ClassBody':
+                return node.body.some((member) => this.declarationIncludesIdentifier(member));
+            case 'MethodDefinition':
+            case 'PropertyDefinition':
+                return ((node.computed &&
+                    this.declarationIncludesIdentifier(node.key)) ||
+                    this.declarationIncludesIdentifier(node.value));
+            case 'ExportNamedDeclaration':
+            case 'ExportDefaultDeclaration':
+                return this.declarationIncludesIdentifier(node.declaration);
+            /**
+             * JSX subtrees carry references like any other expression. Without these
+             * cases a component that renders `<Component />` or `<div x={value} />`
+             * reads as depending on nothing, so a caller asking "can this be hoisted
+             * out of its enclosing scope?" gets `true` for a closure that cannot be.
+             */
+            case 'JSXElement':
+                return (this.declarationIncludesIdentifier(node.openingElement) ||
+                    node.children.some((child) => this.declarationIncludesIdentifier(child)));
+            case 'JSXFragment':
+                return node.children.some((child) => this.declarationIncludesIdentifier(child));
+            case 'JSXOpeningElement':
+                return (this.declarationIncludesIdentifier(node.name) ||
+                    node.attributes.some((attribute) => this.declarationIncludesIdentifier(attribute)));
+            case 'JSXIdentifier':
+                // A lowercase tag is an intrinsic element (`div`), not a binding; an
+                // capitalized one resolves to a component in scope.
+                return !/^[a-z]/.test(node.name);
+            case 'JSXMemberExpression':
+                // `<Foo.Bar />` references `Foo`.
+                return true;
+            case 'JSXAttribute':
+                return this.declarationIncludesIdentifier(node.value);
+            case 'JSXSpreadAttribute':
+            case 'JSXSpreadChild':
+                return this.declarationIncludesIdentifier(node.argument ?? node.expression);
+            case 'JSXExpressionContainer':
+                return this.declarationIncludesIdentifier(node.expression);
             default:
                 return false;
         }

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,51 @@
 [
+  {
+    "version": "1.20.116",
+    "date": "2026-08-05T20:14:19.457Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-doc-ref-generic",
+        "changeType": "fix",
+        "issues": [
+          1754
+        ],
+        "summary": "detect namespaced reference types (closes #1754)"
+      },
+      {
+        "name": "extract-global-constants",
+        "changeType": "fix",
+        "issues": [
+          1755
+        ],
+        "summary": "report nested helper functions (closes #1755)"
+      },
+      {
+        "name": "prefer-batch-operations",
+        "changeType": "fix",
+        "issues": [
+          1757,
+          1759
+        ],
+        "summary": "resolve the setter declaration lexically (closes #1759); stop flagging a lone set() in Promise.all (closes #1757)"
+      },
+      {
+        "name": "require-hooks-default-params",
+        "changeType": "fix",
+        "issues": [
+          1756
+        ],
+        "summary": "resolve the options type lexically (closes #1756)"
+      },
+      {
+        "name": "require-server-timestamp-for-firestore-dates",
+        "changeType": "fix",
+        "issues": [
+          1758
+        ],
+        "summary": "unwrap non-null assertions (closes #1758)"
+      }
+    ]
+  },
   {
     "version": "1.20.115",
     "date": "2026-08-05T18:41:41.153Z",