@blumintinc/eslint-plugin-blumint 1.15.0 → 1.16.1

package/lib/rules/logical-top-to-bottom-grouping.js

@@ -760,18 +760,26 @@ function handleGuardHoists(ruleContext, body, parent) {
 }
 function handleDerivedGrouping(ruleContext, body, parent) {
     const declaredIndices = new Map();
+    /**
+     * Each binding name → the declarator that introduced it. Sibling bindings of
+     * one multi-target declarator (e.g. `const [a, b] = ...`) share one node, so
+     * a statement deriving from `a` is recognizable as a sibling of one deriving
+     * from `b` even though `a` separates `b` from its declaration.
+     */
+    const sourceDeclarators = new Map();
     const { sourceCode } = ruleContext;
     body.forEach((statement, index) => {
         if (isVariableDeclaration(statement)) {
-            processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, parent, sourceCode);
+            processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, sourceDeclarators, parent, sourceCode);
         }
         trackDeclaredNames(statement, index, declaredIndices);
+        trackSourceDeclarators(statement, sourceDeclarators);
     });
 }
 function isVariableDeclaration(statement) {
     return statement.type === utils_1.AST_NODE_TYPES.VariableDeclaration;
 }
-function processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, parent, sourceCode) {
+function processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, sourceDeclarators, parent, sourceCode) {
     const dependencies = collectDependencies(statement);
     const priorDependencies = findPriorDependencies(dependencies, declaredIndices);
     if (priorDependencies.length === 0 ||
@@ -784,6 +792,9 @@ function processVariableDeclaration(ruleContext, statement, index, body, declare
     }
     const declaredNames = getDeclaredNames(statement);
     const priorDependencySet = new Set(priorDependencies);
+    if (interveningAreSiblingDerivations(body, lastDependencyIndex, index, priorDependencySet, sourceDeclarators)) {
+        return;
+    }
     if (hasBlockers(body, lastDependencyIndex, index, priorDependencySet, declaredNames)) {
         return;
     }
@@ -829,6 +840,73 @@ function trackDeclaredNames(statement, index, declaredIndices) {
     const declared = getDeclaredNames(statement);
     declared.forEach((name) => declaredIndices.set(name, index));
 }
+function trackSourceDeclarators(statement, sourceDeclarators) {
+    if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
+        return;
+    }
+    statement.declarations.forEach((declarator) => {
+        const names = new Set();
+        collectDeclaredNamesFromPattern(declarator.id, names);
+        names.forEach((name) => sourceDeclarators.set(name, declarator));
+    });
+}
+/**
+ * True when every statement between a dependency and the statement deriving from
+ * it is itself a pure derivation from a *sibling binding of the same declarator*.
+ *
+ * `const [a, b] = await Promise.all([...]); const x = a; const y = b;` is already
+ * grouped: `x` and `y` unpack one source declaration in order, so the `x` line is
+ * not "unrelated" separation between `b` and `y`. Suppressing here keeps such
+ * cohesive sibling-destructure groups intact instead of reordering them.
+ */
+function interveningAreSiblingDerivations(body, lastDependencyIndex, currentIndex, priorDependencySet, sourceDeclarators) {
+    const sourceNodes = new Set();
+    priorDependencySet.forEach((name) => {
+        const declarator = sourceDeclarators.get(name);
+        if (declarator) {
+            sourceNodes.add(declarator);
+        }
+    });
+    if (sourceNodes.size === 0) {
+        return false;
+    }
+    const intervening = body.slice(lastDependencyIndex + 1, currentIndex);
+    if (intervening.length === 0) {
+        return false;
+    }
+    return intervening.every((between) => isSiblingSourceDerivation(between, sourceNodes, sourceDeclarators));
+}
+/**
+ * A statement is a sibling-source derivation when it is a pure declaration whose
+ * every prior-declared dependency was introduced by one of `sourceNodes` — i.e.
+ * it unpacks a sibling binding of the same multi-target declaration the dependent
+ * statement derives from.
+ */
+function isSiblingSourceDerivation(statement, sourceNodes, sourceDeclarators) {
+    if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+        !isPureDeclaration(statement, { allowHooks: false })) {
+        return false;
+    }
+    const dependencies = collectDependencies(statement);
+    const siblingSourced = Array.from(dependencies).filter((name) => {
+        const declarator = sourceDeclarators.get(name);
+        return Boolean(declarator && sourceNodes.has(declarator));
+    });
+    if (siblingSourced.length === 0) {
+        return false;
+    }
+    /**
+     * Reject when the statement also pulls in any prior-declared name from outside
+     * the sibling source: that would be genuine extra coupling, not a clean sibling
+     * unpack.
+     */
+    return Array.from(dependencies).every((name) => {
+        if (siblingSourced.includes(name)) {
+            return true;
+        }
+        return !sourceDeclarators.has(name);
+    });
+}
 function handleLateDeclarations(ruleContext, body, parent) {
     const { sourceCode } = ruleContext;
     body.forEach((statement, index) => {

package/lib/rules/memo-compare-deeply-complex-props.js

@@ -6,6 +6,19 @@ const createRule_1 = require("../utils/createRule");
 function isUtilMemoModulePath(path) {
     return /(?:^|\/|\\)util\/memo$/.test(path);
 }
+/**
+ * Reserved React slots that never reach a component's props object at runtime.
+ * React extracts `ref` and `key` before invoking the memo equality function, so
+ * a deep comparator can never observe them. Some prop-type sources (notably the
+ * `forwardRef<T, P>` exotic-component signature, whose params include the
+ * synthetic `RefAttributes<T> = { ref?: Ref<T> }` member) surface them as
+ * structural members anyway; flagging them would emit dead `compareDeeply('ref')`
+ * advice. Excluded the same way `children` is.
+ */
+const RESERVED_REACT_PROP_NAMES = new Set(['ref', 'key', 'children']);
+function isReservedReactPropName(name) {
+    return RESERVED_REACT_PROP_NAMES.has(name);
+}
 /**
  * Checks if a property name is handled by the default deep equality logic
  * in our custom memo implementation (blumintAreEqual).
@@ -296,6 +309,91 @@ function ensureCompareDeeplyImportFixes(sourceCode, fixer, usedNames, preferredS
         localName: preferredLocalName,
     };
 }
+/**
+ * Names of React types that represent renderable UI or component references.
+ * Props typed as any of these are stable references (JSX elements, component
+ * constructors, render-prop functions) and do NOT benefit from deep value
+ * comparison — flagging them would produce false positives.
+ */
+const REACT_RENDER_TYPE_NAMES = new Set([
+    'ReactNode',
+    'ReactChild',
+    'ReactElement',
+    'ReactPortal',
+    'ReactFragment',
+    // JSX.Element resolves to a global symbol named 'Element' in the JSX namespace
+    'Element',
+    'Component',
+    'PureComponent',
+    'ComponentClass',
+    'FunctionComponent',
+    'FC',
+    'ComponentType',
+    'ExoticComponent',
+    'NamedExoticComponent',
+    'MemoExoticComponent',
+    'ForwardRefExoticComponent',
+    'LazyExoticComponent',
+    'JSXElementConstructor',
+    'RefObject',
+    'RefCallback',
+    'Ref',
+]);
+/**
+ * Returns true when `sym` is declared inside a `.d.ts` file whose path
+ * contains "react" — indicating it originates from @types/react rather than
+ * from user code that happens to use the same name.
+ *
+ * Also returns true when the symbol has NO declarations at all: this happens
+ * when TypeScript resolves the type as `any` because the source module (e.g.
+ * @types/react) is not included in the tsconfig `types` array.  A symbol with
+ * no declarations cannot be a user-defined type, so treating it as "from
+ * React" is safe — it avoids flagging props that would otherwise be excluded
+ * once the types are properly wired.
+ */
+function isSymbolFromReactDeclarationFile(sym) {
+    const declarations = sym.declarations;
+    // No declarations ⟹ the type was resolved from an unresolvable external
+    // module (common when @types/react is absent from the tsconfig types list).
+    // User-defined types always have at least one declaration.
+    if (!declarations || declarations.length === 0)
+        return true;
+    return declarations.some((decl) => {
+        const fileName = decl.getSourceFile?.()?.fileName ?? '';
+        return fileName.endsWith('.d.ts') && /react/i.test(fileName);
+    });
+}
+/**
+ * Returns true when `type` is a React render-related type that should be
+ * excluded from the "complex prop" check.  Detects by matching the type's
+ * alias symbol or own symbol name against a known React-type allowlist AND
+ * verifying the matched symbol's declaration originates from a React `.d.ts`
+ * file to avoid false negatives for user types that coincidentally share the
+ * same name.
+ */
+function isReactRenderType(type) {
+    // Check the aliasSymbol first (covers type aliases like ReactNode, FC, etc.)
+    const aliasSymbol = type
+        .aliasSymbol;
+    if (aliasSymbol) {
+        const name = aliasSymbol.escapedName;
+        if (REACT_RENDER_TYPE_NAMES.has(name) &&
+            isSymbolFromReactDeclarationFile(aliasSymbol)) {
+            return true;
+        }
+    }
+    // Check the type's own symbol (covers interfaces / classes like ReactElement,
+    // ComponentClass, ForwardRefExoticComponent, etc.)
+    const sym = type.symbol;
+    if (sym) {
+        const name = sym.escapedName;
+        if (REACT_RENDER_TYPE_NAMES.has(name) &&
+            isSymbolFromReactDeclarationFile(sym)) {
+            return true;
+        }
+    }
+    return false;
+}
 function isComplexType(ts, type, checker) {
     return isComplexTypeInternal(ts, type, checker, new Set());
 }
@@ -303,6 +401,13 @@ function isComplexTypeInternal(ts, type, checker, visited) {
     if (visited.has(type))
         return false;
     visited.add(type);
+    // Exclude React render-related types before any structural checks.
+    // This must come early so that ReactElement (an object type) and ReactNode
+    // (a union containing ReactElement) are both short-circuited here rather
+    // than being caught by the isObjectType / checkUnionType branches below.
+    if (isReactRenderType(type)) {
+        return false;
+    }
     const flags = type.flags ?? 0;
     if (isUnionType(ts, flags)) {
         return checkUnionType(ts, type, checker, visited);
@@ -389,13 +494,72 @@ function extractAnnotationType(propDeclaration) {
     }
     return undefined;
 }
-function shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags) {
+/**
+ * Returns true when an annotation TypeNode (the explicit type written in
+ * source, e.g. `React.ComponentType` or `React.ReactNode | null`) resolves to
+ * a React render type that must be excluded from the complex-prop check.
+ *
+ * This path is taken when the prop type resolves to `any` (common when
+ * @types/react is not listed in the tsconfig `types` array) but the
+ * annotation still carries the original alias name via the TypeScript
+ * type-checker.
+ *
+ * For union annotation nodes (e.g. `ReactNode | null`), all non-null /
+ * non-undefined members must themselves be React render types for the whole
+ * union to be considered a React render type.
+ */
+function isAnnotationReactRenderType(annotationType, checker, ts) {
+    try {
+        const tsModule = ts;
+        // Handle union annotation nodes like `React.ReactNode | null`.
+        if (tsModule.isUnionTypeNode?.(annotationType)) {
+            const nonNullishMembers = annotationType.types.filter((member) => {
+                // Nullish keywords appearing directly (older TypeScript AST forms)
+                if (member.kind === tsModule.SyntaxKind.NullKeyword ||
+                    member.kind === tsModule.SyntaxKind.UndefinedKeyword ||
+                    member.kind === tsModule.SyntaxKind.VoidKeyword) {
+                    return false;
+                }
+                // `null` and `undefined` appear as LiteralTypeNode wrapping the
+                // corresponding keyword in modern TypeScript AST.
+                if (tsModule.isLiteralTypeNode?.(member)) {
+                    const lit = member.literal;
+                    if (lit.kind === tsModule.SyntaxKind.NullKeyword ||
+                        lit.kind === tsModule.SyntaxKind.UndefinedKeyword) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+            // If every non-nullish member is a React render type, the union is too.
+            return (nonNullishMembers.length > 0 &&
+                nonNullishMembers.every((member) => isAnnotationReactRenderType(member, checker, ts)));
+        }
+        // For plain TypeReference nodes (the common case), resolve via the checker.
+        const resolvedType = checker.getTypeFromTypeNode?.(annotationType);
+        if (!resolvedType)
+            return false;
+        return isReactRenderType(resolvedType);
+    }
+    catch {
+        return false;
+    }
+}
+function shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags, checker) {
     if (!(propType.flags & ts.TypeFlags.Any))
         return false;
     if (treatAnyAsComplex)
         return true;
     const propDeclaration = extractPropertyDeclaration(prop);
     const annotationType = extractAnnotationType(propDeclaration);
+    // When the annotation resolves to a React render type, the prop is a
+    // stable component/render-prop reference that does not benefit from deep
+    // value comparison — exclude it regardless of the any-as-complex heuristic.
+    if (annotationType &&
+        checker &&
+        isAnnotationReactRenderType(annotationType, checker, ts)) {
+        return false;
+    }
     return ((annotationType && annotationType.kind !== ts.SyntaxKind.AnyKeyword) ||
         (!annotationType && Boolean(parentTypeFlags & ts.TypeFlags.Object)));
 }
@@ -404,13 +568,13 @@ function isPropertyComplex(prop, checker, tsNode, ts, treatAnyAsComplex, parentT
     if (isComplexType(ts, propType, checker)) {
         return true;
     }
-    return shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags);
+    return shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags, checker);
 }
 function getComplexPropertiesFromType(type, checker, tsNode, ts, treatAnyAsComplex = false, parentTypeFlags = 0) {
     const properties = checker.getPropertiesOfType(type);
     const complexProps = [];
     for (const prop of properties) {
-        if (prop.name === 'children')
+        if (isReservedReactPropName(prop.name))
             continue;
         if (isPropertyComplex(prop, checker, tsNode, ts, treatAnyAsComplex, parentTypeFlags)) {
             complexProps.push(prop.name);

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

@@ -252,18 +252,134 @@ const getVariableName = (node) => {
     }
     return null;
 };
-const isInsideFunction = (node) => {
+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 (parent.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
-            parent.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
-            parent.type === utils_1.AST_NODE_TYPES.FunctionDeclaration) {
-            return true;
+        if (isEnclosingFunction(parent)) {
+            return parent;
         }
         parent = parent.parent;
     }
+    return null;
+};
+const isInsideFunction = (node) => {
+    return findEnclosingFunction(node) !== null;
+};
+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: {
@@ -343,7 +459,18 @@ See: https://react.dev/learn/your-first-component#nesting-and-organizing-compone
                         return;
                     }
                 }
-                const componentName = getVariableName(node) ??
+                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
@@ -356,10 +483,14 @@ See: https://react.dev/learn/your-first-component#nesting-and-organizing-compone
                 if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier)
                     return;
                 // Only check if name starts with uppercase (convention for components)
-                if (!/^[A-Z]/.test(node.id.name))
+                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);
@@ -375,10 +506,14 @@ See: https://react.dev/learn/your-first-component#nesting-and-organizing-compone
                 reportNestedComponentViolation(node, node.id.name, 'a render body');
             },
             FunctionDeclaration(node) {
-                if (!node.id || !/^[A-Z]/.test(node.id.name))
+                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;

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;