feat: comprehensive useEffect analyzer expansion (3 rules + 2 extensions)

[aidenybai]

Three new rules and two detector extensions targeted at the gaps between the existing rule set and React's full effect-related guidance. Builds on the smaller follow-up PRs already in flight (#153 detector widening, #154 prefer-use-sync-external-store, #155 no-event-trigger-state, #156 no-effect-chain) without overlapping them.

New rules

no-mirror-prop-effect (warn)

Flags the canonical "mirror a prop into local state via a useEffect" anti-pattern from §1 of You Might Not Need an Effect:

function Form({ value }) {
  const [draft, setDraft] = useState(value);              // mirror
  useEffect(() => { setDraft(value); }, [value]);         // sync
}

Both no-derived-state-effect and no-derived-useState already nudge at parts of this; this rule produces a single, more actionable diagnostic that names the prop and recommends deleting both. Detector reuses the prop-stack scaffolding from no-prop-callback-in-effect / no-derived-useState. Recognizes both useState(prop) and useState(prop.x) MemberExpression variants. Structural equality between the useState initializer and the setX(...) argument is required, so setDraft(value.toUpperCase()) (a transformation, not a mirror) is correctly not flagged.

no-mutable-in-deps (error)

Flags mutable values in a hook's deps array — they don't trigger re-runs because mutations happen outside React's data flow. From Lifecycle of Reactive Effects §"Can global or mutable values be dependencies?":

Mutable values aren't reactive. Even if you specified it in the dependencies, React wouldn't know to re-synchronize the Effect.

Two shapes:

• MemberExpression rooted in a known mutable global — location.pathname, window.innerWidth, document.title, navigator.onLine, history.state, screen.width, performance.now
• MemberExpression <x>.current where <x> is a useRef binding declared in the same component

Bare ref Identifiers (containerRef) and regular state.field reads (state IS reactive) are intentionally not flagged.

effect-needs-cleanup (error)

Flags useEffect bodies that subscribe or schedule but never return a cleanup. Without it the registration leaks on every effect re-run and on unmount; StrictMode in development surfaces this as "you forgot to clean up an effect."

Recognizes three subscribe-shaped families and three cleanup forms:

Subscribe family	Cleanup family
addEventListener / subscribe / addListener / on / watch / listen / sub	removeEventListener / unsubscribe / removeListener / off / unwatch / unlisten / unsub
setInterval / setTimeout	clearInterval / clearTimeout
any of the above	bare return unsubscribe (Identifier — caller bound it)
any of the above	return () => unsubscribe() / cleanup() / dispose() / destroy() / teardown()

Detector extensions (no new rule IDs)

rerender-dependencies — flag inline function literals

The rule already flagged ObjectExpression and ArrayExpression in deps; an inline ArrowFunctionExpression / FunctionExpression has the same identity-instability problem. Closes a coverage gap from Removing Effect Dependencies §"Does some reactive value change unintentionally?".

rerender-functional-setstate — flag array/object spread

The rule already flagged arithmetic and ++ / --. The array-spread / object-spread shape is the most common stale-closure trap inside subscription handlers and is exactly what Removing Effect Dependencies §"Are you reading some state to calculate the next state?" addresses:

setMessages([...messages, receivedMessage]);  // 🔴 now flagged
setProfile({ ...profile, name: input });      // 🔴 now flagged

The recommended fix in both cases is the functional-updater shape (prev => [...prev, item]) which removes the need for the state in the deps array.

Tests

23 new regression cases across the five additions, covering both positive triggers and article-cited GOOD shapes that must NOT be flagged.

Rule / extension	Flag cases	No-flag cases
no-mirror-prop-effect	2 (Identifier prop, prop.x member)	3 (uncontrolled-with-key, derive-not-mirror, transform-not-mirror)
no-mutable-in-deps	3 (location.pathname, containerRef.current, window.innerWidth)	2 (bare ref Identifier, state.field MemberExpression)
effect-needs-cleanup	3 (addEventListener, setInterval, store.subscribe)	3 (bare-return, removeEventListener, clearInterval)
rerender-functional-setstate spread	2 (array spread, object spread)	2 (functional updater, unrelated spread source)
rerender-dependencies inline-fn	2 (arrow in useEffect, fn-expr in useCallback)	1 (stable Identifier deps)

Plus 5 fixture-level smoke tests in run-oxlint.test.ts.

Full suite: 506/506 passing locally. Lint, typecheck, format clean.

Coverage map after this PR

The full set of "You Might Not Need an Effect" sections now has detector coverage:

§	Anti-pattern	Rule(s)
§1	Updating state based on props/state	no-derived-state-effect, no-derived-useState, no-mirror-prop-effect (this PR)
§2	Caching expensive calculations	no-derived-state-effect (memo branch in #153)
§3	Resetting all state on prop change	no-derived-state-effect (reset branch)
§4	Adjusting some state on prop change	no-set-state-in-render whitelist + no-derived-state-effect
§5	Sharing logic between event handlers	no-effect-event-handler (widened in #153)
§6	Sending a POST request	no-event-trigger-state (#155)
§7	Chains of computations	no-effect-chain (#156)
§8	Initializing the application	intentionally skipped (FP risk)
§9 / §10	Notifying parent / passing data to parent	no-prop-callback-in-effect
§11	Subscribing to an external store	prefer-use-sync-external-store (#154)
§12	Fetching data	no-fetch-in-effect, query-no-query-in-effect, tanstack-start-no-useeffect-fetch

Plus reactivity-hygiene rules from Removing Effect Dependencies and Lifecycle of Reactive Effects: rerender-dependencies (objects, arrays, functions), no-mutable-in-deps, effect-needs-cleanup, rerender-functional-setstate (spread cases), no-effect-event-in-deps, advanced-event-handler-refs.

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-doctor-website	Ready	Preview, Comment	May 8, 2026 9:17am

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0bd6a16. Configure here.}

[cursor]

Mutable-global check ignores local variable shadowing

High Severity

findMutableDepIssue flags any MemberExpression whose root identifier name is in MUTABLE_GLOBAL_ROOTS (e.g. location, history, navigator), but never checks whether that identifier is actually the browser global or a locally-scoped variable. React Router's useLocation() canonically binds to const location = useLocation(), and [location.pathname] in a deps array is a perfectly valid reactive dependency. The rule would report it at error severity as a "mutable global," producing a false positive in virtually every React Router codebase. The ref.current path already does scope analysis via collectUseRefBindingNames; the global path needs analogous shadowing detection.

Additional Locations (1)

• packages/react-doctor/src/plugin/constants.ts#L397-L406

 

^{Reviewed by Cursor Bugbot for commit 0bd6a16. Configure here.}