@blumintinc/eslint-plugin-blumint 1.12.6 → 1.14.0

package/lib/rules/semantic-function-prefixes.js

@@ -24,17 +24,43 @@ const SUGGESTED_ALTERNATIVES = {
     process: ['transform', 'sanitize', 'compute'],
     do: ['execute', 'perform', 'apply'],
 };
+function extractFirstWord(name) {
+    let firstWord = name;
+    for (let i = 1; i < name.length; i++) {
+        const currentChar = name[i];
+        const prevChar = name[i - 1];
+        // lowercase -> Uppercase (camel/Pascal boundary)
+        if (prevChar >= 'a' &&
+            prevChar <= 'z' &&
+            currentChar >= 'A' &&
+            currentChar <= 'Z') {
+            firstWord = name.substring(0, i);
+            break;
+        }
+        // UPPERCASE acronym -> lowercase word start (e.g., XML|Http)
+        if (prevChar >= 'A' &&
+            prevChar <= 'Z' &&
+            currentChar >= 'a' &&
+            currentChar <= 'z') {
+            if (i > 1) {
+                firstWord = name.substring(0, i - 1);
+                break;
+            }
+        }
+    }
+    return firstWord;
+}
 exports.semanticFunctionPrefixes = (0, createRule_1.createRule)({
     name: 'semantic-function-prefixes',
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce semantic function prefixes over generic ones like "get" and "update"',
+            description: 'Require semantic function prefixes instead of generic verbs so callers know whether a function fetches data, transforms input, or mutates state',
             recommended: 'error',
         },
         schema: [],
         messages: {
-            avoidGenericPrefix: 'Avoid using generic prefix "{{prefix}}". Consider using one of these alternatives: {{alternatives}}',
+            avoidGenericPrefix: 'Function "{{functionName}}" starts with the generic prefix "{{prefix}}", which hides whether it fetches remote data, transforms input, or mutates state. Use a semantic verb such as {{alternatives}} to describe the operation and set caller expectations.',
         },
     },
     defaultOptions: [],
