refactor(oxlint-plugin): extract exhaustive-deps symbol-stability cluster

Completes the third targeted P8 extraction (the previously-deferred
'stretch' from the cleanup plan). The 7-helper cluster that answers
'is this captured symbol structurally stable across renders?' now
lives in its own module; the low-level helpers it shares with the
main rule body (unwrapExpression, getHookName, isOutsideAllFunctions,
TRANSPARENT_WRAPPER_TYPES) sit in a sibling 'low-level' module so the
main rule and the symbol-stability module both import without a
circular dependency.

New module layout for the exhaustive-deps rule:

  exhaustive-deps.ts                        — analysis logic (1144L)
  exhaustive-deps-symbol-stability.ts       — stability cluster (168L)
  exhaustive-deps-low-level.ts              — shared helpers (80L)
  exhaustive-deps-settings.ts               — config resolver (47L)
  exhaustive-deps-messages.ts               — diagnostic strings (55L)

Main rule file: 1311 -> 1144 lines (-167). Behaviour-neutral; the
7 cluster helpers, the 3 low-level helpers, and the
TRANSPARENT_WRAPPER_TYPES set are re-imported into the main rule
under the same names.

The previous `docs(exhaustive-deps): annotate why unwrapExpression
doesn't reuse stripParenExpression` (6e20c3c) comment is preserved
verbatim in the new low-level module — same rationale, new home.

Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

Author: cursoragent

packages/oxlint-plugin-react-doctor/src/plugin/rules/react-builtins/exhaustive-deps-low-level.ts

@@ -0,0 +1,80 @@
+import type { SymbolDescriptor } from "../../semantic/scope-analysis.js";
+import type { EsTreeNode } from "../../utils/es-tree-node.js";
+import { isNodeOfType } from "../../utils/is-node-of-type.js";
+
+/**
+ * Lowest-level helpers consumed by both the main `exhaustive-deps`
+ * rule body AND the symbol-stability cluster
+ * (`exhaustive-deps-symbol-stability.ts`). Sit in their own module so
+ * the two top-level files can each import without a circular
+ * dependency.
+ *
+ * Behaviour mirrors the previous inlined versions in `exhaustive-deps.ts`
+ * exactly. The doc comment that used to argue against reusing the
+ * shared `stripParenExpression` util still applies: this module's
+ * `TRANSPARENT_WRAPPER_TYPES.has(...)` membership check is also read
+ * directly by the member-chain walker in the main rule, so keeping
+ * both `TRANSPARENT_WRAPPER_TYPES` and `unwrapExpression` co-located
+ * here keeps that intent in one place.
+ */
+
+/**
+ * Strip TypeScript expression wrappers transparently — `(x as T)`,
+ * `x satisfies T`, `x!`, `(x)` — so they don't change the dep key.
+ */
+export const TRANSPARENT_WRAPPER_TYPES: ReadonlySet<string> = new Set([
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSNonNullExpression",
+  "TSTypeAssertion",
+  "ParenthesizedExpression",
+  "ChainExpression",
+]);
+
+export const unwrapExpression = (node: EsTreeNode): EsTreeNode => {
+  let current = node;
+  while (TRANSPARENT_WRAPPER_TYPES.has(current.type)) {
+    const inner = (current as { expression?: EsTreeNode | null }).expression;
+    if (!inner) return current;
+    current = inner;
+  }
+  return current;
+};
+
+/**
+ * Get the hook name from a call expression's callee, regardless of
+ * whether the hook is called as `useFoo()` (Identifier) or
+ * `React.useFoo()` (MemberExpression).
+ */
+export const getHookName = (callee: EsTreeNode): string | null => {
+  if (isNodeOfType(callee, "Identifier")) return callee.name;
+  if (
+    isNodeOfType(callee, "MemberExpression") &&
+    !callee.computed &&
+    isNodeOfType(callee.property, "Identifier")
+  ) {
+    return callee.property.name;
+  }
+  return null;
+};
+
+const FUNCTION_SCOPE_KINDS: ReadonlySet<string> = new Set([
+  "function",
+  "arrow-function",
+  "method",
+]);
+
+/**
+ * True for symbols declared at module scope (outside any function
+ * scope). Module-scope bindings don't change between renders so they
+ * don't need to live in dependency arrays.
+ */
+export const isOutsideAllFunctions = (symbol: SymbolDescriptor): boolean => {
+  let scope: SymbolDescriptor["scope"] | null = symbol.scope;
+  while (scope) {
+    if (FUNCTION_SCOPE_KINDS.has(scope.kind)) return false;
+    if (scope.kind === "module") return true;
+    scope = scope.parent ?? null;
+  }
+  return true;
+};

