refactor: split src/utils/ into src/core/{config,detection,diagnostics,scoring,runners}/ + src/cli/ by aidenybai · Pull Request #224 · millionco/react-doctor

aidenybai · 2026-05-13T17:12:43Z

Final structural refactor in the series (#218 plugin/, #220 cli/, #221 scan/, #222 drop browser-poc, #223 dead-code). Carves the 68-file `src/utils/` dumping ground into purpose-built directories.

New layout

```
src/
├── cli/ (26 files) presentation: prompts, highlighter, spinner,
│ logger, render-*, json-report builders, ...
├── core/ (7 root + 5 subdirs = 55 files)
│ ├── config/ (11) config loading, root-dir, ignore patterns,
│ │ glob matching, gitattributes, validation
│ ├── detection/ (6) project discovery, version parsing,
│ │ package.json reading, monorepo root
│ ├── diagnostics/ (12) combine/filter/suppress/merge, jsx-opener-span,
│ │ disable-directive walks
│ ├── scoring/ (6) score calc (local + remote), breakdown,
│ │ reduced-motion, proxy fetch
│ └── runners/ (13) oxlint + knip + their config builders,
│ include-path resolution, Node compat, diff
│ (root: group-by, is-file, is-plain-object, to-relative-path,
│ read-file-lines-node, build-json-report, build-json-report-error)
├── plugin/ (unchanged from #218)
├── scan.ts, index.ts, errors.ts, types.ts, constants.ts,
└── oxlint-config.ts, eslint-plugin.ts, install-skill.ts
```

`src/utils/` no longer exists.

How it was done

A one-shot codemod performed all 68 file moves via `git mv` (so every rename preserves blame / `git log --follow` history) and rewrote every relative import across the package + tests (98 importer files touched) to the new paths.

Manual fixes after the mechanical move

`src/core/runners/run-oxlint.ts` — resolved its built plugin via `path.resolve(currentDirectory, "../../dist/react-doctor-plugin.js")`. With 1 extra level of nesting (was 2 deep, now 3 deep) this needed to become `../../../dist/react-doctor-plugin.js`.
`tests/regressions/scan-resilience.test.ts` — read a source file by hardcoded path (`src/utils/calculate-score-locally.ts`) to assert no `fetch(` reference. Updated to the new location (`src/core/scoring/calculate-score-locally.ts`).

Verification

128 files changed, +237 / −222 (almost entirely import-path edits)
`pnpm typecheck` — clean
`pnpm test` — 734/734 pass
`pnpm lint` — 0 warnings, 0 errors
`pnpm format:check` — clean
`pnpm build` — produces identical `dist/cli.js`, `dist/index.js`, `dist/eslint-plugin.js`, `dist/react-doctor-plugin.js`
No public API change

What's NOT in this PR

No logic changes — every moved file's body is byte-identical except for its imports
No additional file splits or merges
Top-level files (`scan.ts`, `index.ts`, `errors.ts`, `types.ts`, `constants.ts`, `oxlint-config.ts`, `eslint-plugin.ts`, `install-skill.ts`) stayed at `src/` root — moving them is a behavior-affecting (public API) change for separate PRs

Test plan

typecheck / test / lint / format all clean
`git mv` preserves rename history (verify with `git log --follow packages/react-doctor/src/core/scoring/calculate-score.ts`)
dist build outputs identical
`src/utils/` directory removed

Note

Medium Risk
Mostly mechanical file moves and import rewrites, but touches many runtime entrypoints (CLI, core/inspect, report building) and adjusts the oxlint plugin resolution path, so any missed path update could cause runtime module resolution failures.

Overview
Refactors react-doctor’s internal layout by moving the former src/utils grab-bag into src/core/* (config, detection, diagnostics, scoring, runners) and src/cli, updating imports across the CLI, programmatic entrypoints, and tests accordingly.

Renames the main scanning API from scan/ScanOptions/ScanResult to inspect/InspectOptions/InspectResult, and updates JSON report building to consume the new result type.

Includes a small functional fix in core/runners/run-oxlint.ts to resolve the built react-doctor-plugin.js from the new nested location (../../../dist/...).

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

…ction,diagnostics,scoring,runners}/ + src/cli/ Final big organizational refactor in the series (#218 plugin/, #220 cli/, #221 scan/, #222 drop browser-poc, #223 dead-code). Carves the 68-file src/utils/ dumping ground into purpose-built directories. New layout: src/cli/ presentation (26 files) + prompts.ts, highlighter.ts, spinner.ts, logger.ts + colorize-by-score.ts, format-error-chain.ts + indent-multiline-text.ts, wrap-indented-text.ts + build-hidden-diagnostics-summary.ts + should-auto-select-current-choice.ts, should-select-all-choices.ts + detect-agents.ts, to-display-name.ts + (existing cli/ files: index.ts, render-*.ts, etc.) src/core/ core logic (7 files at root + 5 subdirs) build-json-report.ts shared JSON reporting (CLI + public API) build-json-report-error.ts shared JSON error envelope group-by.ts, is-file.ts generic primitives is-plain-object.ts, to-relative-path.ts read-file-lines-node.ts config/ (11) config loading, root-dir resolution, ignore patterns, glob matching, gitattributes parsing, validation detection/ (6) project discovery, react/tailwind major-version parsing, package.json reading, monorepo root detection diagnostics/ (12) combine/filter/suppress/merge, jsx-opener-span lookup, disable-directive walks scoring/ (6) local + remote score calc, score breakdown, reduced-motion check, proxy fetch runners/ (13) oxlint + knip + their config builders, include-path computation, Node-version compat, diff-files src/plugin/ (unchanged from #218) scan.ts, index.ts, errors.ts, types.ts, constants.ts, oxlint-config.ts, eslint-plugin.ts, install-skill.ts top-level Driven by a one-shot codemod that performed the moves via `git mv` (so all 68 file renames preserve blame/log history) and rewrote every relative import in the package + tests (98 importer files touched) to the new paths. One non-mechanical fix needed after the move: src/core/runners/run-oxlint.ts resolved its built plugin via `../../dist/react-doctor-plugin.js` -- with 1 extra level of nesting that needs to be `../../../dist/react-doctor-plugin.js`. One test fixed: tests/regressions/scan-resilience.test.ts read a source file by hardcoded path (`src/utils/calculate-score-locally.ts`) to assert no `fetch(` reference -- updated to the new location (`src/core/scoring/calculate-score-locally.ts`). Verification: - 128 files changed, +237 / -222 (almost entirely import-path edits) - typecheck/lint/format clean - 734/734 tests pass - build produces identical dist/cli.js, dist/index.js, etc. - No public API change - src/utils/ no longer exists

reactreview · 2026-05-13T17:12:48Z

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

<file name="packages/react-doctor/src/core/runners/resolve-compatible-node.ts">

<violation number="1" location="packages/react-doctor/src/core/runners/resolve-compatible-node.ts:54">
Severity: Warning

.map().filter() 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>

<violation number="2" location="packages/react-doctor/src/core/runners/resolve-compatible-node.ts:54">
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/core/runners/can-oxlint-extend-config.ts">

<violation number="1" location="packages/react-doctor/src/core/runners/can-oxlint-extend-config.ts:45">
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>

<violation number="2" location="packages/react-doctor/src/core/runners/can-oxlint-extend-config.ts:50">
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/core/diagnostics/filter-diagnostics.ts">

<violation number="1" location="packages/react-doctor/src/core/diagnostics/filter-diagnostics.ts:53">
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>

<violation number="2" location="packages/react-doctor/src/core/diagnostics/filter-diagnostics.ts:78">
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/core/detection/discover-project.ts">

<violation number="1" location="packages/react-doctor/src/core/detection/discover-project.ts:214">
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>

<violation number="2" location="packages/react-doctor/src/core/detection/discover-project.ts:227">
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>

<violation number="3" location="packages/react-doctor/src/core/detection/discover-project.ts:236">
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>

<violation number="4" location="packages/react-doctor/src/core/detection/discover-project.ts:241">
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>

<violation number="5" location="packages/react-doctor/src/core/detection/discover-project.ts:452">
Severity: Warning

.map().filter() 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/core/config/is-ignored-file.ts">

<violation number="1" location="packages/react-doctor/src/core/config/is-ignored-file.ts:8">
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/cli/wrap-indented-text.ts">

<violation number="1" location="packages/react-doctor/src/cli/wrap-indented-text.ts:32">
Severity: Warning

.flatMap().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/cli/prompts.ts">

<violation number="1" location="packages/react-doctor/src/cli/prompts.ts:24">
Severity: Warning

Dynamic require() path is not statically analyzable — use a string literal so the bundler can trace this dependency

Use a string-literal path: `import('./feature/heavy.js')` so the bundler can split this chunk

Rule: `no-dynamic-import-path`
</violation>

<violation number="2" location="packages/react-doctor/src/cli/prompts.ts:50">
Severity: Warning

Dynamic require() path is not statically analyzable — use a string literal so the bundler can trace this dependency

Use a string-literal path: `import('./feature/heavy.js')` so the bundler can split this chunk

Rule: `no-dynamic-import-path`
</violation>

</file>

Showing 15 of 21 issues.

^{Reviewed by react-review for commit 861947c. Configure here.}

vercel · 2026-05-13T17:12:50Z

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 5:35pm

* refactor: move install-skill, scan, oxlint-config out of src/ root into their tiers Top-level src/ was still holding three orchestrator-grade files that logically belong inside the existing tier directories. Move them so the src/ root only contains public-API entry points and cross-cutting types. Moves (via git mv, history preserved): src/install-skill.ts -> src/cli/install-skill.ts CLI subcommand (already imported 6 things from cli/) src/scan.ts -> src/core/scan.ts Orchestrator (lives with the logic it calls) src/oxlint-config.ts -> src/core/runners/oxlint-config.ts Sibling of run-oxlint.ts (config + runner) After: top-level src/ contains only the entry points and shared types: src/ ├── cli/ presentation ├── core/ logic ├── plugin/ rules ├── constants.ts ├── errors.ts ├── eslint-plugin.ts public-API entry ├── index.ts public-API entry ├── knip.d.ts type declaration └── types.ts Imports rewritten via a small codemod (11 files): - 3 moved files' internal imports recomputed for new depth - 4 src/ consumers of the moved files updated - 4 test files updated Verification: - 11 files changed, +39/-39 (all import path edits) - typecheck/lint/format clean - 734/734 tests pass - build produces identical dist/* output - run-oxlint.ts's relative path to dist/react-doctor-plugin.js (../../../) is unchanged -- run-oxlint.ts itself didn't move Stacks on top of #224 (utils->core reorg). Once #224 merges, this PR's base auto-rebases to main. * refactor: rename scan -> inspect (function, file, types, test) "scan" was a misnomer -- the function does much more than scan files: it runs lint via oxlint, runs dead-code via knip, calculates a score, merges/filters diagnostics, and renders CLI output. "inspect" describes the role accurately and matches v2's chosen name. Renames: src/core/scan.ts -> src/core/inspect.ts (git mv) tests/scan.test.ts -> tests/inspect.test.ts (git mv) scan() function -> inspect() function runScan() -> runInspect() mergeScanOptions() -> mergeInspectOptions() ResolvedScanOptions -> ResolvedInspectOptions ScanResult -> InspectResult (src/types.ts) ScanOptions -> InspectOptions (src/types.ts) describe("scan", ...) -> describe("inspect", ...) (test) Importers updated: src/cli/index.ts 4 sites src/core/build-json-report.ts 3 sites tests/inspect.test.ts 5 sites tests/regressions/cli-and-output.test.ts 4 sites tests/build-json-report.test.ts 2 sites Kept as English prose (not identifiers): - "full scan", "scan output", "scan only files", "scan banner" in comments, CLI option descriptions, and prompt text -- these describe the action of scanning the codebase, not references to the function. - constants.ts JSX_OPENER_SCAN_MAX_LINES (about lexical JSX scanning, unrelated to inspect()). Verification: - 7 files changed, +54/-54 (all renames) - typecheck/lint/format clean - 734/734 tests pass - No public API change (scan/ScanResult/ScanOptions weren't exported from src/index.ts -- the public API still calls the underlying function diagnose() which is unchanged) Stacks on #225 (which moved scan.ts to src/core/). Once #225 merges, this PR's base auto-rebases to main.

The utils->core import-path codemod's regex matched `from '...'` substrings inside string literals -- specifically the EXAMPLE code shown to users in oxlint diagnostic help text. Three messages in HELP_TEXT_MAP had their example paths mangled into the codemod's target form (`../../utils/...`) even though they were supposed to illustrate paths in the USER'S code, not paths internal to this package. Restored to the original example paths: no-barrel-import: `import { Button } from '../../utils/components/Button.js'` -> `import { Button } from './components/Button'` no-dynamic-import-path: `import('../../utils/feature/heavy.js')` -> `import('./feature/heavy.js')` nextjs-no-css-link: `import styles from '../../utils/Button.module.css.js'` -> `import styles from './Button.module.css'` Verified no other string literals were corrupted (grepped for `["'`]../../(utils|core|cli)/` across src/ -- all remaining hits are legitimate plugin/utils imports from the per-rule split in #218, which is its own unrelated `utils/` directory). Closes the Bugbot finding on PR #224.

cursor

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

There are 2 total unresolved issues (including 1 from previous review).

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

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

…x layering) Addresses Bugbot's "Core modules depend backwards on CLI layer" finding on PR #224. Several core/ files were importing from cli/, undermining the layered structure the refactor was introducing: core/build-json-report-error.ts -> cli/format-error-chain core/runners/extract-failed-plugin-name -> cli/format-error-chain core/config/load-config -> cli/logger core/config/read-ignore-file -> cli/logger core/config/resolve-config-root-dir -> cli/logger The 3 utilities in question are all pure abstractions (no CLI-specific behavior beyond using console.* for output), so they belong in core/ where both core AND cli consumers can import them without inversion. Moves (git mv, history preserved): cli/format-error-chain.ts -> core/format-error-chain.ts (Error.cause walker) cli/logger.ts -> core/logger.ts (silent-mode logger) cli/highlighter.ts -> core/highlighter.ts (picocolors wrapper) 22 files changed, +29/-29 -- all relative-import path rewrites driven by a small codemod with a strict `^import ... from "..."` regex (line-anchored to avoid the help-text-literal corruption bug from the previous codemod, which triggered the bigger Bugbot follow-up). After this: - core/ no longer imports from cli/ for utilities -- only core/inspect.ts still does (legitimately: it's the CLI orchestrator that calls render-*.ts + resolve-oxlint-node prompt + spinner) - cli/ files import the moved utilities via `../core/<name>.js` Verification: - typecheck/lint/format clean - 734/734 tests pass - `rg "from .+cli/" src/core` shows only inspect.ts's legitimate imports of render-*, spinner, resolve-oxlint-node (all of which are CLI presentation/interaction, not utilities)

…s refactor (#224) Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

Rebased PR #164 onto main after a chain of refactors (#218, #220, #221, #223, #224, #226, #227) split the monolithic src/utils + oxlint-config.ts into per-feature modules. Re-applied the HIR additions to the new locations: - packages/react-doctor/src/plugin/hir/{types,lower,infer-types, runner,validators,index}.ts — unchanged from prior revision - Rule registration moved from src/oxlint-config.ts to src/core/runners/oxlint/rule-maps.ts (GLOBAL_REACT_DOCTOR_RULES) - Help / category metadata moved to src/core/runners/run-oxlint.ts - Plugin index import + rules map updated for the new export paths - Tests now import from src/core/runners/run-oxlint.js All 744 tests pass; lint, typecheck, format clean. Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

vercel Bot deployed to Preview May 13, 2026 17:12 View deployment

cursor Bot reviewed May 13, 2026

View reviewed changes

Comment thread packages/react-doctor/src/core/runners/run-oxlint.ts Outdated

aidenybai mentioned this pull request May 13, 2026

refactor: move orchestrators into tiers + rename scan -> inspect #225

Merged

3 tasks

vercel Bot deployed to Preview May 13, 2026 17:25 View deployment

vercel Bot deployed to Preview May 13, 2026 17:28 View deployment

cursor Bot reviewed May 13, 2026

View reviewed changes

Comment thread packages/react-doctor/src/core/build-json-report-error.ts Outdated

vercel Bot deployed to Preview May 13, 2026 17:35 View deployment

aidenybai merged commit 8bb54c9 into main May 13, 2026
6 checks passed

cursor Bot pushed a commit that referenced this pull request May 13, 2026

test(hir-port): update import path after src/utils -> src/core/runner…

be5aabb

…s refactor (#224) Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: split src/utils/ into src/core/{config,detection,diagnostics,scoring,runners}/ + src/cli/#224

refactor: split src/utils/ into src/core/{config,detection,diagnostics,scoring,runners}/ + src/cli/#224
aidenybai merged 4 commits into
mainfrom
refactor/utils-to-core-reorg

aidenybai commented May 13, 2026 •

edited by cursor Bot

Loading

Uh oh!

reactreview Bot commented May 13, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

aidenybai commented May 13, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New layout

How it was done

Manual fixes after the mechanical move

Verification

What's NOT in this PR

Test plan

Uh oh!

reactreview Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

aidenybai commented May 13, 2026 •

edited by cursor Bot

Loading

reactreview Bot commented May 13, 2026 •

edited

Loading

vercel Bot commented May 13, 2026 •

edited

Loading