refactor: move orchestrators into tiers + rename scan -> inspect by aidenybai · Pull Request #225 · millionco/react-doctor

aidenybai · 2026-05-13T17:17:07Z

Stacked on #224 \u2014 base is `refactor/utils-to-core-reorg`. Once #224 merges, this PR's base will rebase to main.

Two commits, both pure refactors:

Commit 1: 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.

From	To	Why
`src/install-skill.ts`	`src/cli/install-skill.ts`	CLI subcommand (`react-doctor install`), already imported 6 things from `./cli/`
`src/scan.ts`	`src/core/scan.ts`	The orchestrator belongs with the logic it calls
`src/oxlint-config.ts`	`src/core/runners/oxlint-config.ts`	The oxlint config builder belongs next to `run-oxlint.ts`

All three done via `git mv` so blame / `git log --follow` history is preserved.

Commit 2: Rename `scan` \u2192 `inspect` (function, file, types, test)

"scan" was a misnomer \u2014 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 (`inspectReactProject`).

Before	After
`src/core/scan.ts`	`src/core/inspect.ts`
`tests/scan.test.ts`	`tests/inspect.test.ts`
`scan()`	`inspect()`
`runScan()`	`runInspect()`
`mergeScanOptions()`	`mergeInspectOptions()`
`ResolvedScanOptions`	`ResolvedInspectOptions`
`ScanResult` (in `src/types.ts`)	`InspectResult`
`ScanOptions` (in `src/types.ts`)	`InspectOptions`
`describe("scan", ...)` (test)	`describe("inspect", ...)`

Kept as English prose (not identifiers):

"full scan", "scan output", "scan only files", "scan banner" in CLI option help text, prompts, and comments \u2014 these describe the action of scanning the codebase, not references to the function.
`JSX_OPENER_SCAN_MAX_LINES` in `constants.ts` (about lexical JSX scanning, unrelated).

After both commits, top-level `src/`

```
src/
\u251c\u2500\u2500 cli/ presentation
\u251c\u2500\u2500 core/ logic
\u2502 \u251c\u2500\u2500 config/
\u2502 \u251c\u2500\u2500 detection/
\u2502 \u251c\u2500\u2500 diagnostics/
\u2502 \u251c\u2500\u2500 runners/ (now hosts oxlint-config.ts alongside run-oxlint.ts)
\u2502 \u251c\u2500\u2500 scoring/
\u2502 \u2514\u2500\u2500 inspect.ts (orchestrator, renamed from scan.ts)
\u251c\u2500\u2500 plugin/ rules
\u251c\u2500\u2500 constants.ts
\u251c\u2500\u2500 errors.ts
\u251c\u2500\u2500 eslint-plugin.ts public-API entry
\u251c\u2500\u2500 index.ts public-API entry
\u251c\u2500\u2500 knip.d.ts
\u2514\u2500\u2500 types.ts
```

Top-level `src/` is now ONLY: 3 tier dirs + 2 public-API entry points + 3 cross-cutting types + 1 type declaration.

No public API change

`scan` / `ScanResult` / `ScanOptions` were not exported from `src/index.ts`. The public programmatic API is still `diagnose()` (unchanged).

Verification

18 files changed, +93 / -93 (all renames / import-path edits)
`pnpm typecheck` clean
`pnpm test` \u2014 734/734 pass
`pnpm lint` \u2014 0 warnings, 0 errors
`pnpm format:check` clean
`pnpm build` \u2014 dist outputs unchanged
git `mv` preserves blame / `git log --follow` for all 5 moved files

Test plan

typecheck / test / lint / format / build all clean
All `scan`/`Scan` identifiers renamed in source + tests; only English-prose mentions in comments / help text remain
No public API surface change

Note

Low Risk
Low risk refactor focused on file moves and type/function renames; main risk is missed import-path updates that could break CLI/test wiring.

Overview
Moves the install subcommand implementation into src/cli/install-skill.ts, and relocates the scan orchestrator into src/core/inspect.ts while renaming scan/ScanOptions/ScanResult to inspect/InspectOptions/InspectResult across the CLI, JSON report builder, and tests.

Relocates the oxlint config builder to src/core/runners/oxlint-config.ts and updates downstream imports (run-oxlint, diagnostic filtering, and eslint-plugin adapter) to reference the new location.

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

…to 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.

reactreview · 2026-05-13T17:17:10Z

🔴 React Review — 0/100 (unchanged) · No new issues

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

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

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:22pm

"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.

…s,scoring,runners}/ + src/cli/ (#224) * refactor: split src/utils/ (68 flat files) into src/core/{config,detection,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 * refactor: move orchestrators into tiers + rename scan -> inspect (#225) * 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. * fix: restore help-text example paths corrupted by the import codemod 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. * refactor: move format-error-chain / logger / highlighter to core/ (fix 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)

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

aidenybai changed the title ~~refactor: move install-skill / scan / oxlint-config out of src/ root into their tiers~~ refactor: move orchestrators into tiers + rename scan -> inspect May 13, 2026

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

aidenybai merged commit 98172d8 into refactor/utils-to-core-reorg May 13, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

refactor: move orchestrators into tiers + rename scan -> inspect#225
aidenybai merged 2 commits into
refactor/utils-to-core-reorgfrom
refactor/move-orchestrators-into-tiers

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!

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!

Commit 1: Move install-skill / scan / oxlint-config out of `src/` root into their tiers

Commit 2: Rename `scan` \u2192 `inspect` (function, file, types, test)

After both commits, top-level `src/`

No public API change

Verification

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!

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