@blumintinc/eslint-plugin-blumint 1.14.0 → 1.16.0

package/lib/rules/memo-nested-react-components.js

@@ -4,12 +4,12 @@ exports.memoNestedReactComponents = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const minimatch_1 = require("minimatch");
 const createRule_1 = require("../utils/createRule");
-const ASTHelpers_1 = require("../utils/ASTHelpers");
-const CALLBACK_HOOKS = new Set(['useCallback', 'useDeepCompareCallback']);
-const HOOK_REPLACEMENT = {
-    useCallback: 'useMemo',
-    useDeepCompareCallback: 'useDeepCompareMemo',
-};
+const CALLBACK_HOOKS = new Set([
+    'useCallback',
+    'useDeepCompareCallback',
+    'useMemo',
+    'useDeepCompareMemo',
+]);
 const collectReactImports = (sourceCode) => {
     const reactImports = { namespace: null, named: {} };
     for (const statement of sourceCode.ast.body) {
@@ -252,24 +252,142 @@ const getVariableName = (node) => {
     }
     return null;
 };
-const findMemoReference = (reactImports) => {
-    if (reactImports.namespace) {
-        return `${reactImports.namespace}.memo`;
+const isEnclosingFunction = (node) => {
+    return (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration);
+};
+/**
+ * Nearest ancestor function whose body directly contains `node`. Climbs from
+ * the node's parent so a function node itself is not treated as its own
+ * enclosing function.
+ */
+const findEnclosingFunction = (node) => {
+    let parent = node.parent;
+    while (parent) {
+        if (isEnclosingFunction(parent)) {
+            return parent;
+        }
+        parent = parent.parent;
     }
-    return reactImports.named.memo ?? null;
+    return null;
+};
+const isInsideFunction = (node) => {
+    return findEnclosingFunction(node) !== null;
 };
-const hasIdentifierInScope = (identifierName, scope) => {
-    return !!ASTHelpers_1.ASTHelpers.findVariableInScope(scope, identifierName);
+const isPascalCaseName = (name) => /^[A-Z]/.test(name);
+/**
+ * A return value is a *component* (vs. rendered output) when it is a
+ * memo()/forwardRef() call, a PascalCase identifier (returned component
+ * reference), or an inline function that itself creates a component. Such a
+ * value identifies the surrounding function as an HOC factory rather than a
+ * render body.
+ */
+const returnExpressionIsComponent = (expression, reactImports) => {
+    if (!expression) {
+        return false;
+    }
+    const unwrapped = unwrapExpression(expression);
+    if (unwrapped.type === utils_1.AST_NODE_TYPES.CallExpression) {
+        if (isMemoCall(unwrapped, reactImports) ||
+            isForwardRefCall(unwrapped, reactImports)) {
+            return true;
+        }
+        return false;
+    }
+    if (unwrapped.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return isPascalCaseName(unwrapped.name);
+    }
+    if (isFunctionExpression(unwrapped)) {
+        return Boolean(functionCreatesComponent(unwrapped, reactImports));
+    }
+    return false;
+};
+const returnExpressionIsJsx = (expression) => {
+    if (!expression) {
+        return false;
+    }
+    const unwrapped = unwrapExpression(expression);
+    return (unwrapped.type === utils_1.AST_NODE_TYPES.JSXElement ||
+        unwrapped.type === utils_1.AST_NODE_TYPES.JSXFragment);
+};
+/**
+ * Direct return-statement arguments of a function, traversing control flow
+ * (if/switch/try/loops) but NOT descending into nested function definitions—
+ * returns inside nested functions belong to those functions, not this one.
+ */
+const collectDirectReturnExpressions = (fn) => {
+    if (fn.body.type !== utils_1.AST_NODE_TYPES.BlockStatement) {
+        return [fn.body];
+    }
+    const returns = [];
+    const visitStatement = (statement) => {
+        switch (statement.type) {
+            case utils_1.AST_NODE_TYPES.ReturnStatement:
+                returns.push(statement.argument);
+                break;
+            case utils_1.AST_NODE_TYPES.BlockStatement:
+                statement.body.forEach(visitStatement);
+                break;
+            case utils_1.AST_NODE_TYPES.IfStatement:
+                visitStatement(statement.consequent);
+                if (statement.alternate) {
+                    visitStatement(statement.alternate);
+                }
+                break;
+            case utils_1.AST_NODE_TYPES.SwitchStatement:
+                for (const switchCase of statement.cases) {
+                    switchCase.consequent.forEach(visitStatement);
+                }
+                break;
+            case utils_1.AST_NODE_TYPES.ForStatement:
+            case utils_1.AST_NODE_TYPES.ForInStatement:
+            case utils_1.AST_NODE_TYPES.ForOfStatement:
+            case utils_1.AST_NODE_TYPES.WhileStatement:
+            case utils_1.AST_NODE_TYPES.DoWhileStatement:
+                visitStatement(statement.body);
+                break;
+            case utils_1.AST_NODE_TYPES.TryStatement:
+                visitStatement(statement.block);
+                if (statement.handler) {
+                    visitStatement(statement.handler.body);
+                }
+                if (statement.finalizer) {
+                    visitStatement(statement.finalizer);
+                }
+                break;
+            default:
+                break;
+        }
+    };
+    fn.body.body.forEach(visitStatement);
+    return returns;
+};
+/**
+ * True when the nearest enclosing function is an HOC factory—it returns a
+ * component (memo/forwardRef/component reference) and never returns JSX. Such
+ * a function runs once per call, so components defined inside it have stable
+ * identities and must NOT be flagged. A function that returns JSX is a render
+ * body, where nested components DO remount and remain flagged.
+ */
+const isInsideHocFactory = (node, reactImports) => {
+    const enclosing = findEnclosingFunction(node);
+    if (!enclosing) {
+        return false;
+    }
+    const returns = collectDirectReturnExpressions(enclosing);
+    const returnsComponent = returns.some((expression) => returnExpressionIsComponent(expression, reactImports));
+    const returnsJsx = returns.some((expression) => returnExpressionIsJsx(expression));
+    return returnsComponent && !returnsJsx;
 };
 exports.memoNestedReactComponents = (0, createRule_1.createRule)({
     name: 'memo-nested-react-components',
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Disallow React components defined in useCallback/useDeepCompareCallback',
+            description: 'Disallow React components defined in render bodies, hooks, or passed as props',
             recommended: 'error',
         },
-        fixable: 'code',
         schema: [
             {
                 type: 'object',
@@ -284,9 +402,19 @@ exports.memoNestedReactComponents = (0, createRule_1.createRule)({
             },
         ],
         messages: {
-            memoizeNestedComponent: `What's wrong: React component "{{componentName}}" is created inside {{hookName}}.
-Why it matters: Components defined inside callbacks get new identities when the callback changes, causing React to remount them and drop their state and effects.
-How to fix: Create the component via {{replacementHook}} and wrap it in memo() so its identity stays stable across renders.`,
+            memoizeNestedComponent: `What's wrong: React component "{{componentName}}" is created inline inside {{locationDescription}}.
+
+Why it matters: Inline components get new identities when their containing scope re-renders, causing React to unmount and remount them—dropping state, replaying animations, and causing UI flashes. Wrapping with memo() does NOT fix this—memo() only prevents re-renders when props change, not when the component identity itself changes.
+
+How to fix:
+  1. Define the component at MODULE SCOPE in its own file, wrapped with memo()
+  2. Use React Context and/or directly provide props to supply any dynamic data the component needs
+  3. Pass the stable, imported component reference to props like CatalogWrapper
+
+Don't pass inline function components to component-type props (*Wrapper, *Component).
+Render-prop callbacks (e.g., render={...}) are fine; this rule targets component-type props only.
+
+See: https://react.dev/learn/your-first-component#nesting-and-organizing-components`,
         },
     },
     defaultOptions: [{}],
@@ -298,7 +426,16 @@ How to fix: Create the component via {{replacementHook}} and wrap it in memo() s
         }
         const sourceCode = context.sourceCode ?? context.getSourceCode();
         const reactImports = collectReactImports(sourceCode);
-        const memoReference = findMemoReference(reactImports);
+        const reportNestedComponentViolation = (node, componentName, locationDescription) => {
+            context.report({
+                node,
+                messageId: 'memoizeNestedComponent',
+                data: {
+                    componentName,
+                    locationDescription,
+                },
+            });
+        };
         return {
             CallExpression(node) {
                 const hook = isHookCall(node.callee);
@@ -314,95 +451,98 @@ How to fix: Create the component via {{replacementHook}} and wrap it in memo() s
                 if (!componentMatch) {
                     return;
                 }
-                const componentName = getVariableName(node) ??
+                // For useMemo, it only counts as a component if it returns a function
+                if (hook.name.includes('useMemo') ||
+                    hook.name.includes('useDeepCompareMemo')) {
+                    if (componentMatch.componentIsCallback) {
+                        // Returns JSX directly, so it's an element, not a component
+                        return;
+                    }
+                }
+                const variableName = getVariableName(node);
+                // A non-PascalCase binding (e.g. renderHit) is a render callback used
+                // with a render={...} prop, not a component—skip it.
+                if (variableName && !isPascalCaseName(variableName)) {
+                    return;
+                }
+                // Inside an HOC factory the binding has a stable identity, so it does
+                // not remount on re-render and must not be flagged.
+                if (isInsideHocFactory(node, reactImports)) {
+                    return;
+                }
+                const componentName = variableName ??
                     (isFunctionExpression(callback) &&
                         callback.id?.type === utils_1.AST_NODE_TYPES.Identifier
                         ? callback.id.name
                         : 'component');
-                const replacementHook = HOOK_REPLACEMENT[hook.name];
-                context.report({
-                    node,
-                    messageId: 'memoizeNestedComponent',
-                    data: {
-                        componentName,
-                        hookName: `${hook.name}()`,
-                        replacementHook: `${replacementHook}()`,
-                    },
-                    fix: (fixer) => {
-                        if (!memoReference) {
-                            return null;
-                        }
-                        const memoNamespace = memoReference.endsWith('.memo')
-                            ? memoReference.slice(0, -'.memo'.length)
-                            : null;
-                        // Prefer SourceCode#getScope when available; fall back to RuleContext#getScope for ESLint compatibility.
-                        const sourceCodeWithScope = sourceCode;
-                        const scope = typeof sourceCodeWithScope.getScope === 'function'
-                            ? sourceCodeWithScope.getScope(node)
-                            : context.getScope();
-                        const replacementIdentifierAvailable = hook.name === 'useCallback'
-                            ? hasIdentifierInScope(HOOK_REPLACEMENT.useCallback, scope)
-                            : hasIdentifierInScope(HOOK_REPLACEMENT.useDeepCompareCallback, scope);
-                        if (!replacementIdentifierAvailable) {
-                            // When the standalone replacement hook (useMemo/useDeepCompareMemo) is not imported,
-                            // we can only fix member expressions that use the React namespace.
-                            if (node.callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
-                                node.callee.object.type !== utils_1.AST_NODE_TYPES.Identifier) {
-                                return null;
-                            }
-                            // Ensure memo's namespace matches the hook's namespace (e.g., React.useCallback → React.useMemo + React.memo).
-                            if (memoReference &&
-                                memoReference.includes('.') &&
-                                memoReference !== `${node.callee.object.name}.memo`) {
-                                return null;
-                            }
-                        }
-                        // Component factories (functions returning functions that return JSX) require manual refactoring.
-                        if (!componentMatch.componentIsCallback) {
-                            return null;
-                        }
-                        // Ensure callback is a function expression before attempting to wrap it.
-                        if (!isFunctionExpression(callback)) {
-                            return null;
-                        }
-                        // React.memo() expects a synchronous component function. Wrapping async functions or
-                        // generators would produce a Promise/yielding component, which is not renderable.
-                        if (callback.async ||
-                            (callback.type === utils_1.AST_NODE_TYPES.FunctionExpression &&
-                                callback.generator)) {
-                            return null;
-                        }
-                        // Avoid rewriting non-React namespaces (e.g., Hooks.useCallback → Hooks.useMemo),
-                        // even when useMemo/memo are available as named imports.
-                        if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression) {
-                            if (node.callee.object.type !== utils_1.AST_NODE_TYPES.Identifier ||
-                                !reactImports.namespace ||
-                                node.callee.object.name !== reactImports.namespace) {
-                                return null;
-                            }
-                        }
-                        // Prevent mixing namespaces: don't apply fix when hook and memo use different React imports.
-                        if (memoNamespace &&
-                            node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                            node.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
-                            node.callee.object.name !== memoNamespace) {
-                            return null;
-                        }
-                        const callbackText = sourceCode.getText(callback);
-                        const callbackReplacement = `() => ${memoReference}(${callbackText})`;
-                        const fixes = [
-                            fixer.replaceText(callback, callbackReplacement),
-                        ];
-                        if (node.callee.type === utils_1.AST_NODE_TYPES.Identifier) {
-                            fixes.push(fixer.replaceText(node.callee, HOOK_REPLACEMENT[node.callee.name]));
-                        }
-                        else if (node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                            node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
-                            fixes.push(fixer.replaceText(node.callee.property, HOOK_REPLACEMENT[node.callee.property.name]));
-                        }
-                        return fixes;
-                    },
-                });
+                reportNestedComponentViolation(node, componentName, `${hook.name}()`);
+            },
+            VariableDeclarator(node) {
+                if (!node.init)
+                    return;
+                if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier)
+                    return;
+                // Only check if name starts with uppercase (convention for components)
+                if (!isPascalCaseName(node.id.name))
+                    return;
+                if (!isInsideFunction(node))
+                    return;
+                // Inside an HOC factory the component has a stable identity (the factory
+                // runs once per call), so it does not remount and must not be flagged.
+                if (isInsideHocFactory(node, reactImports))
+                    return;
+                // Skip if it's already a hook call (handled by CallExpression visitor)
+                if (node.init.type === utils_1.AST_NODE_TYPES.CallExpression) {
+                    const hook = isHookCall(node.init.callee);
+                    if (hook)
+                        return;
+                }
+                const componentMatch = expressionCreatesComponent(node.init, reactImports);
+                if (!componentMatch)
+                    return;
+                // JSX elements assigned to variables are fine, only report function definitions
+                if (componentMatch.componentIsCallback)
+                    return;
+                reportNestedComponentViolation(node, node.id.name, 'a render body');
+            },
+            FunctionDeclaration(node) {
+                if (!node.id || !isPascalCaseName(node.id.name))
+                    return;
+                if (!isInsideFunction(node))
+                    return;
+                // Inside an HOC factory the component has a stable identity (the factory
+                // runs once per call), so it does not remount and must not be flagged.
+                if (isInsideHocFactory(node, reactImports))
+                    return;
+                const componentMatch = functionCreatesComponent(node, reactImports);
+                if (!componentMatch)
+                    return;
+                reportNestedComponentViolation(node.id, node.id.name, 'a render body');
+            },
+            JSXAttribute(node) {
+                if (node.name.type !== utils_1.AST_NODE_TYPES.JSXIdentifier)
+                    return;
+                const attrName = node.name.name;
+                // Check if it's a component-type prop
+                if (!/(Wrapper|Component|Template|Header|Footer)$/.test(attrName)) {
+                    return;
+                }
+                if (!node.value ||
+                    node.value.type !== utils_1.AST_NODE_TYPES.JSXExpressionContainer) {
+                    return;
+                }
+                const expression = node.value.expression;
+                if (expression.type === utils_1.AST_NODE_TYPES.JSXEmptyExpression)
+                    return;
+                const componentMatch = expressionCreatesComponent(expression, reactImports);
+                if (!componentMatch)
+                    return;
+                // For props, we only report if it's a function (component definition)
+                if (componentMatch.componentIsCallback) {
+                    // It's a JSX element passed directly, which is usually fine
+                    return;
+                }
+                reportNestedComponentViolation(node, attrName, `the "${attrName}" prop`);
             },
         };
     },

package/lib/rules/no-array-length-in-deps.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noArrayLengthInDeps = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 // React hooks to check
 const HOOK_NAMES = new Set(['useEffect', 'useCallback', 'useMemo']);
 const DEFAULT_HASH_IMPORT = {
@@ -58,7 +59,7 @@ function getLastPropertyName(expr) {
     return null;
 }
 function generateUniqueName(base, taken) {
-    let candidate = `${base}Hash`;
+    const candidate = `${base}Hash`;
     if (!taken.has(candidate))
         return candidate;
     let i = 2;
@@ -120,6 +121,69 @@ function isUseMemoImported(sourceCode) {
     }
     return false;
 }
+/**
+ * Hook callback = first function-typed argument (the effect/factory/memo fn).
+ * Deps array is the LAST argument; the callback precedes it.
+ */
+function getHookCallback(node) {
+    for (const arg of node.arguments) {
+        if (arg.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+            arg.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+            return arg;
+        }
+    }
+    return null;
+}
+function rangeContains(outer, inner) {
+    return inner.range[0] >= outer.range[0] && inner.range[1] <= outer.range[1];
+}
+/**
+ * True when `identifier` is the object of a non-computed `.length` access,
+ * i.e. the reference reads only the array's length, not its contents.
+ */
+function isLengthAccessOf(identifier) {
+    const parent = identifier.parent;
+    return (!!parent &&
+        parent.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !parent.computed &&
+        parent.object === identifier &&
+        parent.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+        parent.property.name === 'length');
+}
+/**
+ * Decide whether a `<array>.length` dependency is safe to keep (suppress the
+ * report) by inspecting how the hook callback body uses the array binding.
+ *
+ * Safe (suppress) only when the array is referenced at least once inside the
+ * callback body AND every such reference is the object of a `.length` access —
+ * then depending on `.length` correctly avoids reruns on content changes.
+ *
+ * Returns false (keep reporting) for any non-`.length` use (element access,
+ * spread, iteration/method calls, bare reference, passed as an argument), when
+ * the array is never referenced in the body, and whenever the base cannot be
+ * confidently resolved (complex member-chain bases) — never hide a real bug.
+ */
+function isLengthOnlyUsage(context, callback, baseExpr) {
+    // Only resolvable for a bare identifier base (e.g. `items` in `items.length`).
+    // Member-chain bases (`a.b`, `data?.items`) have no single binding to track.
+    if (baseExpr.type !== utils_1.AST_NODE_TYPES.Identifier) {
+        return false;
+    }
+    // Resolve the binding the DEP refers to (from the deps-array identifier's
+    // scope), so a binding shadowed inside the callback body is not mistaken for
+    // it — the outer binding then has zero body references and we keep reporting.
+    const scope = ASTHelpers_1.ASTHelpers.getScope(context, baseExpr);
+    const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, baseExpr.name);
+    if (!variable) {
+        return false;
+    }
+    const bodyReferences = variable.references.filter((ref) => rangeContains(callback.body, ref.identifier));
+    // No body usage → not the content-vs-length bug, but keep current behavior.
+    if (bodyReferences.length === 0) {
+        return false;
+    }
+    return bodyReferences.every((ref) => isLengthAccessOf(ref.identifier));
+}
 function isStableHashImported(sourceCode, hashSource, hashImportName) {
     const program = sourceCode.ast;
     for (const node of program.body) {
@@ -188,15 +252,22 @@ exports.noArrayLengthInDeps = (0, createRule_1.createRule)({
                     return;
                 // Collect .length deps
                 const lengthDeps = [];
+                const callback = getHookCallback(node);
                 for (const el of depsArg.elements) {
                     if (!el)
                         continue;
                     if (el.type === utils_1.AST_NODE_TYPES.SpreadElement)
                         continue;
                     const member = getLengthMember(el);
-                    if (member) {
-                        lengthDeps.push({ element: el, member });
+                    if (!member)
+                        continue;
+                    // Suppress when the callback body reads only `<array>.length`, never
+                    // the array's contents — then `.length` is the correct dependency.
+                    if (callback &&
+                        isLengthOnlyUsage(context, callback, getBaseExpression(member))) {
+                        continue;
                     }
+                    lengthDeps.push({ element: el, member });
                 }
                 if (lengthDeps.length === 0)
                     return;

package/lib/rules/no-async-foreach.js

@@ -82,8 +82,13 @@ const getSourceCode = (context) => {
         `getSourceCode=${typeof context.getSourceCode}.`);
 };
 const getScope = (context, sourceCode, node) => {
-    const typedSourceCode = sourceCode;
-    return typedSourceCode.getScope?.(node) ?? context.getScope?.() ?? null;
+    try {
+        const typedSourceCode = sourceCode;
+        return typedSourceCode.getScope?.(node) ?? context.getScope?.() ?? null;
+    }
+    catch {
+        return context.getScope?.() ?? null;
+    }
 };
 const analyzeInlineCallback = (callback) => {
     if (!callback.async) {

package/lib/rules/no-circular-references.d.ts

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