@blumintinc/eslint-plugin-blumint 1.13.0 → 1.14.0

package/lib/rules/no-explicit-return-type.js

@@ -11,6 +11,98 @@ const defaultOptions = {
     allowDtsFiles: true,
     allowFirestoreFunctionFiles: true,
 };
+function getNameFromIdentifierOrLiteral(key) {
+    if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    if (typeof key.value === 'string') {
+        return key.value;
+    }
+    return undefined;
+}
+function describeClassMethod(node) {
+    if (!node.computed &&
+        (node.key.type === utils_1.AST_NODE_TYPES.Identifier ||
+            (node.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof node.key.value === 'string'))) {
+        const name = getNameFromIdentifierOrLiteral(node.key);
+        if (name) {
+            return `class method "${name}"`;
+        }
+    }
+    return 'class method';
+}
+function describeMethodSignature(node) {
+    if (!node.computed &&
+        (node.key.type === utils_1.AST_NODE_TYPES.Identifier ||
+            (node.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof node.key.value === 'string'))) {
+        const name = getNameFromIdentifierOrLiteral(node.key);
+        if (name) {
+            return `interface method "${name}"`;
+        }
+    }
+    return 'interface method';
+}
+function describeFunctionDeclaration(node) {
+    if (node.id?.name) {
+        return `function "${node.id.name}"`;
+    }
+    return 'function';
+}
+function describeTSDeclareFunction(node) {
+    if (node.id?.name) {
+        return `function "${node.id.name}"`;
+    }
+    return 'function';
+}
+function describeFunctionExpression(node) {
+    if (node.id?.name) {
+        return `function "${node.id.name}"`;
+    }
+    if (node.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        node.parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return `function "${node.parent.id.name}"`;
+    }
+    if (node.parent?.type === utils_1.AST_NODE_TYPES.Property &&
+        !node.parent.computed &&
+        (node.parent.key.type === utils_1.AST_NODE_TYPES.Identifier ||
+            (node.parent.key.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof node.parent.key.value === 'string'))) {
+        const name = getNameFromIdentifierOrLiteral(node.parent.key);
+        if (name) {
+            return `object method "${name}"`;
+        }
+    }
+    return 'function expression';
+}
+function describeArrowFunction(node) {
+    if (node.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        node.parent.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return `arrow function "${node.parent.id.name}"`;
+    }
+    return 'arrow function';
+}
+function describeFunctionKind(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.MethodDefinition:
+            return describeClassMethod(node);
+        case utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition:
+            return describeClassMethod(node);
+        case utils_1.AST_NODE_TYPES.TSMethodSignature:
+            return describeMethodSignature(node);
+        case utils_1.AST_NODE_TYPES.TSDeclareFunction:
+            return describeTSDeclareFunction(node);
+        case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+            return describeFunctionDeclaration(node);
+        case utils_1.AST_NODE_TYPES.FunctionExpression:
+            return describeFunctionExpression(node);
+        case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+            return describeArrowFunction(node);
+        default:
+            return 'function';
+    }
+}
 function isRecursiveFunction(node) {
     const functionName = node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration
         ? node.id?.name
@@ -63,16 +155,52 @@ function isOverloadedFunction(node) {
         const interfaceBody = node.parent;
         if (interfaceBody.type !== utils_1.AST_NODE_TYPES.TSInterfaceBody)
             return false;
-        const methodName = node.key.type === utils_1.AST_NODE_TYPES.Identifier ? node.key.name : undefined;
+        if (node.computed)
+            return false;
+        const methodName = node.key.type === utils_1.AST_NODE_TYPES.Identifier ||
+            node.key.type === utils_1.AST_NODE_TYPES.Literal
+            ? getNameFromIdentifierOrLiteral(node.key)
+            : undefined;
         if (!methodName)
             return false;
         return (interfaceBody.body.filter((member) => member.type === utils_1.AST_NODE_TYPES.TSMethodSignature &&
-            member.key.type === utils_1.AST_NODE_TYPES.Identifier &&
-            member.key.name === methodName).length > 1);
+            !member.computed &&
+            (member.key.type === utils_1.AST_NODE_TYPES.Identifier ||
+                member.key.type === utils_1.AST_NODE_TYPES.Literal) &&
+            getNameFromIdentifierOrLiteral(member.key) === methodName).length > 1);
+    }
+    return false;
+}
+function isOverloadedTsDeclareFunction(node) {
+    const functionName = node.id?.name;
+    if (!functionName)
+        return false;
+    let container = node.parent;
+    while (container) {
+        if (container.type === utils_1.AST_NODE_TYPES.Program ||
+            container.type === utils_1.AST_NODE_TYPES.TSModuleBlock) {
+            const declarations = container.body
+                .map((statement) => {
+                if (statement.type === utils_1.AST_NODE_TYPES.TSDeclareFunction) {
+                    return statement;
+                }
+                if (statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                    statement.declaration?.type === utils_1.AST_NODE_TYPES.TSDeclareFunction) {
+                    return statement.declaration;
+                }
+                return undefined;
+            })
+                .filter((value) => Boolean(value?.id?.name))
+                .filter((decl) => decl.id.name === functionName);
+            return declarations.length > 1;
+        }
+        container = container.parent;
     }
     return false;
 }
 function isInterfaceOrAbstractMethodSignature(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.TSAbstractMethodDefinition)
