refactor(utils): extract and harden identifier- and comment-parsing logic into utils (#1)

- Move INCLUDED_HOOKS, findDisableComment, extractMentionedDeps, extractHookDeps, and extractUsedIdentifiers into utils.js
- Preserve original staticEval guard and only add minimal ref.resolved and defs null checks in extractUsedIdentifiers
- Simplify rule index to import from utils.js and emit a single concise missingDeps message
- Ensure both CLI and API runners load identical, robust logic without TypeError on unresolved refs

Author: sathvikc

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch Program",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/index.js"
+        }
+    ]
+}

index.js

@@ -1,7 +1,5 @@
-console.log('PLUGIN LOADED')
-
 module.exports = {
   rules: {
-    "require-exhaustive-deps-comment": require("./lib/rules/require-exhaustive-deps-comment")
+    "explicit-exhaustive-deps-disable": require("./lib/rules/explicit-exhaustive-deps-disable")
   }
 };

lib/rules/explicit-exhaustive-deps-disable/index.js

@@ -0,0 +1,63 @@
+"use strict";
+
+const {
+  INCLUDED_HOOKS,
+  findDisableComment,
+  extractMentionedDeps,
+  extractHookDeps,
+  extractUsedIdentifiers,
+} = require('./utils');
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require intentional comment when disabling react-hooks/exhaustive-deps',
+      category: 'Best Practices',
+      recommended: false,
+      ruleId: 'explicit-exhaustive-deps-disable'
+    },
+    messages: {
+      missingDeps: 'You\'ve disabled exhaustive-deps, but you need to document why \'{{deps}}\' {{verb}} safe to omit.',
+    },
+    schema: [],
+  },
+
+  /**
+   * @param {import('eslint').Rule.RuleContext} context
+   * @returns {import('eslint').Rule.RuleListener}
+   */
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      CallExpression(node) {
+        const name = node.callee.name;
+
+        if (!INCLUDED_HOOKS.includes(name)) return;
+
+        const disabledComment = findDisableComment(node, sourceCode);
+
+        if (!disabledComment) return;
+
+        const hookDeps = extractHookDeps(node, sourceCode);
+        const usedIdentifiers = extractUsedIdentifiers(node, sourceCode);
+        const mentioned = extractMentionedDeps(disabledComment);
+        
+        const missing = usedIdentifiers.filter(d => !hookDeps.includes(d) && !mentioned.includes(d));
+
+        if (missing.length === 0) return;
+
+        context.report({
+          node,
+          messageId: 'missingDeps',
+          data: {
+            deps: missing.join(', '),
+            verb: missing.length > 1 ? 'are' : 'is',
+          },
+        });
+      }
+    };
+  }
+};

lib/rules/explicit-exhaustive-deps-disable/utils.js