packages/oxlint-plugin-react-doctor/src/plugin/rules/react-builtins/exhaustive-deps-symbol-stability.ts

@@ -0,0 +1,168 @@
+import { closureCaptures } from "../../semantic/closure-captures.js";
+import type { ScopeAnalysis, SymbolDescriptor } from "../../semantic/scope-analysis.js";
+import type { EsTreeNode } from "../../utils/es-tree-node.js";
+import type { EsTreeNodeOfType } from "../../utils/es-tree-node-of-type.js";
+import { getStaticTemplateLiteralValue } from "../../utils/get-static-template-literal-value.js";
+import { isNodeOfType } from "../../utils/is-node-of-type.js";
+import {
+  getHookName,
+  isOutsideAllFunctions,
+  unwrapExpression,
+} from "./exhaustive-deps-low-level.js";
+
+/**
+ * Symbol-stability helpers consumed by the `exhaustive-deps` rule.
+ *
+ * One cohesive concept: "given a captured symbol, is its value
+ * structurally stable across re-renders (and therefore unnecessary
+ * in a deps array)?". The rule reads `symbolHasStableValue` /
+ * `symbolHasStableHookOrigin` / `symbolHasUseEffectEventOrigin` /
+ * `isRecursiveInitializerCapture` at multiple sites — extracting
+ * them lets the rule body stay focused on the diff-the-captured-vs-
+ * declared logic.
+ *
+ * Low-level helpers (`unwrapExpression`, `getHookName`,
+ * `isOutsideAllFunctions`) live in
+ * `./exhaustive-deps-low-level.ts` so both this module and the main
+ * rule can import them without a circular dependency.
+ */
+
+/**
+ * True for symbols whose returned value (or destructured pieces) are
+ * stable across re-renders and don't need to live in deps arrays:
+ *   - useState's setter (`setX`)
+ *   - useReducer's dispatch
+ *   - useRef's ref object
+ *   - useEffectEvent's return value
+ *   - primitive-literal local consts (the value never changes
+ *     between renders unless the literal does)
+ */
+export const symbolHasStableHookOrigin = (symbol: SymbolDescriptor): boolean => {
+  if (symbol.references.some((reference) => reference.flag !== "read")) return false;
+  // We need the binding's parent context. The symbol's
+  // declarationNode is the VariableDeclarator (when destructured) or
+  // the binding identifier itself.
+  let declarator: EsTreeNode | null | undefined = symbol.declarationNode;
+  while (declarator && declarator.type !== "VariableDeclarator") {
+    declarator = declarator.parent ?? null;
+  }
+  if (!declarator || !isNodeOfType(declarator, "VariableDeclarator")) return false;
+  const initializerRaw = declarator.init;
+  if (!initializerRaw) return false;
+  const initializer = unwrapExpression(initializerRaw);
+
+  // Primitive literal initializer of a `const` binding — the value
+  // cannot change between renders, so the captured reference is
+  // structurally stable for dep-array purposes. `let` / `var` could
+  // be reassigned and don't qualify.
+  if (symbol.kind === "const") {
+    if (
+      isNodeOfType(initializer, "Literal") &&
+      (initializer.value === null ||
+        typeof initializer.value === "number" ||
+        typeof initializer.value === "string" ||
+        typeof initializer.value === "boolean")
+    ) {
+      return true;
+    }
+    if (
+      isNodeOfType(initializer, "TemplateLiteral") &&
+      getStaticTemplateLiteralValue(initializer) !== null
+    ) {
+      return true;
+    }
+  }
+
+  if (!isNodeOfType(initializer, "CallExpression")) return false;
+  const initializerHookName = getHookName(initializer.callee);
+  if (!initializerHookName) return false;
+  // useRef returns a stable ref; the binding itself is the ref.
+  if (initializerHookName === "useRef") return true;
+  // useEffectEvent returns a stable callback (React's RFC).
+  if (initializerHookName === "useEffectEvent") return true;
+  // useState / useReducer: the SECOND destructure element (setter /
+  // dispatch) is stable; the first is mutable.
+  if (
+    initializerHookName === "useState" ||
+    initializerHookName === "useReducer" ||
+    initializerHookName === "useActionState" ||
+    initializerHookName === "useTransition"
+  ) {
+    if (!isNodeOfType(declarator.id, "ArrayPattern")) return false;
+    const STABLE_RETURN_INDEX = 1;
+    const elements = declarator.id.elements;
+    const stableElement = elements[STABLE_RETURN_INDEX];
+    if (!stableElement) return false;
+    const innerBinding = isNodeOfType(stableElement as EsTreeNode, "AssignmentPattern")
+      ? (stableElement as EsTreeNodeOfType<"AssignmentPattern">).left
+      : (stableElement as EsTreeNode);
+    return isNodeOfType(innerBinding, "Identifier") && symbol.bindingIdentifier === innerBinding;
+  }
+  return false;
+};
+
+export const symbolHasUseEffectEventOrigin = (symbol: SymbolDescriptor): boolean => {
+  const initializer = symbol.initializer ? unwrapExpression(symbol.initializer) : null;
+  if (!initializer || !isNodeOfType(initializer, "CallExpression")) return false;
+  return getHookName(initializer.callee) === "useEffectEvent";
+};
+
+export const getFunctionValueNode = (symbol: SymbolDescriptor): EsTreeNode | null => {
+  if (symbol.kind === "function" && isNodeOfType(symbol.declarationNode, "FunctionDeclaration")) {
+    return symbol.declarationNode;
+  }
+  const initializer = symbol.initializer ? unwrapExpression(symbol.initializer) : null;
+  if (
+    initializer &&
+    (isNodeOfType(initializer, "FunctionExpression") ||
+      isNodeOfType(initializer, "ArrowFunctionExpression"))
+  ) {
+    return initializer;
+  }
+  return null;
+};
+
+const isAstDescendant = (inner: EsTreeNode, outer: EsTreeNode): boolean => {
+  let current: EsTreeNode | null | undefined = inner;
+  while (current) {
+    if (current === outer) return true;
+    current = current.parent ?? null;
+  }
+  return false;
+};
+
+export const isRecursiveInitializerCapture = (
+  symbol: SymbolDescriptor,
+  callback: EsTreeNode,
+): boolean => {
+  const initializer = symbol.initializer;
+  return Boolean(initializer && isAstDescendant(callback, initializer));
+};
+
+const symbolHasStableFunctionOrigin = (
+  symbol: SymbolDescriptor,
+  scopes: ScopeAnalysis,
+  visitedSymbolIds: Set<number>,
+): boolean => {
+  if (visitedSymbolIds.has(symbol.id)) return true;
+  const functionNode = getFunctionValueNode(symbol);
+  if (!functionNode) return false;
+  visitedSymbolIds.add(symbol.id);
+  for (const reference of closureCaptures(functionNode, scopes)) {
+    const capturedSymbol = reference.resolvedSymbol;
+    if (!capturedSymbol) continue;
+    if (capturedSymbol.id === symbol.id) continue;
+    if (isOutsideAllFunctions(capturedSymbol)) continue;
+    if (symbolHasStableValue(capturedSymbol, scopes, visitedSymbolIds)) continue;
+    return false;
+  }
+  return true;
+};
+
+export const symbolHasStableValue = (
+  symbol: SymbolDescriptor,
+  scopes: ScopeAnalysis,
+  visitedSymbolIds: Set<number> = new Set(),
+): boolean =>
+  symbolHasStableHookOrigin(symbol) ||
+  symbolHasStableFunctionOrigin(symbol, scopes, visitedSymbolIds);