fix(react-x/immutability): false positive on ref.current write inside useEffect, closes #1893 (#1894)

Author: Rel1cx

plugins/eslint-plugin-react-x/src/rules/immutability/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed a false positive where mutating `.current` on a `useRef()`-initialized variable whose name didn't follow the `ref`/`*Ref` naming convention (e.g. `const mounted = useRef(false); mounted.current = true;`) was incorrectly flagged when the containing function was passed to a hook. Added `isInitializedFromUseRef`/`isRefLikeChain` in `lib.ts` to also exempt refs by call-site detection (`useRef()`), not naming alone. Closes #1893. (#1893)
+
 ## [5.12.0] - 2026-07-08
 
 ### Added

plugins/eslint-plugin-react-x/src/rules/immutability/immutability.spec.diff.md

@@ -64,9 +64,12 @@ The IMPL:
 
 The SPEC exempts ref mutations via `isRefOrRefLikeMutableType`, a type-based check.
 
-The IMPL exempts ref mutations via a purely syntactic naming heuristic (`isRefLikeName`/`hasRefLikeNameInChain`): any identifier or property named `ref` or ending in `Ref` anywhere in the mutated member-expression chain is treated as a ref and skipped. This mirrors the heuristic already used elsewhere in this rule family (see `refs.spec.diff.md` §2) and additionally covers refs received as props (e.g. `props.myRef.current = x`) without needing type information.
+The IMPL exempts ref mutations via two complementary, non-type-based checks in `lib.ts`:
 
-**Verdict**: Functionally equivalent intent, different mechanism (naming convention rather than type). Can under- or over-exempt in cases where naming doesn't match the heuristic.
+- A syntactic naming heuristic (`isRefLikeName`/`hasRefLikeNameInChain`): any identifier or property named `ref` or ending in `Ref` anywhere in the mutated member-expression chain is treated as a ref and skipped. This mirrors the heuristic already used elsewhere in this rule family (see `refs.spec.diff.md` §2) and additionally covers refs received as props (e.g. `props.myRef.current = x`) without needing type information.
+- A call-site check (`isInitializedFromUseRef`, combined with the naming heuristic in `isRefLikeChain`): the root identifier of the mutated chain is resolved via `resolve()` and exempted if its initializer is a `useRef()` call, regardless of the variable's name (e.g. `const mounted = useRef(false); mounted.current = true;`). Added to fix #1893, where refs named without the `ref`/`*Ref` convention were incorrectly flagged.
+
+**Verdict**: Closer to the SPEC's type-based exemption than naming alone, since `useRef()` results are now recognized independently of their variable name. Still not fully equivalent: a ref narrowed through an intermediate alias, a custom ref-like hook, or a prop that isn't named `ref`/`*Ref` and wasn't itself produced by a local `useRef()` call is not detected (matching the `refPassedToFunction`-style gaps noted in `refs.spec.diff.md`).
 
 ---
 
@@ -89,3 +92,4 @@ The IMPL emits **two separate ESLint reports** per violation, since ESLint's rep
 2. **Limited aliasing**: Only `const`/`let`-with-initializer aliasing of the _function_ is followed; aliasing of the _mutated object_ itself, reassigned aliases, and property-stored functions are not tracked.
 3. **Fixed mutating-method list**: `MUTATING_METHODS` is a static allow-list rather than a type-driven determination of "known mutable" values.
 4. **Split diagnostics**: The usage-site and mutation-site messages are reported as two independent ESLint problems instead of one diagnostic with two annotated locations, since ESLint has no native multi-location diagnostic model.
