@blumintinc/eslint-plugin-blumint 1.13.0 → 1.15.0

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

@@ -224,6 +224,27 @@ function findLoopNode(node) {
     }
     return undefined;
 }
+function describeLoopContext(loopInfo) {
+    if (loopInfo.isPromiseAll)
+        return 'Promise.all()';
+    if (loopInfo.isArrayMethod) {
+        return `${loopInfo.isArrayMethod}() callback`;
+    }
+    switch (loopInfo.node.type) {
+        case utils_1.AST_NODE_TYPES.ForStatement:
+            return 'for loop';
+        case utils_1.AST_NODE_TYPES.ForInStatement:
+            return 'for...in loop';
+        case utils_1.AST_NODE_TYPES.ForOfStatement:
+            return 'for...of loop';
+        case utils_1.AST_NODE_TYPES.WhileStatement:
+            return 'while loop';
+        case utils_1.AST_NODE_TYPES.DoWhileStatement:
+            return 'do...while loop';
+        default:
+            return 'this control flow';
+    }
+}
 function isFirestoreSetterInstance(node) {
     // Check if it's a DocSetter instance
     if (node.type === utils_1.AST_NODE_TYPES.NewExpression) {
@@ -301,8 +322,7 @@ exports.preferBatchOperations = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            preferSetAll: 'Use setAll() instead of multiple set() calls for better performance',
-            preferOverwriteAll: 'Use overwriteAll() instead of multiple overwrite() calls for better performance',
+            preferBatch: 'DocSetter.{{setterMethod}} is invoked repeatedly inside {{contextDescription}}, which issues separate Firestore writes per document and can leave partial updates when later calls fail. Batch the documents with DocSetter.{{batchMethod}} so the writes stay grouped and latency stays predictable.',
         },
     },
     defaultOptions: [],