+        return true;
     if (node.type === utils_1.AST_NODE_TYPES.TSMethodSignature)
         return true;
     if (node.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
@@ -133,7 +261,8 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
             },
         ],
         messages: {
-            noExplicitReturnType: 'Explicit return type is not allowed. Let TypeScript infer it.',
+            noExplicitReturnTypeInferable: "What's wrong: {{functionKind}} has an explicit return type annotation. \u2192 Why it matters: it must be updated manually and can drift from what the implementation actually returns, hiding bugs behind a stale type. \u2192 How to fix: remove the return type annotation so TypeScript infers it from the implementation.",
+            noExplicitReturnTypeNonInferable: "What's wrong: {{functionKind}} has an explicit return type annotation but no implementation body. \u2192 Why it matters: TypeScript cannot infer the return type here; removing it widens the return type to `any`. \u2192 How to fix: keep the annotation, or provide an implementation body where inference can succeed.",
         },
     },
     defaultOptions: [defaultOptions],
@@ -141,58 +270,77 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
         const mergedOptions = { ...defaultOptions, ...options };
         const filename = context.getFilename();
         if ((mergedOptions.allowDtsFiles && filename.endsWith('.d.ts')) ||
-            (mergedOptions.allowFirestoreFunctionFiles && filename.endsWith('.f.ts'))) {
+            (mergedOptions.allowFirestoreFunctionFiles &&
+                filename.endsWith('.f.ts'))) {
             return {};
         }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         function fixReturnType(fixer, node) {
-            const returnType = node.returnType || node.value?.returnType;
+            // Some nodes expose returnType directly while others nest it under value.
+            const returnType = 'returnType' in node
+                ? node.returnType
+                : 'value' in node
+                    ? node.value.returnType
+                    : null;
             if (!returnType)
                 return null;
-            // Create a fix that removes the return type annotation
             return fixer.remove(returnType);
         }
         return {
             FunctionDeclaration(node) {
-                if (!node.returnType)
+                const returnType = node.returnType;
+                if (!returnType)
                     return;
                 if (isTypeGuardFunction(node) ||
                     (mergedOptions.allowRecursiveFunctions && isRecursiveFunction(node))) {
                     return;
                 }
+                const isInferable = Boolean(node.body);
                 context.report({
-                    node: node.returnType,
-                    messageId: 'noExplicitReturnType',
-                    fix: (fixer) => fixReturnType(fixer, node),
+                    node: returnType,
+                    messageId: isInferable
+                        ? 'noExplicitReturnTypeInferable'
+                        : 'noExplicitReturnTypeNonInferable',
+                    data: { functionKind: describeFunctionKind(node) },
+                    ...(isInferable
+                        ? { fix: (fixer) => fixReturnType(fixer, node) }
+                        : {}),
                 });
             },
             FunctionExpression(node) {
-                if (!node.returnType)
+                const returnType = node.returnType;
+                if (!returnType)
+                    return;
+                if (node.parent?.type === utils_1.AST_NODE_TYPES.MethodDefinition) {
                     return;
+                }
                 if (isTypeGuardFunction(node) ||
                     (mergedOptions.allowRecursiveFunctions && isRecursiveFunction(node))) {
                     return;
                 }
                 context.report({
-                    node: node.returnType,
-                    messageId: 'noExplicitReturnType',
+                    node: returnType,
+                    messageId: 'noExplicitReturnTypeInferable',
+                    data: { functionKind: describeFunctionKind(node) },
                     fix: (fixer) => fixReturnType(fixer, node),
                 });
             },
             ArrowFunctionExpression(node) {
-                if (!node.returnType)
+                const returnType = node.returnType;
+                if (!returnType)
                     return;
                 if (isTypeGuardFunction(node)) {
                     return;
                 }
                 context.report({
-                    node: node.returnType,
-                    messageId: 'noExplicitReturnType',
+                    node: returnType,
+                    messageId: 'noExplicitReturnTypeInferable',
+                    data: { functionKind: describeFunctionKind(node) },
                     fix: (fixer) => fixReturnType(fixer, node),
                 });
             },
             TSMethodSignature(node) {
-                if (!node.returnType)
+                const returnType = node.returnType;
+                if (!returnType)
                     return;
                 if (mergedOptions.allowInterfaceMethodSignatures) {
                     return;
@@ -202,23 +350,64 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     return;
                 }
                 context.report({
-                    node: node.returnType,
-                    messageId: 'noExplicitReturnType',
-                    fix: (fixer) => fixReturnType(fixer, node),
+                    node: returnType,
+                    messageId: 'noExplicitReturnTypeNonInferable',
+                    data: { functionKind: describeFunctionKind(node) },
                 });
             },
             MethodDefinition(node) {
-                if (!node.value.returnType)
+                const returnType = node.value.returnType;
+                if (!returnType)
                     return;
                 if (isTypeGuardFunction(node.value) ||
                     (mergedOptions.allowAbstractMethodSignatures &&
                         isInterfaceOrAbstractMethodSignature(node))) {
                     return;
                 }
+                const isInferable = Boolean(node.value.body);
                 context.report({
-                    node: node.value.returnType,
-                    messageId: 'noExplicitReturnType',
-                    fix: (fixer) => fixReturnType(fixer, node),
+                    node: returnType,
+                    messageId: isInferable
+                        ? 'noExplicitReturnTypeInferable'
+                        : 'noExplicitReturnTypeNonInferable',
+                    data: { functionKind: describeFunctionKind(node) },
+                    ...(isInferable
+                        ? { fix: (fixer) => fixReturnType(fixer, node) }
+                        : {}),
+                });
+            },
+            TSAbstractMethodDefinition(node) {
+                const returnType = node.value.returnType;
+                if (!returnType)
+                    return;
+                if (isTypeGuardFunction(node.value) ||
+                    (mergedOptions.allowAbstractMethodSignatures &&
+                        isInterfaceOrAbstractMethodSignature(node))) {
+                    return;
+                }
+                // Abstract methods never have bodies; they are always non-inferable and
+                // intentionally have no fixer.
+                context.report({
+                    node: returnType,
+                    messageId: 'noExplicitReturnTypeNonInferable',
+                    data: { functionKind: describeFunctionKind(node) },
+                });
+            },
+            TSDeclareFunction(node) {
+                const returnType = node.returnType;
+                if (!returnType)
+                    return;
+                if (isTypeGuardFunction(node)) {
+                    return;
+                }
+                if (mergedOptions.allowOverloadedFunctions &&
+                    isOverloadedTsDeclareFunction(node)) {
+                    return;
+                }
+                context.report({
+                    node: returnType,
+                    messageId: 'noExplicitReturnTypeNonInferable',
+                    data: { functionKind: describeFunctionKind(node) },
                 });
             },
         };