+5. **Ref exemption still has blind spots**: `isRefLikeChain` now recognizes refs both by naming convention and by a direct `useRef()` initializer (fixed #1893), but `isInitializedFromUseRef` calls `resolve()` only once (no recursive alias-chasing like `resolveToFunctionNode` does for functions). So a ref aliased through a plain variable (`const r = mounted; r.current = true;`) is not recognized unless `r`/`mounted` itself matches the naming heuristic. Refs threaded through a custom hook, a `forwardRef`/`useImperativeHandle` boundary, or destructuring are likewise not recognized.

plugins/eslint-plugin-react-x/src/rules/immutability/immutability.spec.ts

@@ -482,5 +482,18 @@ ruleTester.run(RULE_NAME, rule, {
         return <Foo fn={fn} />;
       }
     `,
+    // https://github.com/Rel1cx/eslint-react/issues/1893
+    tsx`
+      import { useEffect, useRef } from "react";
+
+      export function Component() {
+        const mounted = useRef<boolean>(false);
+        useEffect(() => {
+          if (mounted.current) return;
+          mounted.current = true;
+        }, []);
+        return <div/>;
+      }
+    `,
   ],
 });

plugins/eslint-plugin-react-x/src/rules/immutability/immutability.ts

@@ -4,7 +4,7 @@ import * as core from "@eslint-react/core";
 import { type RuleContext, type RuleFeature, type RuleListener, merge } from "@eslint-react/eslint";
 import { AST_NODE_TYPES as AST, type TSESTree } from "@typescript-eslint/types";
 import { findVariable } from "@typescript-eslint/utils/ast-utils";
-import { MUTATING_METHODS, hasRefLikeNameInChain, isNodeWithin, isRefLikeName, resolveToFunctionNode } from "./lib";
+import { MUTATING_METHODS, isNodeWithin, isRefLikeChain, isRefLikeName, resolveToFunctionNode } from "./lib";
 
 export const RULE_NAME = "immutability";
 
@@ -63,7 +63,7 @@ export function create(context: RuleContext<MessageID, []>): RuleListener {
             return;
           }
           case AST.MemberExpression: {
-            if (hasRefLikeNameInChain(left)) return;
+            if (isRefLikeChain(context, left)) return;
             const rootId = Extract.getRootIdentifier(left);
             if (rootId == null) return;
             pushMutationSite(node, rootId);
@@ -75,7 +75,7 @@ export function create(context: RuleContext<MessageID, []>): RuleListener {
         const callee = Extract.unwrap(node.callee);
         if (callee.type === AST.MemberExpression) {
           const propName = Extract.getPropertyName(callee.property);
-          if (propName != null && MUTATING_METHODS.has(propName) && !hasRefLikeNameInChain(callee.object)) {
+          if (propName != null && MUTATING_METHODS.has(propName) && !isRefLikeChain(context, callee.object)) {
             const rootId = Extract.getRootIdentifier(callee.object);
             if (rootId != null) pushMutationSite(node, rootId);
           }
@@ -153,7 +153,7 @@ export function create(context: RuleContext<MessageID, []>): RuleListener {
         if (node.operator !== "delete") return;
         const arg = Extract.unwrap(node.argument);
         if (arg.type !== AST.MemberExpression) return;
-        if (hasRefLikeNameInChain(arg)) return;
+        if (isRefLikeChain(context, arg)) return;
         const rootId = Extract.getRootIdentifier(arg);
         if (rootId == null) return;
         pushMutationSite(node, rootId);
@@ -167,7 +167,7 @@ export function create(context: RuleContext<MessageID, []>): RuleListener {
             return;
           }
           case AST.MemberExpression: {
-            if (hasRefLikeNameInChain(arg)) return;
+            if (isRefLikeChain(context, arg)) return;
             const rootId = Extract.getRootIdentifier(arg);
             if (rootId == null) return;
             pushMutationSite(node, rootId);

plugins/eslint-plugin-react-x/src/rules/immutability/lib.ts

@@ -1,4 +1,5 @@
 import { Check, Extract, type TSESTreeFunction } from "@eslint-react/ast";
+import * as core from "@eslint-react/core";
 import type { RuleContext } from "@eslint-react/eslint";
 import { resolve } from "@eslint-react/var";
 import { AST_NODE_TYPES as AST, type TSESTree } from "@typescript-eslint/types";
@@ -77,3 +78,32 @@ export function hasRefLikeNameInChain(node: TSESTree.Node): boolean {
   }
   return false;
 }
+
+/**
+ * Check if the root identifier of a member-expression chain (or the
+ * identifier itself) is initialized directly from a `useRef()` call, e.g.
+ * `const mounted = useRef(false); mounted.current = true;`.
+ *
+ * This catches refs regardless of naming convention, complementing
+ * {@link hasRefLikeNameInChain}.
+ * @param context The ESLint rule context.
+ * @param node The AST node to inspect (an identifier or member-expression chain).
+ */
+export function isInitializedFromUseRef(context: RuleContext, node: TSESTree.Expression): boolean {
+  const rootId = node.type === AST.Identifier ? node : Extract.getRootIdentifier(node);
+  if (rootId == null) return false;
+  const initNode = resolve(context, rootId);
+  return initNode != null && initNode.type === AST.CallExpression && core.isUseRefCall(context, initNode);
+}
+
+/**
+ * Check if a mutated expression chain should be exempt from immutability
+ * checks because it is rooted at a ref: either by naming convention
+ * ({@link hasRefLikeNameInChain}) or because it is initialized from a
+ * `useRef()` call ({@link isInitializedFromUseRef}).
+ * @param context The ESLint rule context.
+ * @param node The AST node to inspect (an identifier or member-expression chain).
+ */
+export function isRefLikeChain(context: RuleContext, node: TSESTree.Expression): boolean {
+  return hasRefLikeNameInChain(node) || isInitializedFromUseRef(context, node);
+}