@blumintinc/eslint-plugin-blumint 1.20.64 → 1.20.66

package/lib/index.js

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

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

@@ -565,6 +565,183 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
             }
             return false;
         }
+        /**
+         * `@firebase/rules-unit-testing` hands back the compat (v8) Firestore, whose
+         * `.doc()`, `.collection()` and `.collectionGroup()` declare zero type
+         * parameters. Asking for a schema generic there produces
+         * `TS2558: Expected 0 type arguments, but got 1`, so every remediation this
+         * rule suggests is uncompilable on that surface and the receiver must be
+         * exempt.
+         */
+        const RULES_UNIT_TESTING_MODULE = '@firebase/rules-unit-testing';
+        let rulesUnitTestingLocals;
+        /**
+         * Scanned lazily rather than from an `ImportDeclaration` visitor so that
+         * traversal order can never decide whether the exemption applies. Type-only
+         * specifiers count because a callback parameter annotated `RulesTestContext`
+         * is the other way a compat handle reaches a `.doc()` receiver.
+         */
+        function getRulesUnitTestingLocals() {
+            if (rulesUnitTestingLocals) {
+                return rulesUnitTestingLocals;
+            }
+            const locals = new Set();
+            for (const statement of context.sourceCode.ast.body) {
+                if (statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                    statement.source.value === RULES_UNIT_TESTING_MODULE) {
+                    for (const specifier of statement.specifiers) {
+                        locals.add(specifier.local.name);
+                    }
+                }
+            }
+            rulesUnitTestingLocals = locals;
+            return locals;
+        }
+        /**
+         * A qualified annotation such as `rut.RulesTestContext` is rooted at the
+         * namespace binding, which is the name the import declaration provides.
+         */
+        function rootTypeNameOf(typeNode) {
+            if (typeNode.type !== utils_1.AST_NODE_TYPES.TSTypeReference) {
+                return undefined;
+            }
+            let entity = typeNode.typeName;
+            while (entity.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+                entity = entity.left;
+            }
+            return entity.type === utils_1.AST_NODE_TYPES.Identifier
+                ? entity.name
+                : undefined;
+        }
+        function isRulesUnitTestingType(typeNode) {
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType ||
+                typeNode.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
+                return typeNode.types.some(isRulesUnitTestingType);
+            }
+            const rootName = rootTypeNameOf(typeNode);
+            return !!rootName && getRulesUnitTestingLocals().has(rootName);
+        }
+        /**
+         * Walks an expression toward its syntactic root and reports whether that
+         * root is a value supplied by `@firebase/rules-unit-testing`.
+         *
+         * Only `const` bindings are followed, mirroring `isTypedCollectionBinding`:
+         * a `let`/`var` receiver can be reassigned to an Admin SDK handle, where the
+         * generic is both supportable and valuable, so exempting it would silently
+         * drop enforcement.
+         */
+        function tracesToRulesUnitTesting(node, visited = new Set()) {
+            if (!node || getRulesUnitTestingLocals().size === 0) {
+                return false;
+            }
+            // Guards against a self-referential declaration such as `const a = a.b;`.
+            if (visited.has(node)) {
+                return false;
+            }
+            visited.add(node);
+            switch (node.type) {
+                case utils_1.AST_NODE_TYPES.AwaitExpression:
+                    return tracesToRulesUnitTesting(node.argument, visited);
+                case utils_1.AST_NODE_TYPES.CallExpression:
+                    return tracesToRulesUnitTesting(node.callee, visited);
+                case utils_1.AST_NODE_TYPES.MemberExpression:
+                    return tracesToRulesUnitTesting(node.object, visited);
+                case utils_1.AST_NODE_TYPES.ChainExpression:
+                    return tracesToRulesUnitTesting(node.expression, visited);
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+                case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+                    return tracesToRulesUnitTesting(node.expression, visited);
+                case utils_1.AST_NODE_TYPES.Identifier:
+                    return identifierTracesToRulesUnitTesting(node, visited);
+                case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+                case utils_1.AST_NODE_TYPES.FunctionExpression:
+                case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+                    return functionReturnTracesToRulesUnitTesting(node, visited);
+                default:
+                    return false;
+            }
+        }
+        /**
+         * Reached when a receiver is the result of calling a local helper, so what
+         * the helper hands back decides the surface. Only top-level returns are
+         * read; a return nested inside another function belongs to that one.
+         */
+        function functionReturnTracesToRulesUnitTesting(node, visited) {
+            if (node.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+                return tracesToRulesUnitTesting(node.body, visited);
+            }
+            return node.body.body.some((statement) => statement.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
+                tracesToRulesUnitTesting(statement.argument, visited));
+        }
+        /**
+         * `withSecurityRulesDisabled` is the one API here that delivers a context
+         * through a callback rather than a return value, and the documented spelling
+         * leaves the parameter unannotated, so the call it belongs to is the only
+         * evidence of the surface.
+         */
+        const CONTEXT_CALLBACK_METHOD = 'withSecurityRulesDisabled';
+        function parameterTracesToRulesUnitTesting(name, owner, visited) {
+            if (name.type === utils_1.AST_NODE_TYPES.Identifier &&
+                name.typeAnnotation &&
+                isRulesUnitTestingType(name.typeAnnotation.typeAnnotation)) {
+                return true;
+            }
+            const call = owner.parent;
+            if (!call ||
+                call.type !== utils_1.AST_NODE_TYPES.CallExpression ||
+                !call.arguments.includes(owner) ||
+                call.callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                call.callee.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                call.callee.property.name !== CONTEXT_CALLBACK_METHOD) {
+                return false;
+            }
+            return tracesToRulesUnitTesting(call.callee.object, visited);
+        }
+        function identifierTracesToRulesUnitTesting(node, visited) {
+            const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, node.name);
+            if (!variable || variable.defs.length !== 1) {
+                return false;
+            }
+            const def = variable.defs[0];
+            if (def.type === 'ImportBinding') {
+                return (def.parent?.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                    def.parent.source.value === RULES_UNIT_TESTING_MODULE);
+            }
+            if (def.type === 'Parameter') {
+                return parameterTracesToRulesUnitTesting(def.name, def.node, visited);
+            }
+            // A hoisted declaration binds the helper the same way a `const` arrow
+            // does; an ambient `declare function` has no body and falls through.
+            if (def.type === 'FunctionName') {
+                return tracesToRulesUnitTesting(def.node, visited);
+            }
+            if (def.type !== 'Variable' ||
+                def.node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator) {
+                return false;
+            }
+            const declarator = def.node;
+            // An annotation constrains every assignment rather than just the
+            // initializer, so unlike an initializer it survives a `let`. The
+            // environment handle is created in `beforeAll` and so cannot be `const`;
+            // `let testEnv: RulesTestEnvironment` is the documented spelling, and
+            // TypeScript refuses to put another surface in it.
+            if (declarator.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                declarator.id.typeAnnotation &&
+                isRulesUnitTestingType(declarator.id.typeAnnotation.typeAnnotation)) {
+                return true;
+            }
+            // Without that guarantee only a `const` initializer is followed, mirroring
+            // `isTypedCollectionBinding`: an unannotated reassignable binding can hold
+            // an Admin SDK handle by the time it reaches `.doc()`.
+            if (def.parent?.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+                def.parent.kind !== 'const') {
+                return false;
+            }
+            return tracesToRulesUnitTesting(declarator.init, visited);
+        }
         return {
             TSTypeReference(node) {
                 if (node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
@@ -601,6 +778,9 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                 if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
                     node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
                     node.callee.property.name === 'doc') {
+                    if (tracesToRulesUnitTesting(node.callee.object)) {
+                        return;
+                    }
                     const typeAnnotation = node.typeParameters;
                     const isOnTypedCollection = isTypedCollectionReference(node.callee.object);
                     // If this is a .doc() call on a typed CollectionReference,
@@ -655,6 +835,9 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                     node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
                     node.callee.property.name === 'collection' &&
                     !isPartOfMethodChain(node)) {
+                    if (tracesToRulesUnitTesting(node.callee.object)) {
+                        return;
+                    }
                     const typeAnnotation = node.typeParameters;
                     if (!typeAnnotation) {
                         context.report({
@@ -675,6 +858,9 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                 else if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
                     node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
                     node.callee.property.name === 'collectionGroup') {
+                    if (tracesToRulesUnitTesting(node.callee.object)) {
+                        return;
+                    }
                     const typeAnnotation = node.typeParameters;
                     if (!typeAnnotation) {
                         context.report({

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.20.66",
+    "date": "2026-08-01T13:53:31.680Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-doc-ref-generic",
+        "changeType": "fix",
+        "issues": [
+          1564
+        ],
+        "summary": "trace compat receivers through annotated lets and seeding callbacks (closes #1564)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.65",
+    "date": "2026-08-01T13:35:40.762Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-doc-ref-generic",
+        "changeType": "fix",
+        "issues": [
+          1564
+        ],
+        "summary": "exempt compat Firestore receivers from @firebase/rules-unit-testing (closes #1564)"
+      }
+    ]
+  },
   {
     "version": "1.20.64",
     "date": "2026-08-01T12:02:23.073Z",