feat: add dead-code analysis via deslop-js

[aidenybai]

Summary

Re-adds dead-code detection to react-doctor, this time powered by deslop-js (oxc-based, fast) instead of the previously-removed knip integration.

Unused files, unused exports, unused dependencies, and circular import cycles surface alongside lint findings under a new Dead Code category and flow through the same suppression / severity / surface pipeline as every other rule.

New rule ids

• deslop/unused-file — a source file not reachable from any detected entry point.
• deslop/unused-export / deslop/unused-type — exported symbol (or type-only symbol) that no other module imports.
• deslop/unused-dependency / deslop/unused-dev-dependency — a package.json dep that is never imported.
• deslop/circular-dependency — an import cycle between two or more files.

Controls

• CLI: --no-dead-code skips the pass entirely; --dead-code re-enables it.
• Config: "deadCode": false mirrors --no-dead-code.
• Severity: "rules": { "deslop/unused-export": "off" } or "categories": { "Dead Code": "off" } works out of the box.
• Surfaces, ignore.files, ignore.overrides all apply just like any other diagnostic.

Dead-code reachability is a whole-project property, so the pass is automatically skipped in --diff / --staged modes — a diff scan can't tell whether a deleted importer just stopped using a file or whether the file became unreachable. This matches how checkReducedMotion is gated in combineDiagnostics.

Changes by package

• @react-doctor/core
  • New checkDeadCode() (packages/core/src/check-dead-code.ts) wraps deslop's analyze() and maps each ScanResult entry to a Diagnostic (plugin "deslop", category "Dead Code", severity "warning").
  • combineDiagnostics gained an extraDiagnostics channel so the async pass feeds the same suppression / severity pipeline as lint.
  • validateConfigTypes knows about the new boolean deadCode field.
  • PLUGIN_CATEGORY_MAP maps deslop → "Dead Code" for the rare case an external tool emits a raw deslop/* diagnostic without a category.
  • Added deslop-js@^0.0.2 as a dependency.
• @react-doctor/types
  • New deadCode?: boolean on ReactDoctorConfig, InspectOptions, and DiagnoseOptions.
• react-doctor
  • inspect() and diagnose() run the dead-code pass in parallel with runOxlint; failures degrade gracefully and add a "dead-code" entry to skippedChecks / skippedCheckReasons instead of failing the whole scan.
  • CLI exposes --dead-code / --no-dead-code.
  • README updated with a dedicated dead-code section, the new CLI flag, and the new config key.

Tests

• New packages/react-doctor/tests/check-dead-code.test.ts regression suite covering empty projects, unused files, unused exports, and unused dependencies.
• Added an extraDiagnostics case to combine-diagnostics.test.ts.
• All 1175 existing tests still pass; pnpm lint and pnpm typecheck both clean.

Smoke test

Running react-doctor against the basic-react fixture now shows entries like:

deslop/unused-file        ×22  Unused file — not reachable from any entry point
deslop/unused-dependency       Unused dependency: `@tanstack/react-query`

and --no-dead-code zeroes them out.

  

[reactreview]

Copy as prompt

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 1 warning. This PR leaves the React health score unchanged.

<file name="packages/react-doctor/tests/check-dead-code.test.ts">

<violation number="1" location="packages/react-doctor/tests/check-dead-code.test.ts:70">
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>

^{Reviewed by reactreview for commit b382d61. 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 20, 2026 9:21pm

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