feat(react-doctor): typed errors + config rootDir for diagnose() targeting

[aidenybai]

Summary

Three related changes to how react-doctor resolves which project to scan, plus the typed error vocabulary that goes with them. Each commit on the branch is independently shippable.

1. Typed error classes for the node API

react-doctor/api now exports named subclasses of ReactDoctorError instead of plain Error:

• ReactDoctorError — base class
• ProjectNotFoundError — no React project (root or nested) under the requested directory
• NoReactDependencyError — package found but no react dep
• PackageJsonNotFoundError — discoverProject() got a directory with no package.json
• AmbiguousProjectError — multiple nested React subprojects under a directory with no root package.json; carries candidates: readonly string[]
• isReactDoctorError(value) — value is ReactDoctorError type guard

Each error preserves its message text (existing message-substring tests still pass) and sets name to the class name so it round-trips through JSON.stringify and error.name checks.

2. Refuse ambiguous diagnose() targets

The fallback added in #193 silently picked reactSubprojects[0] when the requested directory had no root package.json. That works for single-subproject roots (the Vercel AI Code Review use case) but in true monorepo trees it just guesses — non-deterministic across filesystems.

New behavior:

• 0 nested candidates → ProjectNotFoundError (unchanged)
• 1 nested candidate → auto-resolve (preserves the fix(react-doctor): fall back to nested React subproject in diagnose() #193 fix)
• ≥2 nested candidates → AmbiguousProjectError with candidates[] so the caller iterates or disambiguates explicitly

The CLI is unaffected — it continues to use selectProjects for prompt-or-scan-all.

3. rootDir in react-doctor.config.json

The declarative answer to "I have a monorepo with apps/web and want a single root-level config to route every invocation there." Setting "rootDir": "apps/web" in react-doctor.config.json (or the reactDoctor key in package.json) redirects the CLI / scan() / diagnose() to that subdirectory.

Resolution rules:

• Resolved relative to the config file's directory, not the CWD — stable regardless of where the user invokes from.
• Absolute paths used verbatim.
• Missing / non-directory paths fall back to the requested directory with a logger.warn.
• Non-string values are stripped by validateConfigTypes with the same stderr warning shape used for the boolean fields.
• CLI prints a one-line dimmed Redirected to <relative> via react-doctor config "rootDir" notice (suppressed under --json / --score).

This is also the proper escape hatch for the ambiguous-wrapper case from change #2: a repo with no root package.json and apps/web + apps/admin can declare its intent with rootDir: "apps/web" instead of relying on a CLI argument every time.

Mechanically: refactored load-config to add loadConfigWithSource() (config + the directory it loaded from), kept loadConfig as a thin wrapper for backward compatibility, added utils/resolve-config-root-dir.ts for the resolution + sanity checks, and wired the redirect into all three entry points. When the CLI passes configOverride into scan(), scan() trusts that the caller already applied the redirect to avoid double-redirecting.

Verification

• pnpm typecheck — pass
• pnpm lint — pass (0 warnings, 0 errors on 178 files)
• pnpm format — clean
• pnpm test (in packages/react-doctor) — 695/695 pass
  • Pre-existing: 685
  • +1 ambiguous-project regression
  • +9 covering rootDir resolution (relative, absolute, ancestor config location, non-existent fallback, non-string validation, source-directory exposure)

Example: end-to-end

// repo-root/react-doctor.config.json
{
  "rootDir": "apps/web",
  "ignore": { "rules": ["jsx-a11y/no-autofocus"] }
}

import {
  diagnose,
  AmbiguousProjectError,
  NoReactDependencyError,
  isReactDoctorError,
} from "react-doctor/api";

try {
  // Resolves the rootDir redirect: scans repo-root/apps/web
  await diagnose(repoRoot);
} catch (error) {
  if (error instanceof AmbiguousProjectError) {
    for (const candidate of error.candidates) {
      await diagnose(path.join(error.directory, candidate));
    }
  } else if (error instanceof NoReactDependencyError) {
    // error.directory is typed as string
  } else if (isReactDoctorError(error)) {
    // any other known react-doctor failure
  } else {
    throw error;
  }
}

  

[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 10, 2026 4:35am

[reactreview]

React Review found 0 ❌ errors and 0 ⚠️ warnings. This PR leaves the React health score unchanged.

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

No net-new issues were introduced.

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

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