package/lib/rules/no-filter-without-return.js

@@ -15,9 +15,13 @@ exports.noFilterWithoutReturn = (0, createRule_1.createRule)({
                         return;
                     }
                     if (!ASTHelpers_1.ASTHelpers.hasReturnStatement(body)) {
+                        const filterCall = context.getSourceCode().getText(node.callee);
                         context.report({
                             node,
                             messageId: 'unexpected',
+                            data: {
+                                filterCall,
+                            },
                         });
                     }
                 }
@@ -33,7 +37,7 @@ exports.noFilterWithoutReturn = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            unexpected: 'Array.filter callbacks with block statements must contain a return statement. Instead of `array.filter(x => { doSomething(x); })`, use `array.filter(x => { doSomething(x); return someCondition; })` or use implicit return `array.filter(x => someCondition)`.',
+            unexpected: 'Callback for {{filterCall}} uses braces but never returns a value, so filter receives undefined for every element and silently drops them all. Return the predicate result from inside the block (e.g., "return matches(item);") or use a concise arrow like {{filterCall}}((item) => matches(item)) to make the keep/remove condition explicit.',
         },
     },
     defaultOptions: [],

package/lib/rules/no-firestore-jest-mock.d.ts

@@ -1 +1,2 @@
-export declare const noFirestoreJestMock: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"noFirestoreJestMock", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+import type { TSESLint } from '@typescript-eslint/utils';
+export declare const noFirestoreJestMock: TSESLint.RuleModule<"noFirestoreJestMock", [], TSESLint.RuleListener>;

