refactor(plugin): split rules into per-file modules with TSESTree-narrowed type layer

[aidenybai]

Refactor-only port of the code-organization ideas from #217 to main. Zero behavior drift, no rules added/removed, no scoring or CLI changes, no v2 surface.

Summary

Two stacked commits, each independently testable:

1. refactor(plugin): split helpers/types into single-purpose files with TSESTree-narrowed isNodeOfType (06e9687)

   • Replaces monolithic plugin/helpers.ts (~580 LOC) and plugin/types.ts (~30 LOC) with 50 single-purpose files under plugin/utils/
   • Adds @typescript-eslint/types as a devDependency and wires it through EsTreeNodeOfType<T> = Extract<TSESTree.Node, { type: T }> so isNodeOfType(node, "MemberExpression") narrows to the real estree shape (node.computed: boolean, node.arguments.length: number, etc.) instead of any
   • Old plugin/helpers.ts and plugin/types.ts become 8- and 25-line re-export shims so nothing else needs to change to import them
   • Adds defineRule helper in plugin/utils/define-rule.ts (identity function, used by PR 2)
   • Two narrow EsTreeNode | null | undefined widenings in react-native.ts local helpers (forced by PR 1's tighter parent type)

2. refactor(plugin): split each rule into its own file with defineRule wrapper (5f689e7)

   • Splits 16 monolithic plugin/rules/<bucket>.ts files (10,368 LOC) into 179 per-rule files under plugin/rules/<bucket>/<rule>.ts
   • Each rule wraps with defineRule<Rule>({...}) and only imports the helpers it uses
   • Private helpers used by only one rule are inlined into that rule's file; helpers shared across rules are duplicated per-consumer
   • Bucket files become 12-24 line re-export barrels so plugin/index.ts and external consumers keep working unchanged
   • Each rule's recommendation / examples metadata fields are now ready to be added per-file in a follow-up

What this is NOT

Of the v2 PR (#217), only the code-organization ideas came across. None of these are in this branch:

• ~70 new rules (i18n, mobx, shadcn, storybook, swr, tanstack-ai, react-hook-form, react-three-fiber, testing-library)
• Score formula changes (per-category cap, log amplification, info-issue exclusion)
• Rule false-positive tweaks (radix-aschild, rn-no-raw-text, no-eval test-noise, etc.)
• CLI rewrite (--unstaged, --changed, annotations behavior changes)
• SDK / createReactDoctor / inspectReactProject surface
• Codebase analyzer rewrite (shared module graph, plugins)
• Hierarchical typed errors
• Removal of browser-poc, knip, bippy, wasm parser
• Removal of eslint-plugin-react-you-might-not-need-an-effect

Verification

A whitespace + type-only-widening normalized byte-comparison of every rule body confirms:

• 179 of 179 rules byte-identical (after normalizing Prettier reformatting and the one EsTreeNode | null | undefined widening)
• plugin/index.ts rule registry: byte-identical (same rule IDs, same identifiers, same order)
• plugin/constants.ts: byte-identical
• No rules added, no rules removed

Branch totals vs main: 251 files changed, +13,241 / −11,058. 734 tests pass, lint clean, format clean, typecheck clean. No new runtime deps.

Test plan

• pnpm typecheck clean on both commits
• pnpm test — 734/734 tests pass on both commits
• pnpm lint — 0 warnings, 0 errors
• pnpm format — clean
• Rule body byte-comparison vs main shows zero behavior drift

---

Note

Medium Risk
Large-scale refactor that moves/rewires many rule implementations and helper imports; risk is mainly in missed exports/path resolution or subtle type-narrowing fallout despite intended no behavior change.

Overview
Refactors react-doctor’s ESLint-style plugin code by extracting the previously monolithic helpers.ts and several rule “bucket” modules into many single-purpose files under src/plugin/utils/ and src/plugin/rules/<bucket>/, while keeping the public entrypoints as thin re-export shims.

Adds a shared createDeprecatedReactImportRule utility for React 19 deprecation checks and wraps individual rule modules with defineRule, plus a devDependency on @typescript-eslint/types to support a tighter, TSESTree-narrowed node/type layer.

^{Reviewed by Cursor Bugbot for commit 6002723. Bugbot is set up for automated code reviews on this repo. Configure here.}

[reactreview]

🔴 React Review — 0/100 (unchanged) · 0 ❌ errors · 13 ⚠️ 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 13 warnings. This PR leaves the React health score unchanged.

<file name="packages/react-doctor/src/plugin/rules/state-and-effects/prefer-use-sync-external-store.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/state-and-effects/prefer-use-sync-external-store.ts:204">
Severity: Warning

array.find() in a loop is O(n*m) — build a Map for O(1) lookups

Build an index `Map` once outside the loop instead of `array.find(...)` inside it

Rule: `js-index-maps`
</violation>

</file>

<file name="packages/react-doctor/src/plugin/rules/performance/rerender-transitions-scroll.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/performance/rerender-transitions-scroll.ts:70">
Severity: Warning

cursor.callee.name is read 3 times inside this loop — hoist into a const at the top of the loop body

Hoist the deep member access into a const at the top of the loop body: `const { x, y } = obj.deeply.nested`

Rule: `js-cache-property-access`
</violation>

</file>

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

<violation number="1" location="packages/react-doctor/src/plugin/rules/state-and-effects/no-mirror-prop-effect.ts:133">
Severity: Warning

array.find() in a loop is O(n*m) — build a Map for O(1) lookups

Build an index `Map` once outside the loop instead of `array.find(...)` inside it

Rule: `js-index-maps`
</violation>

</file>

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

<violation number="1" location="packages/react-doctor/src/plugin/rules/state-and-effects/no-effect-event-handler.ts:23">
Severity: Warning

.filter().map() iterates the array twice — combine into a single loop with .reduce() or for...of

Combine `.map().filter()` (or similar chains) into a single pass with `.reduce()` or a `for...of` loop to avoid iterating the array twice

Rule: `js-combine-iterations`
</violation>

</file>

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

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

.filter().map() iterates the array twice — combine into a single loop with .reduce() or for...of

Combine `.map().filter()` (or similar chains) into a single pass with `.reduce()` or a `for...of` loop to avoid iterating the array twice

Rule: `js-combine-iterations`
</violation>

</file>

<file name="packages/react-doctor/src/plugin/utils/are-expressions-structurally-equal.ts">

<violation number="1" location="packages/react-doctor/src/plugin/utils/are-expressions-structurally-equal.ts:32">
Severity: Warning

.every() over an array compared to another array — short-circuit with `a.length === b.length && a.every(...)` so unequal-length arrays exit immediately

Short-circuit with `a.length === b.length && a.every((x, i) => x === b[i])` — unequal-length arrays exit immediately

Rule: `js-length-check-first`
</violation>

</file>

<file name="packages/react-doctor/src/plugin/rules/server/server-sequential-independent-await.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/server/server-sequential-independent-await.ts:21">
Severity: Warning

declarator.id.type is read 3 times inside this loop — hoist into a const at the top of the loop body

Hoist the deep member access into a const at the top of the loop body: `const { x, y } = obj.deeply.nested`

Rule: `js-cache-property-access`
</violation>

</file>

<file name="packages/react-doctor/src/plugin/rules/tanstack-start/tanstack-start-server-fn-method-order.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/tanstack-start/tanstack-start-server-fn-method-order.ts:43">
Severity: Warning

array.indexOf() 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>

<file name="packages/react-doctor/src/plugin/rules/tanstack-start/tanstack-start-route-property-order.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/tanstack-start/tanstack-start-route-property-order.ts:30">
Severity: Warning

array.indexOf() 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>

<file name="packages/react-doctor/src/plugin/rules/react-ui/no-space-on-flex-children.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/react-ui/no-space-on-flex-children.ts:23">
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>

<file name="packages/react-doctor/src/plugin/rules/design/no-inline-bounce-easing.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/design/no-inline-bounce-easing.ts:24">
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>

<file name="packages/react-doctor/src/plugin/rules/design/no-gradient-text.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/design/no-gradient-text.ts:27">
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>

<file name="packages/react-doctor/src/plugin/rules/react-ui/no-bold-heading.ts">

<violation number="1" location="packages/react-doctor/src/plugin/rules/react-ui/no-bold-heading.ts:55">
Severity: Warning

new RegExp() inside a loop — hoist to a module-level constant

Hoist `new RegExp(...)` (or large regex literals) to a module-level constant so it isn't recompiled on every loop iteration

Rule: `js-hoist-regexp`
</violation>

</file>

^{Reviewed by react-review for commit 6002723. 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 13, 2026 4:40pm

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

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

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