@blumintinc/eslint-plugin-blumint 1.20.55 → 1.20.57

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.55',
+        version: '1.20.57',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/no-entire-object-hook-deps.js

@@ -5,10 +5,77 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const typescript_1 = require("typescript");
 const HOOK_NAMES = new Set(['useEffect', 'useCallback', 'useMemo']);
+/**
+ * Hooks that run for their side effects rather than producing a value. An
+ * unread dependency means something different here than in useMemo/useCallback
+ * — see `callsCorrespondingSetter`.
+ */
+const EFFECT_HOOK_NAMES = new Set(['useEffect']);
 function isHookCall(node) {
     const callee = node.callee;
     return (callee.type === utils_1.AST_NODE_TYPES.Identifier && HOOK_NAMES.has(callee.name));
 }
+function isEffectHookCall(node) {
+    const callee = node.callee;
+    return (callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+        EFFECT_HOOK_NAMES.has(callee.name));
+}
+/**
+ * The rule whose suppression marks a dependency array as hand-maintained.
+ */
+const EXHAUSTIVE_DEPS_RULE = 'react-hooks/exhaustive-deps';
+/**
+ * Matches the keyword of an `eslint-disable`, `eslint-disable-next-line` or
+ * `eslint-disable-line` directive, leaving the rule list as the remainder. The
+ * lookahead keeps `eslint-disabled-something` (and prose that merely opens with
+ * the same letters) from parsing as a directive.
+ */
+const DISABLE_DIRECTIVE = /^\s*eslint-disable(-next-line|-line)?(?![\w-])/u;
+/**
+ * ESLint splits a directive's rule list from its ` -- justification` suffix on
+ * this separator, so the rule list must be read the same way.
+ */
+const JUSTIFICATION_SEPARATOR = /\s-{2,}\s/u;
+/**
+ * The line an exhaustive-deps disable comment covers, `'file'` for the
+ * whole-file form, or null when the comment is not such a directive.
+ *
+ * why: `eslint-disable-next-line` covers the line after the comment ends, while
+ * `eslint-disable-line` covers the comment's own line. Only the block form of
+ * the bare `eslint-disable` is a file-level directive to ESLint, so a line
+ * comment starting with it is not treated as one here either. The file form
+ * counts for the whole file rather than from its own position onward: erring
+ * toward exempting a hook keeps a hand-managed array intact, which is the safe
+ * direction for a deleting fixer.
+ */
+function readExhaustiveDepsDisable(comment) {
+    const [directive] = comment.value.split(JUSTIFICATION_SEPARATOR);
+    const match = DISABLE_DIRECTIVE.exec(directive);
+    if (!match) {
+        return null;
+    }
+    // why: a bare directive with no rule list says nothing about dependency
+    // management, so only an explicit mention of exhaustive-deps counts.
+    const namesExhaustiveDeps = directive
+        .slice(match[0].length)
+        .split(',')
+        .some((ruleId) => ruleId.trim() === EXHAUSTIVE_DEPS_RULE);
+    if (!namesExhaustiveDeps) {
+        return null;
+    }
+    const scope = match[1];
+    if (scope === '-next-line') {
+        return comment.loc.end.line + 1;
+    }
+    if (scope === '-line') {
+        return comment.loc.start.line;
+    }
+    return comment.type === utils_1.AST_TOKEN_TYPES.Block ? 'file' : null;
+}
+/** `channelGroupActive` -> `setChannelGroupActive`, `a` -> `setA`. */
+function toSetterName(dependencyName) {
+    return `set${dependencyName.charAt(0).toUpperCase()}${dependencyName.slice(1)}`;
+}
 function isArrayOrPrimitive(checker, esTreeNode, nodeMap) {
     try {
         const tsNode = nodeMap.get(esTreeNode);
@@ -80,6 +147,55 @@ function unwrapExpression(expr) {
     }
     return current;
 }
+/**
+ * Whether the hook body anywhere calls the state setter that corresponds to
+ * `dependencyName` (dep `count` -> `setCount(...)`).
+ *
+ * why: for an effect, an unread dependency is React's reset-on-scope-change
+ * idiom — a deliberate re-run trigger. The one shape where an unread dependency
+ * is genuinely wrong is the circular dependency, where the effect writes the
+ * very value it depends on and so re-triggers itself. The setter call is that
+ * signature. It can sit arbitrarily deep (inside an inner async function, a
+ * `startTransition` callback, a `.then()`), so the whole body is searched.
+ */
+function callsCorrespondingSetter(hookBody, dependencyName) {
+    const setterName = toSetterName(dependencyName);
+    const visited = new Set();
+    function visit(node) {
+        if (!node || visited.has(node))
+            return false;
+        visited.add(node);
+        if (node.type === utils_1.AST_NODE_TYPES.CallExpression) {
+            const callee = unwrapExpression(node.callee);
+            if (callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                callee.name === setterName) {
+                return true;
+            }
+        }
+        for (const key in node) {
+            if (key === 'parent')
+                continue; // Skip parent references to avoid cycles
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const child = node[key];
+            if (!child || typeof child !== 'object')
+                continue;
+            if (Array.isArray(child)) {
+                for (const item of child) {
+                    if (item && typeof item === 'object' && 'type' in item) {
+                        if (visit(item))
+                            return true;
+                    }
+                }
+            }
+            else if ('type' in child) {
+                if (visit(child))
+                    return true;
+            }
+        }
+        return false;
+    }
+    return visit(hookBody);
+}
 function getObjectUsagesInHook(hookBody, objectName) {
     const usages = new Map(); // Track usage and its position
     // why: derived dependency paths (first-optional intermediate, array base)
@@ -545,6 +661,53 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
             // In a real environment, we would want to enforce this
             // throw new Error('You have to enable the `project` setting in parser options to use this rule');
         }
+        const sourceCode = context.getSourceCode();
+        // why: scanning every comment once per file rather than once per hook call
+        // keeps the check off the hot path of files with many hooks.
+        let manuallyManagedLines = null;
+        let disabledForWholeFile = false;
+        function collectDisableDirectives() {
+            if (manuallyManagedLines) {
+                return manuallyManagedLines;
+            }
+            const lines = new Set();
+            for (const comment of sourceCode.getAllComments()) {
+                const scope = readExhaustiveDepsDisable(comment);
+                if (scope === 'file') {
+                    disabledForWholeFile = true;
+                }
+                else if (scope !== null) {
+                    lines.add(scope);
+                }
+            }
+            manuallyManagedLines = lines;
+            return lines;
+        }
+        /**
+         * Whether the author has taken manual control of this hook's dependency
+         * array by suppressing `react-hooks/exhaustive-deps` for it.
+         *
+         * why: exhaustive-deps is the rule that would otherwise force every read
+         * value into the array, so disabling it declares the array hand-maintained.
+         * Entries in such an array are load-bearing by construction — an unread one
+         * is a deliberate recompute trigger (a hydration flag, a change-detecting
+         * hash) whose deletion silently returns a stale value. The comment can sit
+         * above the hook call, above the dependency array, or above the closing
+         * `}, [...])` line, so any directive landing anywhere within the call
+         * counts.
+         */
+        function hasManuallyManagedDeps(node) {
+            const lines = collectDisableDirectives();
+            if (disabledForWholeFile) {
+                return true;
+            }
+            for (let line = node.loc.start.line; line <= node.loc.end.line; line += 1) {
+                if (lines.has(line)) {
+                    return true;
+                }
+            }
+            return false;
+        }
         return {
             CallExpression(node) {
                 if (!isHookCall(node)) {
@@ -562,6 +725,9 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
                         callbackArg.type !== utils_1.AST_NODE_TYPES.FunctionExpression)) {
                     return;
                 }
+                const callbackBody = callbackArg.body;
+                const isEffect = isEffectHookCall(node);
+                const manuallyManagedDeps = hasManuallyManagedDeps(node);
                 // Check each dependency in the array
                 depsArg.elements.forEach((element) => {
                     const unwrappedElement = element ? unwrapExpression(element) : null;
@@ -579,9 +745,30 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
                             }
                         }
                         // For testing without TypeScript services, we'll assume all identifiers are objects
-                        const result = getObjectUsagesInHook(callbackArg.body, objectName);
+                        const result = getObjectUsagesInHook(callbackBody, objectName);
                         // If the object is not used at all, suggest removing it
                         if (result.notUsed) {
+                            // why: deleting an entry from an array the author maintains by
+                            // hand is presumptuous — the suppression is the declaration that
+                            // the entries were chosen deliberately, and an unread one is a
+                            // recompute trigger whose removal yields a stale value. Narrowing
+                            // an entire object (avoidEntireObject) is a different transform
+                            // and stays enabled: it preserves the dependency, it does not
+                            // drop it.
+                            if (manuallyManagedDeps) {
+                                return;
+                            }
+                            // why: an effect reruns for its side effects, so a dependency the
+                            // body never reads is normally a deliberate re-run trigger
+                            // (React's reset-on-scope-change idiom) — deleting it silently
+                            // stops the effect from rerunning. Only when the body also writes
+                            // that value (setX for dep x) is the dependency a circular one
+                            // worth removing. Value-producing hooks (useMemo/useCallback)
+                            // gain nothing from an unread dependency, so they still report.
+                            if (isEffect &&
+                                !callsCorrespondingSetter(callbackBody, objectName)) {
+                                return;
+                            }
                             context.report({
                                 node: element,
                                 messageId: 'removeUnusedDependency',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.55",
+  "version": "1.20.57",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.20.57",
+    "date": "2026-08-01T03:42:42.343Z",
+    "rules": [
+      {
+        "name": "no-entire-object-hook-deps",
+        "changeType": "fix",
+        "issues": [
+          1547
+        ],
+        "summary": "never prune deps from a hand-maintained dependency array (closes #1547)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.56",
+    "date": "2026-08-01T03:08:15.343Z",
+    "rules": [
+      {
+        "name": "no-entire-object-hook-deps",
+        "changeType": "fix",
+        "issues": [
+          1546
+        ],
+        "summary": "treat unread useEffect deps as re-run triggers unless the effect sets them (closes #1546)"
+      }
+    ]
+  },
   {
     "version": "1.20.55",
     "date": "2026-08-01T02:47:13.295Z",