feat(oxlint): natively port eslint-plugin-react-you-might-not-need-an-effect (8 rules)

[aidenybai]

Summary

Brings the 8 rules from eslint-plugin-react-you-might-not-need-an-effect natively into oxlint-plugin-react-doctor, using a real eslint-scope analyzer (not an approximation), and retires the runtime peer-dep surface that loaded the upstream plugin as effect/* rules.

Upstream snapshot: 4c71faaa7623d2d5feb33983dc2ebcc08206bcc5 (HEAD of main, v0.10.1, NickvanDyke, MIT-licensed). Full attribution and the known-divergence list live in packages/oxlint-plugin-react-doctor/src/plugin/rules/state-and-effects/effect/SOURCE.md.

Parity status

147 / 148 upstream test cases pass — every valid: and invalid: case from test/rules/<rule>.test.js runs through our oxlint plugin and matches upstream's expected error count. The 1 remaining case is upstream's own todo: true (renamed-useState import — upstream documents this as unsupported).

Rule	Upstream cases	Pass	Skip (todo: true)
no-derived-state	52	51	1
no-chain-state-updates	11	11	0
no-event-handler	10	10	0
no-adjust-state-on-prop-change	7	7	0
no-reset-all-state-on-prop-change	15	15	0
no-pass-live-state-to-parent	20	20	0
no-pass-data-to-parent	21	21	0
no-initialize-state	12	12	0
Total	148	147	1

Ported rule IDs

All eight register under the react-doctor/* namespace (matching upstream rule IDs):

Rule	Upstream file
react-doctor/no-derived-state	src/rules/no-derived-state.js
react-doctor/no-chain-state-updates	src/rules/no-chain-state-updates.js
react-doctor/no-event-handler	src/rules/no-event-handler.js
react-doctor/no-adjust-state-on-prop-change	src/rules/no-adjust-state-on-prop-change.js
react-doctor/no-reset-all-state-on-prop-change	src/rules/no-reset-all-state-on-prop-change.js
react-doctor/no-pass-live-state-to-parent	src/rules/no-pass-live-state-to-parent.js
react-doctor/no-pass-data-to-parent	src/rules/no-pass-data-to-parent.js
react-doctor/no-initialize-state	src/rules/no-initialize-state.js

Diagnostic messages match upstream verbatim with {{state}} / {{arguments}} / {{prop}} template variables substituted in JS.

These coexist with our existing thematically-related rules (no-derived-state-effect, no-effect-chain, no-event-trigger-state, no-prop-callback-in-effect); the IDs are distinct and the rules target different code shapes.

Architecture: real eslint-scope analyzer

The first iteration of this PR built a hand-rolled AST-only analyze-component-bindings.ts table that approximated scope analysis. Per feedback, that approximation has been replaced with a real eslint-scope ScopeManager so the port faithfully mirrors upstream's context.sourceCode.getScope / ref.resolved.defs[].node.init semantics. The hand-rolled analyzer is deleted.

New infrastructure under state-and-effects/utils/effect/:

• get-program-analysis.ts — Lazy WeakMap<Program, ScopeManager> cache keyed on the live Program node. Walks the AST once, strips parent pointers (eslint-scope chokes on cycles), runs analyze(), restores the parents synchronously, returns the cached manager. All 8 rules share one analysis per file. Also exposes getScopeForNode(node) and getOuterScopeContaining(node) helpers that pick the innermost (module / function / block) scope by smallest containing range, with <= tiebreak so the module scope wins over the equally-sized global scope.
• ast.ts — 1:1 port of upstream src/util/ast.js: ascend / descend / getDownstreamRefs / getUpstreamRefs / getRef / getCallExpr / getArgsUpstreamRefs / isSynchronous / isEventualCallTo. Uses eslint-visitor-keys.KEYS as the static visitorKeys table (replacing upstream's context.sourceCode.visitorKeys).
• react.ts — 1:1 port of upstream src/util/react.js: isReactFunctionalComponent / isReactFunctionalHOC / isCustomHook / isUseEffect / isState / isStateSetter / isProp / isConstant / isRef / isRefCurrent / isStateSetterCall / isPropCall / isRefCall / getEffectFn / getEffectFnRefs / getEffectDepsRefs / getUseStateDecl / hasCleanup / findContainingNode. The separately-wrapped HOC detection (const Wrapped = withRouter(MyComponent), inject('x')(observer(MyComponent))) goes through the scope manager's Variable list to find every reference of the binding.
• stringify-expression-snippet.ts — Substitute for upstream's context.sourceCode.getText() used only in no-initialize-state's diagnostic data field (oxlint plugins don't expose source text).

Each ported rule (e.g. no-derived-state.ts) is a near-verbatim transliteration of the corresponding upstream src/rules/<name>.js.

Parity test infrastructure

• /tmp/convert-tests.mjs (utility, not committed) loads each upstream test/rules/<name>.test.js with a stubbed MyRuleTester to capture every {name, code, todo, errors} case as JSON.
• packages/react-doctor/tests/regressions/state-rules/effect-fixtures/ ships the 8 captured JSON fixture files — committed so the parity baseline is reproducible without re-running the converter.
• _effect-parity-runner.ts drives the fixtures: each case becomes one it(...) that wraps the upstream snippet in src/Component.tsx, runs oxlint, asserts hits.length matches upstream's expected error count, and skips on todo: true.
• parity-<rule>.test.ts (8 files) invoke the runner per rule.

What's removed

• YOU_MIGHT_NOT_NEED_EFFECT_RULES map in packages/core/src/runners/oxlint/external-plugin-rules.ts.
• resolveYouMightNotNeedEffectPlugin / YOU_MIGHT_NOT_NEED_EFFECT_NAMESPACE in plugin-resolution.ts.
• The resolver call + rule merge in createOxlintConfig.
• eslint-plugin-react-you-might-not-need-an-effect optional peer + devDep entries from @react-doctor/core and react-doctor package.json.
• The three scan-resilience.test.ts assertions about loading the external plugin → replaced with a single assertion that the 8 ported rules are enabled as react-doctor/* in the generated oxlint config.

Docs / changeset

• packages/oxlint-plugin-react-doctor/README.md: new "You Might Not Need an Effect" section listing the 8 ported rule IDs with one-line descriptions; bumped rule count 179 → 187.
• packages/react-doctor/README.md: dropped eslint-plugin-react-you-might-not-need-an-effect from the "Optional companion plugins" table; added a paragraph naming the 8 react-doctor/* IDs that now subsume it.
• .changeset/port-effect-rules.md: patch-level changeset for @react-doctor/core, oxlint-plugin-react-doctor, and react-doctor.

Verification

pnpm typecheck        ✓ 10/10 packages clean
pnpm test             ✓ 1297 passed | 1 skipped | 0 failures (101 test files)
pnpm lint             ✓ 0 warnings, 0 errors (584 files)
pnpm format           ✓ applied (718 files)

End-to-end smoke test against packages/website

$ node packages/react-doctor/bin/react-doctor.js packages/website --verbose --offline --json
Total diagnostics: 11
By rule:
     3  react-doctor/nextjs-no-img-element
     3  react-doctor/async-defer-await
     2  react-doctor/no-initialize-state   ← ported rule fires
     1  react-doctor/effect-needs-cleanup
     1  react-doctor/nextjs-missing-metadata
     1  react-doctor/no-inline-exhaustive-style

Ported-rule hits: 2
  no-initialize-state: src/components/terminal.tsx:261 - Avoid initializing state in an effect. Instead, initialize "state"'s `useState()...
  no-initialize-state: src/components/terminal.tsx:314 - Avoid initializing state in an effect. Instead, initialize "state"'s `useState()...

Verbatim message text matches upstream. The diagnostics fire as react-doctor/no-initialize-state (not effect/no-initialize-state), confirming the namespace migration is live end-to-end.

New deps

• eslint-scope (BSD-2-Clause, transitively present before; now a direct dep of oxlint-plugin-react-doctor)
• eslint-visitor-keys (Apache-2.0, ditto)
• @types/eslint-scope / @types/eslint-visitor-keys (devDeps)

Notes

• The PR was originally pushed directly to main by mistake. Those two commits were reverted on main (d7efa43, 3bb230f) and the work is now isolated on this cursor/ branch.

  

[reactreview]

🔴 React Review — 0/100 (unchanged) · 0 ❌ errors · 2 ⚠️ warnings

Copy prompt for agent

Check if these React Review issues are valid. If so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.

Run this before and after your changes to verify the result:
npx react-doctor@latest --verbose --diff

Do not modify the react-doctor configuration unless explicitly asked.
Fix the underlying code issues instead of changing or suppressing the rules.

React Review found 0 errors and 2 warnings. This PR leaves the React health score unchanged.

<file name="packages/react-doctor/tests/regressions/state-rules/_effect-parity-runner.ts">

<violation number="1" location="packages/react-doctor/tests/regressions/state-rules/_effect-parity-runner.ts:75">
Severity: Warning

await inside a for…of loop runs the calls sequentially — for independent operations, collect them and use `await Promise.all(items.map(...))` to run them concurrently

Collect the items and use `await Promise.all(items.map(...))` to run independent operations concurrently

Rule: `async-await-in-loop`
</violation>

</file>

<file name="packages/oxlint-plugin-react-doctor/src/plugin/rules/state-and-effects/utils/effect/react.ts">

<violation number="1" location="packages/oxlint-plugin-react-doctor/src/plugin/rules/state-and-effects/utils/effect/react.ts:110">
Severity: Warning

array.includes() in a loop is O(n) per call — convert to a Set for O(1) lookups

Use a `Set` or `Map` for repeated membership tests / keyed lookups — `Array.includes`/`find` is O(n) per call

Rule: `js-set-map-lookups`
</violation>

</file>

^{Reviewed by react-review for commit 81ccfc6. Configure here.}

[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 17, 2026 3:29am

[cursor]

countUseStates walks nested scopes, diverging from upstream

Medium Severity

countUseStates uses getDownstreamRefs which walks the entire AST subtree (including nested callbacks, effects, and other closures), whereas the upstream uses scope.references which only returns references at the component's own scope level. This means any state variable referenced inside a nested function (e.g. a useCallback, event handler, or another effect) gets counted extra times, inflating the count. Since the rule checks stateSetterRefs.length !== countUseStates(...), an inflated count causes false negatives — the rule silently skips cases it should flag.

 

^{Reviewed by Cursor Bugbot for commit 288732c. Configure here.}

[cursor]

Deprecated @types stubs listed as production dependencies

Low Severity

@types/eslint-scope and @types/eslint-visitor-keys are placed under dependencies instead of devDependencies. Both are deprecated stub packages (the main packages ship their own types), meaning they add unnecessary weight to every consumer's node_modules at install time without providing any runtime value.

 

^{Reviewed by Cursor Bugbot for commit 288732c. Configure here.}

[cursor]

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

There are 3 total unresolved issues (including 2 from previous reviews).

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

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