@blumintinc/eslint-plugin-blumint 1.12.6 → 1.14.0

package/lib/rules/enforce-fieldpath-syntax-in-docsetter.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceFieldPathSyntaxInDocSetter = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const getMethodName_1 = require("../utils/getMethodName");
+exports.enforceFieldPathSyntaxInDocSetter = (0, createRule_1.createRule)({
+    name: 'enforce-fieldpath-syntax-in-docsetter',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce the use of Firestore FieldPath syntax when passing documentData into DocSetter. Instead of using nested object syntax, developers should use dot notation for deeply nested fields.',
+            recommended: 'error',
+            requiresTypeChecking: false,
+            extendsBaseRule: false,
+        },
+        fixable: 'code',
+        schema: [],
+        messages: {
+            enforceFieldPathSyntax: 'What’s wrong: DocSetter {{methodName}} receives nested object data under "{{topLevelKey}}". → Why it matters: Firestore treats that nested map as a whole sub-document write, so partial updates can overwrite sibling fields you did not include. → How to fix: Flatten nested properties into FieldPath (dot) keys before passing documentData (e.g., "{{exampleFieldPath}}") so only the intended leaves are written.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        // Track DocSetter variables
+        const docSetterVariables = new Set();
+        // Helper function to check if a node is a DocSetter method call
+        function isDocSetterMethodCall(node) {
+            if (node.callee.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+                return false;
+            }
+            const { object, property } = node.callee;
+            // Only enforce for set/updateIfExists; skip overwrite (full-document replacement)
+            if (property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !['set', 'updateIfExists'].includes(property.name)) {
+                return false;
+            }
+            // Check if the object is a DocSetter instance
+            if (object.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return docSetterVariables.has(object.name);
+            }
+            // Support chained instantiation: new DocSetter(...).set(...)
+            if (object.type === utils_1.AST_NODE_TYPES.NewExpression &&
+                object.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                object.callee.name === 'DocSetter') {
+                return true;
+            }
+            return false;
+        }
+        // Helper: detect spread or computed properties in an object literal
+        function isSpreadOrComputed(prop) {
+            return (prop.type === utils_1.AST_NODE_TYPES.SpreadElement ||
+                (prop.type === utils_1.AST_NODE_TYPES.Property && prop.computed === true));
+        }
+        function isNumericKey(property) {
+            return (property.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                (typeof property.key.value === 'number' ||
+                    (typeof property.key.value === 'string' &&
+                        /^\d+$/.test(property.key.value))));
+        }
+        function hasRootNumericKey(node) {
+            return node.properties.some((property) => property.type === utils_1.AST_NODE_TYPES.Property && isNumericKey(property));
+        }
+        // Helper function to flatten nested objects into FieldPath syntax
+        function flattenObject(obj, sourceCode, prefix = '') {
+            const result = {};
+            for (const property of obj.properties) {
+                // Skip spread elements
+                if (property.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+                    continue;
+                }
+                if (property.type !== utils_1.AST_NODE_TYPES.Property) {
+                    continue;
+                }
+                // Skip computed properties (dynamic keys)
+                if (property.computed) {
+                    continue;
+                }
+                let key;
+                if (property.key.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    key = property.key.name;
+                }
+                else if (property.key.type === utils_1.AST_NODE_TYPES.Literal) {
+                    // Handle both string and numeric literal keys
+                    if (typeof property.key.value === 'string') {
+                        key = property.key.value;
+                    }
+                    else if (typeof property.key.value === 'number') {
+                        key = String(property.key.value);
+                    }
+                    else {
+                        // Skip other literal types
+                        continue;
+                    }
+                }
+                else {
+                    // Skip other key types
+                    continue;
+                }
+                const numericKey = isNumericKey(property);
+                if (prefix === '' && numericKey) {
+                    continue;
+                }
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                // If the value is a nested object, recursively flatten it
+                if (property.value.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    const nestedResult = flattenObject(property.value, sourceCode, fullKey);
+                    Object.assign(result, nestedResult);
+                }
+                else {
+                    // For non-object values, use the key as is
+                    result[fullKey] = sourceCode.getText(property.value);
+                }
+            }
+            return result;
+        }
+        // Helper to decide if a key needs quoting (contains dot or is not IdentifierName)
+        function needsQuoting(key) {
+            return key.includes('.') || !/^(?:[$_A-Za-z][$\w]*)$/u.test(key);
+        }
+        // Helper function to convert an object to FieldPath syntax
+        function convertToFieldPathSyntax(node, sourceCode, preflattened) {
+            const idProperty = node.properties.find((prop) => prop.type === utils_1.AST_NODE_TYPES.Property &&
+                prop.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                prop.key.name === 'id');
+            const flattenedProperties = {
+                ...(preflattened ?? flattenObject(node, sourceCode)),
+            };
+            if (idProperty && idProperty.type === utils_1.AST_NODE_TYPES.Property) {
+                delete flattenedProperties['id'];
+            }
+            const entries = Object.entries(flattenedProperties);
+            const propertyComma = ',';
+            // Start with the id property if it exists
+            let result = '{\n';
+            if (idProperty && idProperty.type === utils_1.AST_NODE_TYPES.Property) {
+                result += `  id: ${sourceCode.getText(idProperty.value)}${propertyComma}\n`;
+            }
+            // Add the flattened properties (always include trailing commas for multiline objects)
+            entries.forEach(([key, value]) => {
+                const printedKey = needsQuoting(key) ? `'${key}'` : key;
+                result += `  ${printedKey}: ${value}${propertyComma}\n`;
+            });
+            result += '}';
+            return result;
+        }
+        function getPropertyKeyText(property) {
+            if (property.key.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return property.key.name;
+            }
+            if (property.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                (typeof property.key.value === 'string' ||
+                    typeof property.key.value === 'number')) {
+                return String(property.key.value);
+            }
+            return undefined;
+        }
+        function getFirstNestedObjectProperty(node, keyPredicate) {
+            for (const property of node.properties) {
+                if (isSpreadOrComputed(property)) {
+                    continue;
+                }
+                if (property.type !== utils_1.AST_NODE_TYPES.Property) {
+                    continue;
+                }
+                const propertyKeyText = getPropertyKeyText(property);
+                if (!propertyKeyText) {
+                    continue;
+                }
+                if (keyPredicate && !keyPredicate(propertyKeyText)) {
+                    continue;
+                }
+                // Root-level numeric keys typically model array-style buckets rather than
+                // Firestore document fields, so ignore them when identifying nested objects
+                if (node.parent?.type !== utils_1.AST_NODE_TYPES.Property &&
+                    isNumericKey(property)) {
+                    continue;
+                }
+                if (property.value.type !== utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    continue;
+                }
+                const hasSpreadOrComputed = property.value.properties.some((prop) => isSpreadOrComputed(prop));
+                if (hasSpreadOrComputed) {
+                    continue;
+                }
+                return property;
+            }
+            return undefined;
+        }
+        function extractViolationDetails(firstArg, sourceCode) {
+            const firstNestedPropertyWithoutDots = getFirstNestedObjectProperty(firstArg, (key) => !key.includes('.'));
+            const firstNestedProperty = firstNestedPropertyWithoutDots ||
+                getFirstNestedObjectProperty(firstArg);
+            if (!firstNestedProperty) {
+                return null;
+            }
+            const propertyKeyText = getPropertyKeyText(firstNestedProperty);
+            const exampleFieldPathFromProperty = propertyKeyText &&
+                flattenObject(firstNestedProperty.value, sourceCode, propertyKeyText);
+            const flattenedProperties = flattenObject(firstArg, sourceCode);
+            const exampleFieldPath = (exampleFieldPathFromProperty &&
+                Object.keys(exampleFieldPathFromProperty).find((key) => key.includes('.'))) ??
+                (propertyKeyText &&
+                    Object.keys(flattenedProperties).find((key) => key.startsWith(`${propertyKeyText}.`))) ??
+                Object.keys(flattenedProperties).find((key) => key.includes('.')) ??
+                'field.nested';
+            return {
+                topLevelKey: propertyKeyText ?? 'nested field',
+                exampleFieldPath,
+                flattenedProperties,
+            };
+        }
+        return {
+            // Track DocSetter variable declarations
+            VariableDeclarator(node) {
+                if (node.init?.type === utils_1.AST_NODE_TYPES.NewExpression &&
+                    node.init.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.init.callee.name === 'DocSetter' &&
+                    node.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    docSetterVariables.add(node.id.name);
+                }
+            },
+            // Check DocSetter method calls
+            CallExpression(node) {
+                if (!isDocSetterMethodCall(node)) {
+                    return;
+                }
+                // Check if the first argument is an object literal
+                const firstArg = node.arguments[0];
+                if (firstArg?.type !== utils_1.AST_NODE_TYPES.ObjectExpression) {
+                    return;
+                }
+                if (hasRootNumericKey(firstArg)) {
+                    return;
+                }
+                const violationDetails = extractViolationDetails(firstArg, sourceCode);
+                if (!violationDetails) {
+                    return;
+                }
+                // Report and fix the issue
+                const callee = node.callee;
+                context.report({
+                    node: firstArg,
+                    messageId: 'enforceFieldPathSyntax',
+                    data: {
+                        methodName: `${(0, getMethodName_1.getMemberExpressionName)(callee, sourceCode, {
+                            computedFallbackToText: false,
+                        }) || 'set'}()`,
+                        topLevelKey: violationDetails.topLevelKey,
+                        exampleFieldPath: violationDetails.exampleFieldPath,
+                    },
+                    fix(fixer) {
+                        const newText = convertToFieldPathSyntax(firstArg, sourceCode, violationDetails.flattenedProperties);
+                        return fixer.replaceText(firstArg, newText);
+                    },
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=enforce-fieldpath-syntax-in-docsetter.js.map

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

@@ -24,8 +24,20 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            missingGeneric: '{{ type }} must specify a generic type argument for type safety. Instead of `const docRef = doc(collection)`, use `const docRef = doc<YourType>(collection)`.',
-            invalidGeneric: '{{ type }} must not use "any" or "{}" as generic type argument. Define a proper interface/type for your document: `interface UserDoc { name: string; age: number; }` and use it: `const docRef = doc<UserDoc>(collection)`.',
+            missingGeneric: [
+                "What's wrong: {{ type }} is missing its document schema generic (the document data type).",
+                '',
+                'Why it matters: Without the generic, Firestore references fall back to loose DocumentData, so TypeScript cannot catch field typos or missing required properties before they reach Firestore.',
+                '',
+                'How to fix: Add the document interface/type as the generic (e.g., const ref: {{ type }}<UserDoc> = ... or doc<UserDoc>(collection)).',
+            ].join('\n'),
+            invalidGeneric: [
+                'What\'s wrong: {{ type }} uses "any" or an empty object ({}) in its schema generic.',
+                '',
+                'Why it matters: This erases the document schema and disables TypeScript checks on Firestore reads and writes, so malformed payloads and missing fields can pass silently.',
+                '',
+                'How to fix: Define a concrete interface/type for the document (e.g., interface UserDoc { name: string }) and use it as the generic instead of "any" or {}.',
+            ].join('\n'),
         },
     },
     defaultOptions: [],
@@ -61,7 +73,7 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                         }
                         // Prevent infinite recursion
                         typeCache.set(typeName, false);
-                        const program = context.getSourceCode().ast;
+                        const program = context.sourceCode.ast;
                         const interfaceDecl = program.body.find((n) => n.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration &&
                             n.id.name === typeName);
                         if (interfaceDecl) {
@@ -194,6 +206,308 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
             }
             return false;
         }
+        const isTypedCollectionReferenceCache = new Map();
+        function isTypedCollectionReference(node) {
+            if (!node)
+                return false;
+            if (isTypedCollectionReferenceCache.has(node)) {
+                return isTypedCollectionReferenceCache.get(node);
+            }
+            let result = false;
+            if (node.type === utils_1.AST_NODE_TYPES.CallExpression &&
+                node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                node.callee.property.name === 'collection' &&
+                node.typeParameters &&
+                node.typeParameters.params.length > 0) {
+                result = true;
+            }
+            else if (node.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                result = checkMemberExpressionForCollectionReference(node);
+            }
+            else if (node.type === utils_1.AST_NODE_TYPES.Identifier) {
+                result = checkIdentifierForCollectionReference(node);
+            }
+            else if (node.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                result = checkCallExpressionForCollectionReference(node);
+            }
+            isTypedCollectionReferenceCache.set(node, result);
+            return result;
+        }
+        function checkMemberExpressionForCollectionReference(node) {
+            const obj = node.object;
+            const property = node.property;
+            // Handle this.property access
+            if (obj.type === utils_1.AST_NODE_TYPES.ThisExpression &&
+                property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const classNode = findParentClass(node);
+                if (classNode) {
+                    const classProp = classNode.body.body.find((member) => member.type === utils_1.AST_NODE_TYPES.PropertyDefinition &&
+                        member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        member.key.name === property.name);
+                    if (classProp?.typeAnnotation) {
+                        return hasCollectionReferenceType(classProp.typeAnnotation.typeAnnotation);
+                    }
+                }
+            }
+            // Handle nested property access like this.collections.tasks
+            if (obj.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                const parentType = getTypeOfMemberExpression(obj);
+                if (parentType && property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    // Check if the parent object has a property with CollectionReference type
+                    return checkObjectPropertyForCollectionReference(parentType, property.name);
+                }
+            }
+            // Handle identifier.property access
+            if (obj.type === utils_1.AST_NODE_TYPES.Identifier &&
+                property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const objType = getTypeOfIdentifier(obj);
+                if (objType) {
+                    return checkObjectPropertyForCollectionReference(objType, property.name);
+                }
+            }
+            // Handle getter methods like this.collection where collection is a getter
+            if (obj.type === utils_1.AST_NODE_TYPES.ThisExpression &&
+                property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const classNode = findParentClass(node);
+                if (classNode) {
+                    const getter = classNode.body.body.find((member) => member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+                        member.kind === 'get' &&
+                        member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        member.key.name === property.name);
+                    if (getter) {
+                        // Check explicit return type
+                        if (getter.value.returnType) {
+                            return hasCollectionReferenceType(getter.value.returnType.typeAnnotation);
+                        }
+                        // Check return statement to infer type
+                        if (getter.value.body &&
+                            getter.value.body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+                            const returnStmt = getter.value.body.body.find((stmt) => stmt.type === utils_1.AST_NODE_TYPES.ReturnStatement);
+                            if (returnStmt?.argument?.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                                return checkMemberExpressionForCollectionReference(returnStmt.argument);
+                            }
+                        }
+                    }
+                }
+            }
+            return false;
+        }
+        function checkIdentifierForCollectionReference(node) {
+            // Check function parameters
+            const functionParam = findFunctionParameter(node);
+            if (functionParam &&
+                'typeAnnotation' in functionParam &&
+                functionParam.typeAnnotation) {
+                return hasCollectionReferenceType(functionParam.typeAnnotation.typeAnnotation);
+            }
+            // Check variable declarations in current scope and parent scopes
+            if (findVariableDeclaration(node)) {
+                return true;
+            }
+            return false;
+        }
+        function checkCallExpressionForCollectionReference(node) {
+            // Check if this is a method call that returns CollectionReference
+            if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                const obj = node.callee.object;
+                const property = node.callee.property;
+                if (property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    // Check if this is a getter or method that returns CollectionReference
+                    if (obj.type === utils_1.AST_NODE_TYPES.ThisExpression) {
+                        const classNode = findParentClass(node);
+                        if (classNode) {
+                            const method = classNode.body.body.find((member) => member.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+                                member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                member.key.name === property.name &&
+                                !!member.value.returnType);
+                            if (method?.value.returnType) {
+                                return hasCollectionReferenceType(method.value.returnType.typeAnnotation);
+                            }
+                        }
+                    }
+                }
+            }
+            return false;
+        }
+        function getTypeOfMemberExpression(node) {
+            if (node.object.type === utils_1.AST_NODE_TYPES.ThisExpression &&
+                node.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                const classNode = findParentClass(node);
+                if (classNode) {
+                    const classProp = classNode.body.body.find((member) => member.type === utils_1.AST_NODE_TYPES.PropertyDefinition &&
+                        member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        'name' in node.property &&
+                        member.key.name === node.property.name);
+                    return classProp?.typeAnnotation?.typeAnnotation || null;
+                }
+            }
+            return null;
+        }
+        function getTypeOfIdentifier(node) {
+            const functionParam = findFunctionParameter(node);
+            if (functionParam &&
+                'typeAnnotation' in functionParam &&
+                functionParam.typeAnnotation) {
+                return functionParam.typeAnnotation.typeAnnotation;
+            }
+            const varDecl = findVariableDeclarationNode(node);
+            if (varDecl?.typeAnnotation) {
+                return varDecl.typeAnnotation.typeAnnotation;
+            }
+            return null;
+        }
+        function checkObjectPropertyForCollectionReference(objectType, propertyName) {
+            if (objectType.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
+                const property = objectType.members.find((member) => member.type === utils_1.AST_NODE_TYPES.TSPropertySignature &&
+                    member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    member.key.name === propertyName &&
+                    !!member.typeAnnotation);
+                if (property?.typeAnnotation) {
+                    return hasCollectionReferenceType(property.typeAnnotation.typeAnnotation);
+                }
+            }
+            // Handle Record<string, CollectionReference<T>> types
+            if (objectType.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+                objectType.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+                objectType.typeName.name === 'Record' &&
+                objectType.typeParameters &&
+                objectType.typeParameters.params.length === 2) {
+                const valueType = objectType.typeParameters.params[1];
+                return hasCollectionReferenceType(valueType);
+            }
+            // Handle array types like CollectionReference<T>[]
+            if (objectType.type === utils_1.AST_NODE_TYPES.TSArrayType) {
+                return hasCollectionReferenceType(objectType.elementType);
+            }
+            return false;
+        }
+        function findFunctionParameter(node) {
+            const isFunctionNode = (n) => n.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                n.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                n.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression;
+            const findParamInFunction = (func) => {
+                const param = func.params.find((p) => p.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    p.name === node.name &&
+                    'typeAnnotation' in p &&
+                    p.typeAnnotation !== undefined);
+                return param || null;
+            };
+            const functionScopes = [];
+            let current = node;
+            while (current) {
+                if (isFunctionNode(current)) {
+                    functionScopes.push(current);
+                }
+                current = current.parent;
+            }
+            for (const func of functionScopes) {
+                const param = findParamInFunction(func);
+                if (param) {
+                    return param;
+                }
+            }
+            return null;
+        }
+        function findVariableDeclaration(node) {
+            let current = node;
+            while (current) {
+                // Check in current scope
+                if (current.type === utils_1.AST_NODE_TYPES.Program ||
+                    current.type === utils_1.AST_NODE_TYPES.BlockStatement ||
+                    current.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                    current.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                    current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                    const varDecl = findVariableInScope(current, node.name);
+                    if (varDecl && varDecl.typeAnnotation) {
+                        return hasCollectionReferenceType(varDecl.typeAnnotation.typeAnnotation);
+                    }
+                }
+                current = current.parent;
+            }
+            return false;
+        }
+        function findVariableDeclarationNode(node) {
+            let current = node;
+            while (current) {
+                if (current.type === utils_1.AST_NODE_TYPES.Program ||
+                    current.type === utils_1.AST_NODE_TYPES.BlockStatement ||
+                    current.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                    current.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                    current.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                    const varDecl = findVariableInScope(current, node.name);
+                    if (varDecl) {
+                        return varDecl;
+                    }
+                }
+                current = current.parent;
+            }
+            return null;
+        }
+        function findVariableInScope(scope, varName) {
+            const body = getNodeBody(scope);
+            if (!body)
+                return null;
+            for (const stmt of body) {
+                if (stmt.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+                    for (const decl of stmt.declarations) {
+                        if (decl.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+                            decl.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                            decl.id.name === varName &&
+                            decl.id.typeAnnotation) {
+                            return decl.id;
+                        }
+                    }
+                }
+            }
+            return null;
+        }
+        function getNodeBody(node) {
+            if (node.type === utils_1.AST_NODE_TYPES.Program) {
+                return node.body;
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+                return node.body;
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                node.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+                return node.body?.body || null;
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                return node.body.type === utils_1.AST_NODE_TYPES.BlockStatement
+                    ? node.body.body
+                    : null;
+            }
+            return null;
+        }
+        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')) &&
+                typeNode.typeParameters &&
+                typeNode.typeParameters.params.length > 0) {
+                return true;
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSUnionType) {
+                return typeNode.types.some(hasCollectionReferenceType);
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSIntersectionType) {
+                return typeNode.types.some(hasCollectionReferenceType);
+            }
+            // TSParenthesizedType may appear even though AST_NODE_TYPES omits it
+            if (typeNode.type === 'TSParenthesizedType') {
+                const inner = typeNode
+                    .typeAnnotation;
+                return hasCollectionReferenceType(inner);
+            }
+            if (typeNode.type === utils_1.AST_NODE_TYPES.TSArrayType) {
+                return hasCollectionReferenceType(typeNode.elementType);
+            }
+            return false;
+        }
         return {
             TSTypeReference(node) {
                 if (node.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
@@ -231,6 +545,39 @@ exports.enforceFirestoreDocRefGeneric = (0, createRule_1.createRule)({
                     node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
                     node.callee.property.name === 'doc') {
                     const typeAnnotation = node.typeParameters;
+                    const isOnTypedCollection = isTypedCollectionReference(node.callee.object);
+                    // If this is a .doc() call on a typed CollectionReference,
+                    // only check for invalid generics, not missing generics
+                    if (isOnTypedCollection) {
+                        if (typeAnnotation && hasInvalidType(typeAnnotation.params[0])) {
+                            context.report({
+                                node,
+                                messageId: 'invalidGeneric',
+                                data: { type: 'DocumentReference' },
+                            });
+                        }
+                        return; // Skip the missing generic check for typed CollectionReference.doc() calls
+                    }
+                    // For standalone doc() calls or calls on untyped collections
+                    if (!typeAnnotation) {
+                        context.report({
+                            node,
+                            messageId: 'missingGeneric',
+                            data: { type: 'DocumentReference' },
+                        });
+                    }
+                    else if (hasInvalidType(typeAnnotation.params[0])) {
+                        context.report({
+                            node,
+                            messageId: 'invalidGeneric',
+                            data: { type: 'DocumentReference' },
+                        });
+                    }
+                }
+                // Check for standalone doc() function calls
+                else if (node.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.callee.name === 'doc') {
+                    const typeAnnotation = node.typeParameters;
                     if (!typeAnnotation) {
                         context.report({
                             node,