@@ -0,0 +1,206 @@
+"use strict";
+
+const { getStaticValue } = require("eslint-utils");
+
+const INCLUDED_HOOKS = [
+  'useEffect',
+  'useCallback',
+  'useMemo',
+  'useLayoutEffect',
+  'useInsertionEffect',
+];
+
+/**  
+ * Find an inline disable‐line comment for react-hooks/exhaustive-deps  
+ * attached to a hook call.  
+ *  
+ * @param {ESTree.CallExpression} node  
+ * @param {import('eslint').SourceCode} sourceCode  
+ * @returns {import('eslint').Token|null}  the comment node, or null if none  
+ */
+function findDisableComment(node, sourceCode) {
+  // Walk up until we hit exactly an ExpressionStatement or VariableDeclaration
+  let stmt = node;
+  while (
+    stmt &&
+    stmt.type !== "ExpressionStatement" &&
+    stmt.type !== "VariableDeclaration"
+  ) {
+    stmt = stmt.parent;
+  }
+  if (!stmt) return null;
+
+  // Grab trailing comments on that statement
+  const comments = sourceCode.getCommentsAfter(stmt) || [];
+  return (
+    comments.find(c =>
+      c.type === "Line" &&
+      c.loc.start.line === stmt.loc.end.line &&
+      /eslint-disable-line\s+react-hooks\/exhaustive-deps/.test(c.value)
+    ) || null
+  );
+}
+
+/**
+ * Extracts dependency names mentioned after the first "--" in a disable comment.
+ * Supports multiple "--" in the payload by rejoining after the first marker.
+ *
+ * @param {string} commentText - The raw comment value
+ * @returns {string[]} Array of dependency names (e.g. ["foo", "bar"])
+ */
+function extractMentionedDeps(comment) {
+  const commentText = comment.value;
+  // Split on the first "--" marker, keep everything after it
+  const parts = commentText.split(/--/);
+  if (parts.length < 2) return []; // no "--" at all
+
+  // Rejoin anything after the first "--" in case reasons contain "--"
+  const payload = parts.slice(1).join("--").trim();
+  if (!payload) return []; // "--" present but nothing after it
+
+  // Extract all valid identifier tokens (including nested like user.id)
+  const matches = payload.match(/[\w$.]+/g);
+  return matches || [];
+}
+
+/**
+ * Given a CallExpression node for a hook,
+ * return an array of everything listed in its deps array.
+ *
+ * Supports both simple identifiers and member expressions (e.g. user.id).
+ */
+function extractHookDeps(node, sourceCode) {
+  const depsArg = node.arguments[1];
+  if (!depsArg || depsArg.type !== "ArrayExpression") {
+    return [];
+  }
+
+  return depsArg.elements
+    .filter(el => el && (el.type === "Identifier" || el.type === "MemberExpression"))
+    .map(el => {
+      if (el.type === "Identifier") {
+        return el.name;
+      } else {
+        // for MemberExpression, just grab the source text (e.g. "user.id")
+        return sourceCode.getText(el);
+      }
+    });
+}
+
+/**
+ * Collect every identifier reference in the hook callback’s closure,
+ * skipping those that statically evaluate to a primitive.
+ *
+ * @param {ESTree.FunctionExpression|ESTree.ArrowFunctionExpression} callback
+ * @param {import('eslint').SourceCode} sourceCode
+ * @returns {string[]}
+ */
+function extractUsedIdentifiers(node, sourceCode) {
+  const callback = node.arguments[0];
+  const hookName = node.callee.name;
+
+  // Figure out if this call is stored in a variable:
+  //    e.g. const handleClick = useCallback(...)
+  let varName;
+  if (
+    node.parent &&
+    node.parent.type === "VariableDeclarator" &&
+    node.parent.id.type === "Identifier"
+  ) {
+    varName = node.parent.id.name;
+  }
+
+  // ensure we have a block body
+  if (!callback.body || callback.body.type !== "BlockStatement") {
+    return [];
+  }
+
+  const { start, end } = callback.body.loc;
+
+  // grab the scope for the callback
+  const scope = sourceCode.scopeManager.acquire(callback);
+  if (!scope) return [];
+
+  const deps = new Set();
+
+  // walk up through scopes but focus on "through" refs for the callback
+  for (const ref of scope.through) {
+    const idNode = ref.identifier;
+    const name = idNode.name;
+    const { line } = idNode.loc.start;
+
+    // only consider references whose definition *use* is inside the callback
+    if (line < start.line || line > end.line) continue;
+
+    // skip the hook itself
+    if (name === hookName) continue;
+    // skip the variable the hook is assigned to
+    if (name === varName) continue;
+
+    // skip globally‐resolved names (console, window, etc.)
+      //    ref.resolved will be undefined if it’s undeclared,
+      //    but if it’s a built‐in, resolved.scope.type === 'global'
+    if (ref.resolved && ref.resolved.scope.type === 'global') {
+      continue;
+    }
+
+    // skip primitives that statically evaluate
+    const staticEval = getStaticValue(idNode, sourceCode.getScope(idNode));
+    if (
+      staticEval &&
+      (typeof staticEval.value === "string" ||
+       typeof staticEval.value === "number" ||
+       typeof staticEval.value === "boolean")
+    ) {
+      continue;
+    }
+
+    // skip any unresolved refs (avoid defs lookup on null)
+    if (!ref.resolved) {
+      continue;
+    }
+
+    // generic member-expression logic
+    if (
+      idNode.parent.type === "MemberExpression" &&
+      idNode.parent.object === idNode &&
+      idNode.parent.property.type === "Identifier"
+    ) {
+      const objName = name;
+      const propName = idNode.parent.property.name;
+      // safely grab defs array (may be empty)
+      const defs = Array.isArray(ref.resolved.defs) ? ref.resolved.defs : [];
+      const varDef = defs[0]?.node; // VariableDeclarator
+      const init = varDef && varDef.init;
+
+      if (init && init.type === "ArrayExpression") {
+        // any array method → just record the array variable
+        deps.add(objName);
+      } else if (init && init.type === "ObjectExpression") {
+        // if this object literal defines that key, record full obj.prop
+        const hasOwn = init.properties.some(prop => {
+          return (
+            prop.key.type === "Identifier" &&
+            prop.key.name === propName
+          );
+        });
+        deps.add(hasOwn ? `${objName}.${propName}` : objName);
+      } else {
+        // fallback: assume this is your own custom method
+        deps.add(`${objName}.${propName}`);
+      }
+    } else {
+      deps.add(name);
+    }
+  }
+
+  return Array.from(deps);
+}
+
+module.exports = {
+  INCLUDED_HOOKS,
+  findDisableComment,
+  extractMentionedDeps,
+  extractHookDeps,
+  extractUsedIdentifiers,
+};