feat: add prefer-use-effect-event rule

[aidenybai]

New rule (severity: warn) inspired by Vercel Labs' advanced-use-latest and React's Separating Events from Effects.

What it catches

When a function-typed reactive value is read from an effect only inside a sub-handler, listing it in the dep array forces the whole effect to re-synchronize on every parent render. The fix is useEffectEvent:

function SearchInput({ onSearch }) {
  const [query, setQuery] = useState('');
  useEffect(() => {
    const id = setTimeout(() => onSearch(query), 300);  // ← sub-handler
    return () => clearTimeout(id);
  }, [query, onSearch]);                                 // 🔴 onSearch in deps
}

function SearchInput({ onSearch }) {
  const [query, setQuery] = useState('');
  const onSearchEvent = useEffectEvent(onSearch);
  useEffect(() => {
    const id = setTimeout(() => onSearchEvent(query), 300);
    return () => clearTimeout(id);
  }, [query]);                                           // ✅
}

Detector — four pre-conditions, all must hold

Chosen to keep real-world false positives near zero:

1. useEffect with a dep array of ≥ 2 Identifier elements — single-dep effects don't meaningfully benefit from the migration.
2. At least one dep is function-typed:
   • a destructured prop (uses the existing prop-stack scaffold), or
   • a local declared via const F = useCallback(...)
3. Every read of F inside the effect body sits inside a sub-handler:
   • direct callee: setTimeout / setInterval / requestAnimationFrame / requestIdleCallback / queueMicrotask
   • member callee: subscribe / addEventListener / addListener / on / watch / listen / sub
   • the sub-handler can be passed inline (setTimeout(() => …)) or via a const-bound local (const handler = () => …; window.addEventListener('keydown', handler);)
4. F is NEVER read at the effect's own top level — a synchronous call there is a true reactive read; useEffectEvent isn't appropriate.

React version gating

useEffectEvent is a React 19+ Hook. Recommending it on React 18 (or older) projects produces noisy diagnostics for an API the user doesn't have, so the rule is registered in the existing VERSION_GATED_RULE_IDS map under a new USE_EFFECT_EVENT_MIN_MAJOR = 19 constant.

Detected reactMajorVersion	Behavior
19 (or higher)	rule fires
18, 17 (or lower)	rule is filtered out before oxlint runs
null (couldn't detect — workspace tag, missing dep, exotic spec)	rule fires — same convention as every other version-gated rule, so we never silently swallow real findings

Tests — 12 regression cases

Detector behavior (8):

• ✅ flags canonical setTimeout shape (Vercel advanced-use-latest)
• ✅ flags addEventListener with const-bound handler + multi-deps
• ✅ flags store.subscribe handler that calls a prop callback
• ✅ flags useCallback-bound local invoked only from setInterval
• ❌ does NOT flag callback read at the effect's top level (true reactive read)
• ❌ does NOT flag when the dep is not function-typed (state, plain identifier)
• ❌ does NOT flag a single-dep effect (no benefit)
• ❌ does NOT flag addEventListener with the callback as the only dep

Version gating (4):

• ✅ explicit reactMajorVersion: 19 → fires
• ❌ explicit reactMajorVersion: 18 → does not fire
• ❌ explicit reactMajorVersion: 17 → does not fire
• ✅ reactMajorVersion: null (unknown) → fires

Plus a smoke test in run-oxlint.test.ts against a fixture component.

Coverage map for the useEffect track

After this PR, the comprehensive useEffect analyzer family across all open PRs covers:

Article / source	Rule
§1 mirroring	no-derived-state-effect, no-derived-useState, no-mirror-prop-effect (#157)
§2 expensive caching	no-derived-state-effect memo branch (#153)
§3 / §4 reset/adjust	no-derived-state-effect, no-set-state-in-render
§5 shared logic	no-effect-event-handler widened (#153)
§6 trigger state	no-event-trigger-state (#155)
§7 chains	no-effect-chain (#156)
§9 / §10 parent notify	no-prop-callback-in-effect
§11 external store	prefer-use-sync-external-store (#154)
§12 fetching	no-fetch-in-effect
Separating Events from Effects	prefer-use-effect-event (this PR, React 19+)
Removing Effect Dependencies (mutable deps)	no-mutable-in-deps (#157)
Removing Effect Dependencies (functional setState spread)	rerender-functional-setstate extended (#157)
Removing Effect Dependencies (inline-fn deps)	rerender-dependencies extended (#157)
Lifecycle of Reactive Effects (cleanup)	effect-needs-cleanup (#157)

Checks

493/493 tests passing locally. Lint, typecheck, format clean. No changeset (per project preference).

  

[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:22am

[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 8d89540. Configure here.}