@@ -321,6 +341,13 @@ exports.preferBatchOperations = (0, createRule_1.createRule)({
                 const loopInfo = findLoopNode(node);
                 if (!loopInfo)
                     return;
+                const batchMethod = methodName === 'set' ? 'setAll()' : 'overwriteAll()';
+                const messageData = {
+                    setterMethod: `${methodName}()`,
+                    batchMethod,
+                    contextDescription: describeLoopContext(loopInfo),
+                };
+                const messageId = 'preferBatch';
                 // Get or create the setter calls map for this loop
                 let setterCalls = loopSetterCalls.get(loopInfo.node);
                 if (!setterCalls) {
@@ -348,10 +375,10 @@ exports.preferBatchOperations = (0, createRule_1.createRule)({
                         existing.count === 2 &&
                         !reportedLoops.has(loopInfo.node)) {
                         reportedLoops.add(loopInfo.node);
-                        const messageId = methodName === 'set' ? 'preferSetAll' : 'preferOverwriteAll';
                         context.report({
                             node: existing.firstNode,
                             messageId,
+                            data: messageData,
                             fix: () => null, // We can't provide a fix because we don't know the array structure
                         });
                     }
@@ -371,10 +398,10 @@ exports.preferBatchOperations = (0, createRule_1.createRule)({
                         // For traditional loops, report on the first occurrence since we know it's in a loop
                         if (!reportedLoops.has(loopInfo.node)) {
                             reportedLoops.add(loopInfo.node);
-                            const messageId = methodName === 'set' ? 'preferSetAll' : 'preferOverwriteAll';
                             context.report({
                                 node,
                                 messageId,
+                                data: messageData,
                                 fix: () => null, // We can't provide a fix because we don't know the array structure
                             });
                         }
@@ -383,10 +410,10 @@ exports.preferBatchOperations = (0, createRule_1.createRule)({
                     else if (loopInfo.isArrayMethod) {
                         if (!reportedLoops.has(loopInfo.node)) {
                             reportedLoops.add(loopInfo.node);
-                            const messageId = methodName === 'set' ? 'preferSetAll' : 'preferOverwriteAll';
                             context.report({
                                 node,
                                 messageId,
+                                data: messageData,
                                 fix: () => null, // We can't provide a fix because we don't know the array structure
                             });
                         }

package/lib/rules/prefer-block-comments-for-declarations.js

@@ -65,17 +65,22 @@ exports.preferBlockCommentsForDeclarations = (0, createRule_1.createRule)({
             if (isInsideFunctionBody(node)) {
                 return;
             }
-            const sourceCode = context.getSourceCode();
+            const sourceCode = context.sourceCode;
             const comments = sourceCode.getCommentsBefore(node);
             // Find the closest comment to the node
             const lastComment = comments[comments.length - 1];
             if (lastComment && isLineCommentBeforeDeclaration(lastComment, node)) {
+                const commentText = lastComment.value.trim();
+                const commentLabel = commentText || 'declaration comment';
                 context.report({
                     loc: lastComment.loc,
                     messageId: 'preferBlockComment',
+                    data: { commentText: commentLabel },
                     fix: (fixer) => {
-                        const commentText = lastComment.value.trim();
-                        return fixer.replaceText(lastComment, `/** ${commentText} */`);
+                        if (commentLabel.includes('*/')) {
+                            return null;
+                        }
+                        return fixer.replaceText(lastComment, `/** ${commentLabel} */`);
                     },
                 });
             }
@@ -129,7 +134,7 @@ exports.preferBlockCommentsForDeclarations = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            preferBlockComment: 'Use block comments (/** */) instead of line comments (//) for declarations to improve IDE support.',
+            preferBlockComment: 'Line comment "{{commentText}}" sits on a declaration, and IDE hovers and TypeScript docs ignore it as documentation. Rewrite it as a block comment (/** ... */) so the text stays attached to the declaration and tooling surfaces it.',
         },
     },
     defaultOptions: [],

package/lib/rules/prefer-clone-deep.js

@@ -14,7 +14,7 @@ exports.preferCloneDeep = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            preferCloneDeep: 'Use cloneDeep from functions/src/util/cloneDeep.ts instead of nested spread operators for deep object copying',
+            preferCloneDeep: 'Nested spread copies only clone one level, so inner objects still point at the original and later mutations leak back. Use cloneDeep from functions/src/util/cloneDeep.ts and pass overrides as the second argument so the base object is deeply cloned before applying updates.',
         },
     },
     defaultOptions: [],
@@ -74,7 +74,7 @@ exports.preferCloneDeep = (0, createRule_1.createRule)({
                 !hasSymbol);
         }
         function generateCloneDeepFix(node) {
-            const sourceCode = context.getSourceCode();
+            const sourceCode = context.sourceCode;
             // Find the base object (first spread element)
             let baseObj = null;
             // Extract the base object from the first spread element
@@ -248,7 +248,7 @@ exports.preferCloneDeep = (0, createRule_1.createRule)({
         }
         // Helper function to extract nested overrides without spread elements
         function extractNestedOverrides(node) {
-            const sourceCode = context.getSourceCode();
+            const sourceCode = context.sourceCode;
             const overrides = [];
             for (const prop of node.properties) {
                 if (prop.type === utils_1.AST_NODE_TYPES.Property) {

package/lib/rules/prefer-destructuring-no-class.d.ts

@@ -1,8 +1,9 @@
+import { TSESLint } from '@typescript-eslint/utils';
 type Options = [
     {
         object?: boolean;
         enforceForRenamedProperties?: boolean;
     }
 ];
-export declare const preferDestructuringNoClass: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"preferDestructuring", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export declare const preferDestructuringNoClass: TSESLint.RuleModule<"preferDestructuring", Options, TSESLint.RuleListener>;
 export {};

package/lib/rules/prefer-destructuring-no-class.js

@@ -104,7 +104,7 @@ exports.preferDestructuringNoClass = (0, createRule_1.createRule)({
             },
         ],
         messages: {
-            preferDestructuring: 'Use destructuring instead of accessing the property directly.',
+            preferDestructuring: 'Property "{{property}}" from "{{object}}" is assigned via dot access{{targetNote}}. Destructure the property so the dependency is declared once and stays aligned with the source object. Use destructuring{{renamingHint}} (e.g., {{example}}).',
         },
     },
     defaultOptions,
@@ -114,6 +114,7 @@ exports.preferDestructuringNoClass = (0, createRule_1.createRule)({
             enforceForRenamedProperties: defaultOptions[0].enforceForRenamedProperties,
             ...context.options[0],
         };
+        const sourceCode = context.getSourceCode();
         /**
          * Check if we're inside a class method
          */
@@ -128,32 +129,228 @@ exports.preferDestructuringNoClass = (0, createRule_1.createRule)({
             }
             return false;
         }
+        function isIdentifierTarget(node) {
+            return node.type === utils_1.AST_NODE_TYPES.Identifier;
+        }
+        function isSkippedClassMemberAccess(memberExpression) {
+            return (isClassInstance(memberExpression, context) ||
+                isStaticClassMember(memberExpression, context));
+        }
+        function isThisMemberInClassMethod(memberExpression) {
+            return (memberExpression.object.type === utils_1.AST_NODE_TYPES.ThisExpression &&
+                isInsideClassMethod(memberExpression));
+        }
+        function findEnclosingMethodDefinition(node) {
+            let current = node;
+            while (current) {
+                if (current.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
+                    return current;
+                }
+                current = current.parent ?? undefined;
+            }
+            return null;
+        }
+        function isInsideConstructorBody(node) {
+            let current = node;
+            while (current) {
+                if (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 enclosingMethod = findEnclosingMethodDefinition(current);
+                    return (!!enclosingMethod &&
+                        enclosingMethod.kind === 'constructor' &&
+                        enclosingMethod.value === current);
+                }
+                current = current.parent ?? undefined;
+            }
+            return false;
+        }
+        function isPrivateIdentifierProperty(property) {
+            return property.type === utils_1.AST_NODE_TYPES.PrivateIdentifier;
+        }
+        function canDestructureObjectProperty(memberExpression, identifier) {
+            if (isPrivateIdentifierProperty(memberExpression.property)) {
+                return false;
+            }
+            if (!options.object) {
+                return false;
+            }
+            if (options.enforceForRenamedProperties) {
+                return true;
+            }
+            return isMatchingPropertyName(memberExpression.property, identifier.name);
+        }
+        function getPatternKeyText(memberExpression, propertyText) {
+            if (memberExpression.computed) {
+                return `[${sourceCode.getText(memberExpression.property)}]`;
+            }
+            return propertyText;
+        }
+        function getDestructuringBindingText(memberExpression, propertyText, targetName) {
+            if (isPrivateIdentifierProperty(memberExpression.property)) {
+                return null;
+            }
+            const patternKeyText = getPatternKeyText(memberExpression, propertyText);
+            if (memberExpression.computed ||
+                (options.enforceForRenamedProperties &&
+                    !isMatchingPropertyName(memberExpression.property, targetName))) {
+                return `${patternKeyText}: ${targetName}`;
+            }
+            return patternKeyText;
+        }
         /**
          * Check if destructuring should be used for this node
          */
         function shouldUseDestructuring(node, leftNode) {
-            // Skip if this is a class instance or static class member
-            if (isClassInstance(node, context) ||
-                isStaticClassMember(node, context)) {
+            if (!isIdentifierTarget(leftNode)) {
                 return false;
             }
-            // Skip if the object is 'this' and we're inside a class method
-            if (node.object.type === utils_1.AST_NODE_TYPES.ThisExpression &&
-                isInsideClassMethod(node)) {
-                return false;
+            return (!isSkippedClassMemberAccess(node) &&
+                !isThisMemberInClassMethod(node) &&
+                canDestructureObjectProperty(node, leftNode));
+        }
+        /**
+         * Extracts the property name from a MemberExpression when it can be safely compared.
+         */
+        function getMemberExpressionPropertyName(memberExpression) {
+            if (isPrivateIdentifierProperty(memberExpression.property)) {
+                return null;
             }
-            // Check object destructuring
-            if (options.object) {
-                if (options.enforceForRenamedProperties) {
-                    return true;
+            if (!memberExpression.computed) {
+                if (memberExpression.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return memberExpression.property.name;
                 }
-                // Only suggest destructuring when property name matches variable name
-                if (leftNode.type === utils_1.AST_NODE_TYPES.Identifier) {
-                    return isMatchingPropertyName(node.property, leftNode.name);
+                return null;
+            }
+            if (memberExpression.property.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof memberExpression.property.value === 'string') {
+                return memberExpression.property.value;
+            }
+            return null;
+        }
+        /**
+         * Look up a variable by name within a scope.
+         */
+        function findVariableInScope(scope, name) {
+            return scope?.variables.find((variable) => variable.name === name);
+        }
+        /**
+         * Check whether a variable definition originates from a parameter.
+         */
+        function isParameterDefinition(variable) {
+            if (!variable || !Array.isArray(variable.defs)) {
+                return false;
+            }
+            return variable.defs.some((definition) => definition.type === 'Parameter');
+        }
+        /**
+         * Determine whether an identifier refers to a function or method parameter.
+         */
+        function isFunctionParameter(identifier) {
+            let scope = context.getScope();
+            while (scope) {
+                const variable = findVariableInScope(scope, identifier.name);
+                if (variable) {
+                    return isParameterDefinition(variable);
                 }
+                scope = scope.upper;
             }
             return false;
         }
+        function buildReportDetails(memberExpr, targetName, examplePrefix, exampleSuffix) {
+            const objectText = sourceCode.getText(memberExpr.object);
+            const propertyText = getPropertyText(memberExpr.property, memberExpr.computed, sourceCode);
+            const usesRenaming = options.enforceForRenamedProperties &&
+                !!targetName &&
+                !isMatchingPropertyName(memberExpr.property, targetName);
+            const aliasName = targetName ?? propertyText;
+            const patternKeyText = getPatternKeyText(memberExpr, propertyText);
+            const destructuringBinding = getDestructuringBindingText(memberExpr, propertyText, aliasName) ??
+                patternKeyText;
+            return {
+                propertyText,
+                objectText,
+                destructuringBinding,
+                data: {
+                    property: propertyText,
+                    object: objectText,
+                    targetNote: usesRenaming && targetName ? ` to "${targetName}"` : '',
+                    renamingHint: usesRenaming ? ' with renaming' : '',
+                    example: usesRenaming
+                        ? `${examplePrefix}{ ${destructuringBinding} } = ${objectText}${exampleSuffix}`
+                        : `${examplePrefix}{ ${destructuringBinding} } = ${objectText}${exampleSuffix}`,
+                },
+            };
+        }
+        function generateVariableDeclaratorFix(fixer, node, propertyText, objectText, memberExpr) {
+            const parentNode = node.parent;
+            if (!parentNode ||
+                parentNode.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
+                return null;
+            }
+            if (parentNode.declarations.length > 1) {
+                return null;
+            }
+            const kind = parentNode.kind;
+            if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return null;
+            }
+            const destructuringBinding = getDestructuringBindingText(memberExpr, propertyText, node.id.name);
+            if (!destructuringBinding) {
+                return null;
+            }
+            return fixer.replaceText(parentNode, `${kind} { ${destructuringBinding} } = ${objectText};`);
+        }
+        function generateAssignmentExpressionFix(fixer, node, propertyText, objectText, memberExpr) {
+            if (node.left.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return null;
+            }
+            const destructuringBinding = getDestructuringBindingText(memberExpr, propertyText, node.left.name);
+            if (!destructuringBinding) {
+                return null;
+            }
+            return fixer.replaceText(node, `({ ${destructuringBinding} } = ${objectText})`);
+        }
+        /**
+         * Report assignments that copy properties from parameter objects to class fields.
+         * These are reported without a fixer to avoid changing function signatures.
+         */
+        function handleClassPropertyAssignment(node) {
+            // Caller ensures node.right is a MemberExpression.
+            if (!options.object ||
+                node.left.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                node.left.object.type !== utils_1.AST_NODE_TYPES.ThisExpression) {
+                return;
+            }
+            if (!isInsideConstructorBody(node)) {
+                return;
+            }
+            const rightObject = node.right.object;
+            if (rightObject.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !isFunctionParameter(rightObject)) {
+                return;
+            }
+            const leftPropertyName = getMemberExpressionPropertyName(node.left);
+            const rightPropertyName = getMemberExpressionPropertyName(node.right);
+            if (!leftPropertyName || !rightPropertyName) {
+                return;
+            }
+            if (!options.enforceForRenamedProperties &&
+                leftPropertyName !== rightPropertyName) {
+                return;
+            }
+            if (isClassInstance(node.right, context) ||
+                isStaticClassMember(node.right, context)) {
+                return;
+            }
+            const { data } = buildReportDetails(node.right, leftPropertyName, '(', ')');
+            // No fixer here because destructuring parameters changes the function signature and must stay manual.
+            context.report({
+                node,
+                messageId: 'preferDestructuring',
+                data,
+            });
+        }
         return {
             VariableDeclarator(node) {
                 // Skip if variable is declared without assignment or if init is not a MemberExpression
@@ -161,57 +358,45 @@ exports.preferDestructuringNoClass = (0, createRule_1.createRule)({
                     return;
                 if (node.init.type !== utils_1.AST_NODE_TYPES.MemberExpression)
                     return;
-                if (shouldUseDestructuring(node.init, node.id)) {
-                    const sourceCode = context.getSourceCode();
-                    const objectText = sourceCode.getText(node.init.object);
-                    const propertyText = getPropertyText(node.init.property, node.init.computed, sourceCode);
+                const memberInit = node.init;
+                if (!shouldUseDestructuring(memberInit, node.id)) {
+                    return;
+                }
+                const targetName = node.id.type === utils_1.AST_NODE_TYPES.Identifier ? node.id.name : null;
+                const { propertyText, objectText, data } = buildReportDetails(memberInit, targetName, `${node.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclaration
+                    ? node.parent.kind
+                    : 'const'} `, ';');
+                context.report({
+                    node,
+                    messageId: 'preferDestructuring',
+                    data,
+                    fix(fixer) {
+                        return generateVariableDeclaratorFix(fixer, node, propertyText, objectText, memberInit);
+                    },
+                });
+            },
+            AssignmentExpression(node) {
+                if (node.operator !== '=' ||
+                    node.right.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+                    return;
+                }
+                const memberRight = node.right;
+                if (shouldUseDestructuring(memberRight, node.left)) {
+                    const targetName = node.left.type === utils_1.AST_NODE_TYPES.Identifier
+                        ? node.left.name
+                        : null;
+                    const { propertyText, objectText, data } = buildReportDetails(memberRight, targetName, '(', ')');
                     context.report({
                         node,
                         messageId: 'preferDestructuring',
+                        data,
                         fix(fixer) {
-                            // Get the variable declaration kind (const, let, var)
-                            const parentNode = node.parent;
-                            if (!parentNode ||
-                                parentNode.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
-                                return null;
-                            }
-                            const kind = parentNode.kind;
-                            // Handle renamed properties
-                            if (options.enforceForRenamedProperties &&
-                                node.id.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                node.init &&
-                                node.init.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                                !isMatchingPropertyName(node.init.property, node.id.name)) {
-                                return fixer.replaceText(parentNode, `${kind} { ${propertyText}: ${node.id.name} } = ${objectText};`);
-                            }
-                            return fixer.replaceText(parentNode, `${kind} { ${propertyText} } = ${objectText};`);
+                            return generateAssignmentExpressionFix(fixer, node, propertyText, objectText, memberRight);
                         },
                     });
+                    return;
                 }
-            },
-            AssignmentExpression(node) {
-                if (node.operator === '=' &&
-                    node.right.type === utils_1.AST_NODE_TYPES.MemberExpression) {
-                    if (shouldUseDestructuring(node.right, node.left)) {
-                        const sourceCode = context.getSourceCode();
-                        const objectText = sourceCode.getText(node.right.object);
-                        const propertyText = getPropertyText(node.right.property, node.right.computed, sourceCode);
-                        context.report({
-                            node,
-                            messageId: 'preferDestructuring',
-                            fix(fixer) {
-                                // Handle renamed properties
-                                if (options.enforceForRenamedProperties &&
-                                    node.left.type === utils_1.AST_NODE_TYPES.Identifier &&
-                                    node.right.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                                    !isMatchingPropertyName(node.right.property, node.left.name)) {
-                                    return fixer.replaceText(node, `({ ${propertyText}: ${node.left.name} } = ${objectText})`);
-                                }
-                                return fixer.replaceText(node, `({ ${propertyText} } = ${objectText})`);
-                            },
-                        });
-                    }
-                }
+                handleClassPropertyAssignment(node);
             },
         };
     },

package/lib/rules/prefer-docsetter-setall.d.ts

@@ -0,0 +1,2 @@
+import { TSESLint } from '@typescript-eslint/utils';
+export declare const preferDocSetterSetAll: TSESLint.RuleModule<"preferSetAll", [], TSESLint.RuleListener>;