refactor: refs rule for improved lazy-init and nested writes detection (#1892)

Author: Rel1cx

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

@@ -5,6 +5,21 @@ All notable changes to the `react-x/refs` rule will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Added detection of nested property writes on a ref's value (e.g. `ref.current.inner = value`), which are now reported as `writeDuringRender` instead of being misclassified as a read.
+- Added tracking of functions bound to (and called through) simple object-member-expression targets (e.g. `object.foo = () => ref.current; object.foo();`), closing a gap in the render-reachability analysis that previously only covered plain variable bindings.
+- Added detection of `ref.current` accesses inside the lazy initializer function passed directly as `useState`'s first argument, since it runs synchronously during the initial render unlike other hook-callback arguments.
+- Added an exemption for calls to a function named `render` (e.g. `props.render(ref)`, a common render-prop pattern) from the `refPassedToFunction` diagnostic, alongside the existing `mergeRefs`/hook exemptions.
+
+### Changed
+
+- Made lazy-init guard-block detection direction-aware: inside the branch of an `if (ref.current == null)`-style guard that is guaranteed to see `ref.current` as null, only a direct write is now treated as the (single) valid initialization - reads or values passed to a function there are still reported, matching `refs.spec.md`'s `ValidateNoRefAccessInRender` semantics. Reading the already-initialized value back in the other branch (the `if (x.current !== null) { return x.current; }` memoization idiom) remains allowed.
+- Replaced `isRefCurrentNullCheck` with `getRefCurrentNullCheckBranch` in `lib.ts`, which reports which branch of a guard is the null branch instead of just whether the test is a recognized null check.
+- Updated `refs.spec.diff.md` to reflect the fixes above and corrected the "Non-null Lazy Init Guards" entry, which was not an actual gap since `refs.spec.md` itself treats guards like `if (r.current == DEFAULT_VALUE)` as errors.
+
 ## [5.11.0] - 2026-07-05
 
 ### Added

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

@@ -5,6 +5,20 @@ import type { Scope } from "@typescript-eslint/scope-manager";
 import { AST_NODE_TYPES as AST, type TSESTree } from "@typescript-eslint/types";
 import { findVariable } from "@typescript-eslint/utils/ast-utils";
 
+export function isFunctionExpressionLike(node: TSESTree.Node): node is TSESTree.FunctionExpression | TSESTree.ArrowFunctionExpression {
+  return node.type === AST.FunctionExpression || node.type === AST.ArrowFunctionExpression;
+}
+
+export function resolveAlias(name: string, aliases: Map<string, string>): string {
+  const seen = new Set<string>();
+  while (aliases.has(name) && !seen.has(name)) {
+    seen.add(name);
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    name = aliases.get(name)!;
+  }
+  return name;
+}
+
 /**
  * Check if the node is the operand of a `ref.current === null` test inside an IfStatement.
  * @param node The MemberExpression node for ref.current
@@ -52,47 +66,103 @@ export function isInNullCheckTest(node: TSESTree.MemberExpression): boolean {
   return false;
 }
 
-function isBinaryNullCheck(test: TSESTree.Expression, refName: string): boolean {
+function isBinaryNullCheckOperand(a: TSESTree.Node, b: TSESTree.Node, refName: string): boolean {
+  a = Check.isTypeExpression(a) ? Extract.unwrap(a) : a;
+  if (a.type !== AST.MemberExpression) return false;
+  if (Extract.getPropertyName(a.property) !== "current") return false;
+  const obj = Extract.unwrap(a.object);
+  return obj.type === AST.Identifier && obj.name === refName && b.type === AST.Literal && b.value == null;
+}
+
+function isBinaryNullCheck(test: TSESTree.Expression, refName: string): test is TSESTree.BinaryExpression {
   if (test.type !== AST.BinaryExpression) return false;
   if (!/^(===|==|!==|!=)$/.test(test.operator)) return false;
   const { left, right } = test;
-  const checkSides = (a: TSESTree.Node, b: TSESTree.Node) => {
-    a = Check.isTypeExpression(a) ? Extract.unwrap(a) : a;
-    if (a.type !== AST.MemberExpression) return false;
-    if (Extract.getPropertyName(a.property) !== "current") return false;
-    const obj = Extract.unwrap(a.object);
-    return obj.type === AST.Identifier && obj.name === refName && b.type === AST.Literal && b.value == null;
-  };
-  return checkSides(left, right) || checkSides(right, left);
+  return isBinaryNullCheckOperand(left, right, refName) || isBinaryNullCheckOperand(right, left, refName);
 }
 
 /**
- * Check if a test expression is a null check on `ref.current` for a given ref name.
- * Matches forms like `ref.current === null`, `null === ref.current`, `!ref.current`,
- * `!(ref.current === null)`, and their != variants.
+ * Which branch of an `if` statement is guaranteed to observe `ref.current` as `null`/`undefined`,
+ * for a test expression recognized by `isRefCurrentNullCheck`.
+ *
+ * `"consequent"` means the true-branch is the null branch (e.g. `== null`, `=== null`,
+ * `!ref.current`); `"alternate"` means the false-branch is the null branch (e.g. `!= null`,
+ * `!== null`, `!(ref.current === null)`).
+ */
+export type NullCheckBranch = "consequent" | "alternate";
+
+/**
+ * Determine which branch of an `if` statement is guaranteed to see `ref.current` as null, given
+ * a test expression. Returns `null` if the test isn't a recognized null check on `refName`.
  * @param test The test expression to check.
  * @param refName The name of the ref variable.
  */
-export function isRefCurrentNullCheck(test: TSESTree.Expression, refName: string): boolean {
-  // Direct binary check
-  if (isBinaryNullCheck(test, refName)) return true;
+export function getRefCurrentNullCheckBranch(test: TSESTree.Expression, refName: string): NullCheckBranch | null {
+  // Direct binary check: ref.current === null / == null -> consequent is null branch
+  //                       ref.current !== null / != null -> alternate is null branch
+  if (isBinaryNullCheck(test, refName)) {
+    return test.operator === "===" || test.operator === "==" ? "consequent" : "alternate";
+  }
 
   // !ref.current  or  !(ref.current === null)
   if (test.type === AST.UnaryExpression && test.operator === "!") {
     const arg = Extract.unwrap(test.argument);
-    // !ref.current
+    // !ref.current: truthy check, so the true-branch (falsy, i.e. null-like) is the null branch
     if (arg.type === AST.MemberExpression) {
       const obj = Extract.unwrap(arg.object);
-      return obj.type === AST.Identifier
+      const isRefCurrent = obj.type === AST.Identifier
         && obj.name === refName
         && Extract.getPropertyName(arg.property) === "current";
+      return isRefCurrent ? "consequent" : null;
+    }
+    // !(ref.current === null): flip the inner binary check's direction
+    if (arg.type === AST.BinaryExpression) {
+      const inner = getRefCurrentNullCheckBranch(arg, refName);
+      if (inner === "consequent") return "alternate";
+      if (inner === "alternate") return "consequent";
     }
-    // !(ref.current === null)
-    // tsl-ignore dx/no-unsafe-as
-    return isBinaryNullCheck(arg as TSESTree.Expression, refName);
   }
 
-  return false;
+  return null;
+}
+
+/**
+ * Check if a test expression is a null check on `ref.current` for a given ref name.
+ * Matches forms like `ref.current === null`, `null === ref.current`, `!ref.current`,
+ * `!(ref.current === null)`, and their != variants.
+ * @param test The test expression to check.
+ * @param refName The name of the ref variable.
+ */
+export function isRefCurrentNullCheck(test: TSESTree.Expression, refName: string): boolean {
+  return getRefCurrentNullCheckBranch(test, refName) != null;
+}
+
+/**
+ * Check whether `node` (a `ref.current` MemberExpression) is being written to indirectly through
+ * a nested property write, e.g. `ref.current.inner = value` or `ref.current.inner++`.
+ * @param node The MemberExpression node for ref.current
+ */
+export function isNestedRefCurrentWrite(node: TSESTree.MemberExpression): boolean {
+  let outer: TSESTree.Node = node;
+  let sawNesting = false;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    let parent: TSESTree.Node = outer.parent;
+    while (Check.isTypeExpression(parent)) parent = parent.parent;
+    if (parent.type === AST.MemberExpression && (parent.object === outer || Extract.unwrap(parent.object) === outer)) {
+      outer = parent;
+      sawNesting = true;
+      continue;
+    }
+    if (!sawNesting) return false;
+    if (parent.type === AST.AssignmentExpression) {
+      return parent.left === outer || Extract.unwrap(parent.left) === outer;
+    }
+    if (parent.type === AST.UpdateExpression) {
+      return parent.argument === outer || Extract.unwrap(parent.argument) === outer;
+    }
+    return false;
+  }
 }
 
 export function isInitializedFromRef(context: RuleContext, name: string, initialScope: Scope) {