@@ -54,20 +80,17 @@ exports.semanticFunctionPrefixes = (0, createRule_1.createRule)({
             if (NEXTJS_DATA_FUNCTIONS.has(methodName))
                 return;
             // Extract first word from PascalCase/camelCase
-            let firstWord = methodName;
-            for (let i = 1; i < methodName.length; i++) {
-                if (methodName[i] >= 'A' && methodName[i] <= 'Z') {
-                    firstWord = methodName.substring(0, i);
-                    break;
-                }
-            }
+            const firstWord = extractFirstWord(methodName);
             // Check for disallowed prefixes
+            // Only flag if the disallowed word is used as a prefix (not the entire name)
             for (const prefix of DISALLOWED_PREFIXES) {
-                if (firstWord.toLowerCase() === prefix.toLowerCase()) {
+                if (firstWord.toLowerCase() === prefix.toLowerCase() &&
+                    firstWord.length < methodName.length) {
                     context.report({
                         node: node.key,
                         messageId: 'avoidGenericPrefix',
                         data: {
+                            functionName: methodName,
                             prefix,
                             alternatives: SUGGESTED_ALTERNATIVES[prefix].join(', '),
                         },
@@ -99,20 +122,17 @@ exports.semanticFunctionPrefixes = (0, createRule_1.createRule)({
             if (NEXTJS_DATA_FUNCTIONS.has(functionName))
                 return;
             // Extract first word from PascalCase/camelCase
-            let firstWord = functionName;
-            for (let i = 1; i < functionName.length; i++) {
-                if (functionName[i] >= 'A' && functionName[i] <= 'Z') {
-                    firstWord = functionName.substring(0, i);
-                    break;
-                }
-            }
+            const firstWord = extractFirstWord(functionName);
             // Check for disallowed prefixes
+            // Only flag if the disallowed word is used as a prefix (not the entire name)
             for (const prefix of DISALLOWED_PREFIXES) {
-                if (firstWord.toLowerCase() === prefix.toLowerCase()) {
+                if (firstWord.toLowerCase() === prefix.toLowerCase() &&
+                    firstWord.length < functionName.length) {
                     context.report({
                         node: node.id || node,
                         messageId: 'avoidGenericPrefix',
                         data: {
+                            functionName,
                             prefix,
                             alternatives: SUGGESTED_ALTERNATIVES[prefix].join(', '),
                         },

package/lib/rules/sync-onwrite-name-func.js

@@ -14,7 +14,7 @@ exports.syncOnwriteNameFunc = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            mismatchedName: 'The name field should match the func field in onWrite handlers',
+            mismatchedName: 'OnWrite handler name "{{nameValue}}" does not match func reference "{{funcName}}". The name field is what gets registered for deploys, logs, and alerts, so a mismatch hides which function is actually running. Rename the "name" value to "{{funcName}}" or point "func" to a function named "{{nameValue}}" so the trigger label and implementation stay in sync.',
         },
     },
     defaultOptions: [],
@@ -68,6 +68,10 @@ exports.syncOnwriteNameFunc = (0, createRule_1.createRule)({
                         context.report({
                             node: nameProperty,
                             messageId: 'mismatchedName',
+                            data: {
+                                nameValue,
+                                funcName,
+                            },
                             fix(fixer) {
                                 return fixer.replaceText(value, `'${funcName}'`);
                             },

package/lib/rules/test-file-location-enforcement.d.ts

@@ -0,0 +1 @@
+export declare const testFileLocationEnforcement: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"misplacedTestFile", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;

package/lib/rules/test-file-location-enforcement.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testFileLocationEnforcement = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const createRule_1 = require("../utils/createRule");
+const TEST_FILE_PATTERN = /\.test\.tsx?$/i;
+const SUPPORTED_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+exports.testFileLocationEnforcement = (0, createRule_1.createRule)({
+    name: 'test-file-location-enforcement',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce colocating *.test.ts or *.test.tsx files with the code they cover.',
+            recommended: 'error',
+        },
+        schema: [],
+        messages: {
+            misplacedTestFile: 'Test file "{{testFile}}" is not colocated with its subject. Keep tests in the same directory as {{expectedNames}} so refactors move code and coverage together and engineers can find the implementation without searching separate test folders.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            Program(node) {
+                const filename = context.getFilename();
+                if (filename === '<input>' ||
+                    filename === '<text>' ||
+                    filename.includes('node_modules') ||
+                    !TEST_FILE_PATTERN.test(filename)) {
+                    return;
+                }
+                const directory = path_1.default.dirname(filename);
+                const testFileName = path_1.default.basename(filename);
+                const baseName = testFileName.replace(TEST_FILE_PATTERN, '');
+                const candidates = SUPPORTED_EXTENSIONS.map((extension) => path_1.default.join(directory, `${baseName}${extension}`));
+                const hasSibling = candidates.some((candidate) => fs_1.default.existsSync(candidate));
+                if (hasSibling) {
+                    return;
+                }
+                const relativePath = path_1.default.isAbsolute(filename)
+                    ? path_1.default.relative(process.cwd(), filename) || filename
+                    : filename;
+                const expectedNames = SUPPORTED_EXTENSIONS.map((extension) => `"${baseName}${extension}"`).join(' or ');
+                context.report({
+                    node,
+                    messageId: 'misplacedTestFile',
+                    data: { testFile: relativePath, expectedNames },
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=test-file-location-enforcement.js.map

package/lib/rules/use-custom-link.js

@@ -13,7 +13,7 @@ exports.useCustomLink = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            useCustomLink: 'Import Link from src/components/Link instead of next/link',
+            useCustomLink: 'Import "{{localName}}" from src/components/Link instead of next/link. The custom Link wraps Next.js navigation with design system defaults and analytics hooks; importing next/link bypasses those wrappers and leads to inconsistent styling and missing instrumentation. Replace the import source with src/components/Link so routing uses the shared wrapper.',
         },
     },
     defaultOptions: [],
@@ -30,6 +30,11 @@ exports.useCustomLink = (0, createRule_1.createRule)({
                         context.report({
                             node,
                             messageId: 'useCustomLink',
+                            data: {
+                                localName: defaultSpecifier?.local?.name ||
+                                    defaultAsSpecifier?.local?.name ||
+                                    'Link',
+                            },
                             fix(fixer) {
                                 // Get the local name of the imported Link component
                                 const localName = defaultSpecifier?.local?.name ||

package/lib/rules/use-custom-router.js

@@ -14,7 +14,7 @@ exports.useCustomRouter = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            useCustomRouter: 'Import useRouter from src/hooks/routing/useRouter instead of next/router',
+            useCustomRouter: 'useRouter import "{{imports}}" comes from next/router, which bypasses the app-specific hook that applies auth checks, analytics, and redirect helpers. Import it from src/hooks/routing/useRouter so routing code stays consistent with the rest of the app.',
         },
     },
     defaultOptions: [],
@@ -29,6 +29,11 @@ exports.useCustomRouter = (0, createRule_1.createRule)({
                         context.report({
                             node,
                             messageId: 'useCustomRouter',
+                            data: {
+                                imports: specifiers
+                                    .map((specifier) => specifier.local.name)
+                                    .join(', '),
+                            },
                             fix(fixer) {
                                 // If there are other imports from next/router, keep them
                                 const otherSpecifiers = node.specifiers.filter((specifier) => specifier.type !== utils_1.AST_NODE_TYPES.ImportSpecifier ||

package/lib/rules/use-latest-callback.d.ts

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

package/lib/rules/use-latest-callback.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLatestCallback = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+exports.useLatestCallback = (0, createRule_1.createRule)({
+    name: 'use-latest-callback',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce using useLatestCallback from use-latest-callback instead of React useCallback',
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [],
+        messages: {
+            useLatestCallback: 'Replace {{currentHook}} with {{recommendedHook}} from "use-latest-callback" so the callback keeps a stable reference while still reading the latest props/state. useCallback recreates functions whenever dependencies change, which can trigger needless renders and stale closures. Drop the dependency array when switching to {{recommendedHook}}.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const filename = context.getFilename();
+        if (filename.includes('/node_modules/')) {
+            return {};
+        }
+        // Track if the file already has a useLatestCallback import
+        let hasUseLatestCallbackImport = false;
+        let useLatestCallbackImportName = 'useLatestCallback';
+        // Track if any useCallback calls should be replaced
+        let hasNonJsxUseCallbacks = false;
+        const useCallbackLocalNames = new Set();
+        const reactNamespaceNames = new Set();
+        const reactDefaultLikeNames = new Set();
+        let hasReactMemberUseCallback = false;
+        const isJSXLikeReturn = (node) => {
+            if (!node)
+                return false;
+            if (node.type === utils_1.AST_NODE_TYPES.JSXElement ||
+                node.type === utils_1.AST_NODE_TYPES.JSXFragment ||
+                node.type === utils_1.AST_NODE_TYPES.JSXExpressionContainer) {
+                return true;
+            }
+            if (node.type === 'ParenthesizedExpression') {
+                return isJSXLikeReturn(node.expression);
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.SequenceExpression) {
+                return isJSXLikeReturn(node.expressions[node.expressions.length - 1]);
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+                return node.elements.some((el) => isJSXLikeReturn(el && el.type === utils_1.AST_NODE_TYPES.SpreadElement
+                    ? el.argument
+                    : el));
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
+                return (isJSXLikeReturn(node.consequent) || isJSXLikeReturn(node.alternate));
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.LogicalExpression) {
+                return isJSXLikeReturn(node.left) || isJSXLikeReturn(node.right);
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                    node.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    reactNamespaceNames.has(node.callee.object.name) &&
+                    node.callee.property.name === 'createElement') {
+                    return true;
+                }
+            }
+            return false;
+        };
+        return {
+            // First pass: check imports
+            ImportDeclaration(node) {
+                if (node.importKind && node.importKind !== 'value')
+                    return;
+                if (node.source.value === 'use-latest-callback') {
+                    // Check if useLatestCallback is imported
+                    const specifiers = node.specifiers.filter((specifier) => {
+                        if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                            return (specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                specifier.imported.name === 'useLatestCallback');
+                        }
+                        return (specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
+                            specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier);
+                    });
+                    if (specifiers.length > 0) {
+                        hasUseLatestCallbackImport = true;
+                        // Get the local name of the import (in case it's renamed)
+                        if (specifiers[0].type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                            useLatestCallbackImportName = specifiers[0].local.name;
+                        }
+                        else if (specifiers[0].type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier) {
+                            useLatestCallbackImportName = specifiers[0].local.name;
+                        }
+                        else if (specifiers[0].type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+                            useLatestCallbackImportName = `${specifiers[0].local.name}.useLatestCallback`;
+                        }
+                    }
+                }
+                else if (node.source.value === 'react') {
+                    // Check if useCallback is imported from React
+                    const useCallbackSpecifiers = node.specifiers.filter((specifier) => {
+                        return (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                            specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                            specifier.imported.name === 'useCallback');
+                    });
+                    node.specifiers.forEach((specifier) => {
+                        if (specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
+                            specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+                            reactNamespaceNames.add(specifier.local.name);
+                            reactDefaultLikeNames.add(specifier.local.name);
+                        }
+                    });
+                    if (useCallbackSpecifiers.length > 0) {
+                        useCallbackSpecifiers.forEach((spec) => {
+                            useCallbackLocalNames.add(spec.local.name);
+                        });
+                    }
+                }
+            },
+            // Check for useCallback usage and identify JSX-returning callbacks
+            CallExpression(node) {
+                const isUseCallbackIdentifierCall = node.callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    useCallbackLocalNames.has(node.callee.name);
+                const isUseCallbackMemberCall = node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                    node.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    reactDefaultLikeNames.has(node.callee.object.name) &&
+                    node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    node.callee.property.name === 'useCallback';
+                if ((isUseCallbackIdentifierCall || isUseCallbackMemberCall) &&
+                    node.arguments.length >= 1) {
+                    if (isUseCallbackMemberCall) {
+                        hasReactMemberUseCallback = true;
+                    }
+                    // Check if this is a JSX-returning callback (edge case where we shouldn't replace)
+                    const callback = node.arguments[0];
+                    let isJsxReturning = false;
+                    if ((callback.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                        callback.type === utils_1.AST_NODE_TYPES.FunctionExpression) &&
+                        callback.body) {
+                        // For arrow functions with implicit return
+                        if (callback.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+                            if (isJSXLikeReturn(callback.body)) {
+                                isJsxReturning = true;
+                            }
+                        }
+                        // For functions with block body - check all return statements
+                        else if (callback.body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+                            const returnStatements = callback.body.body.filter((statement) => statement.type === utils_1.AST_NODE_TYPES.ReturnStatement);
+                            // If there are return statements, check if any return JSX
+                            if (returnStatements.length > 0) {
+                                isJsxReturning = returnStatements.some((returnStatement) => returnStatement.argument &&
+                                    isJSXLikeReturn(returnStatement.argument));
+                            }
+                        }
+                    }
+                    if (!isJsxReturning) {
+                        hasNonJsxUseCallbacks = true;
+                        const currentCallbackName = node.callee.type === utils_1.AST_NODE_TYPES.Identifier
+                            ? node.callee.name
+                            : node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                                node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier
+                                ? node.callee.property.name
+                                : 'useCallback';
+                        const replacementName = hasUseLatestCallbackImport
+                            ? useLatestCallbackImportName
+                            : currentCallbackName === 'useCallback'
+                                ? 'useLatestCallback'
+                                : currentCallbackName;
+                        // Report the useCallback call for replacement
+                        context.report({
+                            node,
+                            messageId: 'useLatestCallback',
+                            data: {
+                                currentHook: currentCallbackName,
+                                recommendedHook: replacementName,
+                            },
+                            fix(fixer) {
+                                const sourceCode = context.sourceCode;
+                                const callbackText = sourceCode.getText(node.arguments[0]);
+                                const typeParams = node.typeParameters
+                                    ? sourceCode.getText(node.typeParameters)
+                                    : '';
+                                // Replace useCallback with useLatestCallback and remove the dependency array
+                                return fixer.replaceText(node, `${replacementName}${typeParams}(${callbackText})`);
+                            },
+                        });
+                    }
+                }
+            },
+            // Final pass: check for useCallback import from react (only if there are non-JSX callbacks)
+            'Program:exit'() {
+                if (!hasNonJsxUseCallbacks) {
+                    return; // Don't modify imports if all useCallback calls return JSX
+                }
+                const sourceCode = context.sourceCode;
+                const program = sourceCode.ast;
+                for (const statement of program.body) {
+                    if (statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
+                        statement.source.value === 'react') {
+                        if (statement.importKind && statement.importKind !== 'value') {
+                            continue;
+                        }
+                        const specifiers = statement.specifiers.filter((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                            specifier.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                            specifier.imported.name === 'useCallback');
+                        if (specifiers.length > 0 || hasReactMemberUseCallback) {
+                            const useCallbackLocalName = specifiers[0]?.local.name ?? 'useCallback';
+                            const recommendedHook = hasUseLatestCallbackImport
+                                ? useLatestCallbackImportName
+                                : useCallbackLocalName === 'useCallback'
+                                    ? 'useLatestCallback'
+                                    : useCallbackLocalName;
+                            context.report({
+                                node: statement,
+                                messageId: 'useLatestCallback',
+                                data: {
+                                    currentHook: useCallbackLocalName,
+                                    recommendedHook,
+                                },
+                                fix(fixer) {
+                                    const importText = `import ${useCallbackLocalName === 'useCallback'
+                                        ? 'useLatestCallback'
+                                        : useCallbackLocalName} from 'use-latest-callback';`;
+                                    if (specifiers.length === 0) {
+                                        if (hasUseLatestCallbackImport)
+                                            return null;
+                                        return fixer.insertTextBefore(statement, `${importText}\n`);
+                                    }
+                                    const defaultOrNamespace = statement.specifiers.find((s) => s.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
+                                        s.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier);
+                                    const remainingNamed = statement.specifiers.filter((s) => s.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                                        s.imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                        s.imported.name !== 'useCallback');
+                                    const prefix = statement.importKind && statement.importKind !== 'value'
+                                        ? 'import type'
+                                        : 'import';
+                                    if (remainingNamed.length === 0 && !defaultOrNamespace) {
+                                        if (!hasUseLatestCallbackImport) {
+                                            return fixer.replaceText(statement, importText);
+                                        }
+                                        return fixer.remove(statement);
+                                    }
+                                    const parts = [];
+                                    if (defaultOrNamespace) {
+                                        parts.push(sourceCode.getText(defaultOrNamespace));
+                                    }
+                                    if (remainingNamed.length > 0) {
+                                        parts.push(`{ ${remainingNamed
+                                            .map((s) => sourceCode.getText(s))
+                                            .join(', ')} }`);
+                                    }
+                                    const replacement = `${prefix} ${parts.join(', ')} from 'react';`;
+                                    const fixes = [];
+                                    if (!hasUseLatestCallbackImport) {
+                                        fixes.push(fixer.insertTextBefore(statement, `${importText}\n`));
+                                    }
+                                    fixes.push(fixer.replaceText(statement, replacement));
+                                    return fixes;
+                                },
+                            });
+                        }
+                        break;
+                    }
+                }
+            },
+        };
+    },
+});
+exports.default = exports.useLatestCallback;
+//# sourceMappingURL=use-latest-callback.js.map

package/lib/rules/vertically-group-related-functions.d.ts

@@ -0,0 +1,16 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type GroupName = 'event-handlers' | 'utilities' | 'other';
+type DependencyDirection = 'callers-first' | 'callees-first';
+type ExportPlacement = 'top' | 'bottom' | 'ignore';
+type Options = [
+    Partial<{
+        exportPlacement: ExportPlacement;
+        dependencyDirection: DependencyDirection;
+        groupOrder: GroupName[];
+        eventHandlerPattern: string;
+        utilityPattern: string;
+    }>
+];
+type MessageIds = 'misorderedFunction';
+export declare const verticallyGroupRelatedFunctions: TSESLint.RuleModule<MessageIds, Options>;
+export {};