package/lib/rules/no-firestore-jest-mock.js

@@ -1,8 +1,90 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noFirestoreJestMock = void 0;
+const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const FIRESTORE_JEST_MOCK = 'firestore-jest-mock';
+const MOCK_FIRESTORE_TARGET = '__test-utils__/mockFirestore';
+const toPosixPath = (filePath) => filePath.replace(/\\/g, '/');
+const ensureRelativeSpecifier = (specifier) => specifier.startsWith('.') ? specifier : `./${specifier}`;
+const isWindowsDrivePath = (filePath) => /^[A-Za-z]:[\\/]/.test(filePath);
+const isValidRelativePath = (relativePath) => !path_1.default.isAbsolute(relativePath) && !isWindowsDrivePath(relativePath);
+const buildReplacementPath = (sourceFilePath, cwd) => {
+    const absoluteFilename = path_1.default.isAbsolute(sourceFilePath)
+        ? sourceFilePath
+        : path_1.default.join(cwd, sourceFilePath);
+    const targetPath = path_1.default.join(cwd, MOCK_FIRESTORE_TARGET);
+    const relativePath = path_1.default.relative(path_1.default.dirname(absoluteFilename), targetPath);
+    if (!isValidRelativePath(relativePath)) {
+        return '';
+    }
+    return ensureRelativeSpecifier(toPosixPath(relativePath));
+};
+const findVariableDeclarator = (node) => {
+    const { parent } = node;
+    if (parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
+        return parent;
+    }
+    if (parent?.type === utils_1.AST_NODE_TYPES.AwaitExpression &&
+        parent.parent?.type === utils_1.AST_NODE_TYPES.VariableDeclarator) {
+        return parent.parent;
+    }
+    return null;
+};
+const buildDestructuringFix = (fixer, pattern) => {
+    if (pattern.properties.length !== 1) {
+        return null;
+    }
+    const [property] = pattern.properties;
+    if (property.type !== utils_1.AST_NODE_TYPES.Property) {
+        return null;
+    }
+    if (property.value.type === utils_1.AST_NODE_TYPES.AssignmentPattern) {
+        return null;
+    }
+    if (property.value.type !== utils_1.AST_NODE_TYPES.Identifier) {
+        return null;
+    }
+    const localName = property.value.name;
+    const replacement = localName === 'mockFirestore'
+        ? '{ mockFirestore }'
+        : `{ mockFirestore: ${localName} }`;
+    return fixer.replaceText(pattern, replacement);
+};
+const constructImportStatement = (localName, replacementPath) => {
+    const binding = localName === 'mockFirestore'
+        ? 'mockFirestore'
+        : `mockFirestore as ${localName}`;
+    return `import { ${binding} } from '${replacementPath}';`;
+};
+const getSingleValueImportSpecifier = (node) => {
+    const valueSpecifiers = node.specifiers.filter((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        specifier.importKind !== 'type');
+    const hasTypeSpecifiers = node.specifiers.some((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        specifier.importKind === 'type');
+    const hasUnsupportedSpecifier = node.specifiers.some((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
+        specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier);
+    if (valueSpecifiers.length !== 1 ||
+        hasTypeSpecifiers ||
+        hasUnsupportedSpecifier) {
+        return null;
+    }
+    return valueSpecifiers[0];
+};
+const buildImportDeclarationFix = (node, replacementPath) => {
+    if (!replacementPath) {
+        return null;
+    }
+    const specifier = getSingleValueImportSpecifier(node);
+    if (!specifier) {
+        return null;
+    }
+    return constructImportStatement(specifier.local.name, replacementPath);
+};
 exports.noFirestoreJestMock = (0, createRule_1.createRule)({
     name: 'no-firestore-jest-mock',
     meta: {
@@ -14,38 +96,72 @@ exports.noFirestoreJestMock = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            noFirestoreJestMock: 'Do not import from firestore-jest-mock. Use mockFirestore from the centralized mock utility instead.',
+            noFirestoreJestMock: 'What\'s wrong: This test imports "{{moduleName}}" directly → Why it matters: it bypasses the centralized mockFirestore helper that mirrors production schema and keeps seeding/cleanup consistent, which leads to inconsistent data and flaky tests → How to fix: import { mockFirestore } from "{{replacementPath}}" instead.',
         },
     },
     defaultOptions: [],
     create(context) {
-        const filename = context.getFilename();
+        const sourceFilePath = context.getFilename();
         // Only apply rule to test files
-        if (!filename.endsWith('.test.ts')) {
+        if (!sourceFilePath.endsWith('.test.ts')) {
             return {};
         }
+        const cwd = typeof context.getCwd === 'function' ? context.getCwd() : process.cwd();
+        const replacementPath = buildReplacementPath(sourceFilePath, cwd);
+        const messageReplacementPath = replacementPath ||
+            ensureRelativeSpecifier(toPosixPath(MOCK_FIRESTORE_TARGET));
+        const reportData = {
+            moduleName: FIRESTORE_JEST_MOCK,
+            replacementPath: messageReplacementPath,
+        };
         return {
             ImportDeclaration(node) {
                 // Skip type imports completely
                 if (node.importKind === 'type') {
                     return;
                 }
-                if (node.source.value === 'firestore-jest-mock') {
+                if (node.source.value === FIRESTORE_JEST_MOCK) {
                     context.report({
                         node,
                         messageId: 'noFirestoreJestMock',
+                        data: reportData,
                         fix: (fixer) => {
-                            return fixer.replaceText(node, `import { mockFirestore } from '../../../../../__test-utils__/mockFirestore';`);
+                            const replacementImport = buildImportDeclarationFix(node, replacementPath);
+                            if (!replacementImport) {
+                                return null;
+                            }
+                            return fixer.replaceText(node, replacementImport);
                         },
                     });
                 }
             },
             ImportExpression(node) {
                 if (node.source.type === utils_1.AST_NODE_TYPES.Literal &&
-                    node.source.value === 'firestore-jest-mock') {
+                    node.source.value === FIRESTORE_JEST_MOCK) {
+                    const variableDeclarator = findVariableDeclarator(node);
                     context.report({
                         node,
                         messageId: 'noFirestoreJestMock',
+                        data: reportData,
+                        fix: (fixer) => {
+                            if (!replacementPath) {
+                                return null;
+                            }
+                            if (!variableDeclarator) {
+                                return null;
+                            }
+                            if (variableDeclarator.id.type !== utils_1.AST_NODE_TYPES.ObjectPattern) {
+                                return null;
+                            }
+                            const destructuringFix = buildDestructuringFix(fixer, variableDeclarator.id);
+                            if (!destructuringFix) {
+                                return null;
+                            }
+                            return [
+                                fixer.replaceText(node.source, `'${replacementPath}'`),
+                                destructuringFix,
+                            ];
+                        },
                     });
                 }
             },
@@ -58,10 +174,11 @@ exports.noFirestoreJestMock = (0, createRule_1.createRule)({
                     node.callee.property.name === 'mock' &&
                     node.arguments.length > 0 &&
                     node.arguments[0].type === utils_1.AST_NODE_TYPES.Literal &&
-                    node.arguments[0].value === 'firestore-jest-mock') {
+                    node.arguments[0].value === FIRESTORE_JEST_MOCK) {
                     context.report({
                         node,
                         messageId: 'noFirestoreJestMock',
+                        data: reportData,
                     });
                 }
                 // Check for require('firestore-jest-mock')
@@ -69,10 +186,11 @@ exports.noFirestoreJestMock = (0, createRule_1.createRule)({
                     node.callee.name === 'require' &&
                     node.arguments.length > 0 &&
                     node.arguments[0].type === utils_1.AST_NODE_TYPES.Literal &&
-                    node.arguments[0].value === 'firestore-jest-mock') {
+                    node.arguments[0].value === FIRESTORE_JEST_MOCK) {
                     context.report({
                         node,
                         messageId: 'noFirestoreJestMock',
+                        data: reportData,
                     });
                 }
             },