feat(react-doctor): adopt user lint config, ship as ESLint plugin, remove browser surface

[aidenybai]

Closes #143 from both sides.

Issue #143 asked for react-doctor to integrate with existing ESLint setups so diagnostics flow through "classic hooks / analysis." This PR addresses that two ways:

1. Fold the user's config INTO a react-doctor scan — adoptExistingLintConfig (default-on). When a project has a JSON-format oxlint or eslint config (.oxlintrc.json or .eslintrc.json) at the scanned directory or any ancestor up to the nearest project boundary, react-doctor merges it into the same scan via oxlint's extends field. Diagnostics from those rules count toward the 0–100 score.
2. Fold react-doctor's rules INTO the user's eslint run — new react-doctor/eslint-plugin export. Drop into a flat config, get the same curated rule set with recommended / next / react-native / tanstack-start / tanstack-query / all presets, and diagnostics surface inline through whichever ESLint integration the user already runs.

Behavior change on upgrade

Projects with an existing .oxlintrc.json / .eslintrc.json will see new diagnostics flow into the score on first run; the score may drop. Set "adoptExistingLintConfig": false to preserve the previous behavior. customRulesOnly: true also implies opt-out.

The PR also broadens the diagnostic file-extension filter from .tsx/.jsx to the full source-file pattern so adopted rules and react-doctor's own JS-performance rules now report on plain .ts/.js files.

Resilience

If oxlint can't load the user's config (broken JSON, missing plugin, unknown rule name), react-doctor logs the reason on stderr ([react-doctor] could not adopt existing lint config (...); retrying without extends. Set "adoptExistingLintConfig": false to silence.) and retries the scan once without extends so a real score is still produced off the curated rule set.

Limitations (documented)

• Only JSON configs are picked up. oxlint's extends cannot evaluate JS or TS, so flat configs (eslint.config.js), .eslintrc.{js,cjs}, and oxlint.config.ts are silently skipped.
• Rule-level severities ("rules": {...}) flow through. Category-level enables ("categories": {...}) do not — react-doctor's local categories block always wins.
• Plugins from the user's config are unioned in (verified empirically against oxlint 1.63), so "plugins": ["unicorn"] + "rules": { "unicorn/no-array-for-each": "error" } works.
• Detection walks up only to a project boundary (.git directory or monorepo root), never to the user's home directory.

Implementation highlights

Adopt-existing-lint-config

• New detect-user-lint-config.ts that walks up to a project boundary and returns the first matching config (.oxlintrc.json preferred over .eslintrc.json). Filename list lives in constants.ts (ADOPTABLE_LINT_CONFIG_FILENAMES) next to KNIP_CONFIG_LOCATIONS.
• createOxlintConfig accepts extendsPaths; emits extends only when non-empty.
• runOxlint writes the config via a small writeOxlintConfig helper (allows in-place rewrite for retry), runs the spawn loop through spawnLintBatches. On failure with non-empty extends, we rewrite without extends, log to stderr, and retry once.
• New adoptExistingLintConfig?: boolean field on ReactDoctorConfig (default true), wired through validate-config-types.ts, scan.ts, and index.ts.
• PLUGIN_CATEGORY_MAP gains category defaults for eslint, oxc, typescript, unicorn, import, promise, n, node, vitest, jest, nextjs so adopted-rule diagnostics group meaningfully.
• Diagnostic file filter JSX_FILE_PATTERN → SOURCE_FILE_PATTERN so .ts/.js files aren't dropped post-parse.

ESLint plugin

• New src/eslint-plugin.ts reuses every rule from the existing oxlint plugin (each rule's create(context) => visitors signature is already ESLint-compatible), wraps each in the ESLint v9-required { meta, create } shape, and ships flat configs reusing the exact severity maps the CLI emits to oxlint so the engines stay in lock-step.
• RuleSeverity, NEXTJS_RULES, REACT_NATIVE_RULES, TANSTACK_START_RULES, TANSTACK_QUERY_RULES, and GLOBAL_REACT_DOCTOR_RULES are now exported from oxlint-config.ts so the eslint-plugin module can read the canonical rule sets without re-declaring them.
• New ./eslint-plugin entry in package.json exports + a matching vite.config.ts build entry; dist/eslint-plugin.{js,d.ts} ships alongside react-doctor-plugin.{js,d.ts}.

Commits

• 87e5cc6 — adopt-existing-lint-config (core feature, retry-on-failure, detection walk-up, fixtures, tests)
• 605cc5e — chore: export rule severity / category constants from oxlint-config
• ea988a3 — chore: bump oxlint to ^1.63.0 and pin oxlint-tsgolint via override
• 2b59680 — eslint-plugin source
• 6acdddc — build: wire react-doctor/eslint-plugin entry + README docs
• 8eed892 — eslint-plugin changeset

Test plan

• pnpm typecheck clean
• pnpm lint 0 errors (333 pre-existing warnings unchanged)
• pnpm test — 461 tests pass (was 456); new tests cover:
  • detect-user-lint-config.test.ts — empty dir, single oxlint/eslint config, first-match priority, dotless / JS variants ignored, walk-up to root, project-boundary stop.
  • run-oxlint.test.ts — adoptExistingLintConfig: default-on merges user rules, .ts files reported (not just .tsx), opt-out skips, customRulesOnly skips, broken-config fallback emits stderr warning and still resolves.
  • validate-config-types.test.ts — passthrough + stringy coercion for the new boolean.
• pnpm --filter react-doctor build produces dist/eslint-plugin.{js,d.ts} (~257 kB / ~55 kB gzipped).
• End-to-end CLI verification:
  • react-doctor packages/react-doctor/tests/fixtures/user-oxlint-config reports (2) debugger violations across app.tsx + util.ts (was (1), .tsx only) and folds them into the score (97/100, vs 99/100 with adoptExistingLintConfig: false).
  • react-doctor packages/react-doctor/tests/fixtures/user-oxlint-config-broken (intentionally references unknown plugin) emits the retry warning on stderr and produces a real score (100/100 on the clean fixture) instead of failing the lint pass.

---

Note

Medium Risk
Medium risk because it changes how lint diagnostics are sourced and scored (now optionally extends user configs and includes .ts/.js), and it removes previously published browser-related entrypoints/packages which may break downstream consumers.

Overview
React Doctor now (by default) adopts an existing JSON .oxlintrc.json / .eslintrc.json found at or above the scan root (up to a project boundary) by wiring it into oxlint via extends, so user rules run alongside the curated rule set and count toward the health score; failures to load the adopted config are handled by logging and retrying once without extends.

It also adds a first-class ESLint v9 flat-config plugin export at react-doctor/eslint-plugin, exposing recommended/framework presets and all configs that mirror the CLI’s severity maps.

Separately, the PR drops the browser surface area (the react-doctor-browser/headless-browser workspace package and related CLI/exports) and adds a pnpm override for oxlint-tsgolint.

^{Reviewed by Cursor Bugbot for commit 51e8448. Bugbot is set up for automated code reviews on this repo. 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 7, 2026 5:39am

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

[vercel]

Additional Suggestion:

In diff mode and with file ignores, .ts/.js files are filtered out by computeJsxIncludePaths and resolveLintIncludePaths, contradicting the PR's stated goal of broadening coverage to include those files.