react-doctor 0.1.6 → 0.2.0-beta.0

package/README.md

@@ -9,13 +9,13 @@
 
 Your agent writes bad React, this catches it.
 
-One command scans your codebase and outputs a **0 to 100 health score** with actionable diagnostics.
+React Doctor scans React projects with native codebase analysis, a curated oxlint rule set, and actionable diagnostics.
 
-Works with Next.js, Vite, and React Native.
+Works with React, Next.js, React Native, Expo, TanStack Start, and common React ecosystem libraries.
 
-### [See it in action →](https://react.doctor)
+### [See it in action](https://react.doctor)
 
-## Install
+## Run
 
 Run this at your project root:
 
@@ -23,104 +23,119 @@ Run this at your project root:
 npx -y react-doctor@latest .
 ```
 
-You'll get a score (75+ Great, 50 to 74 Needs work, under 50 Critical) and a list of issues across state & effects, performance, architecture, security, accessibility, and dead code. Rules toggle automatically based on your framework and React version.
+By default React Doctor runs:
+
+- native project structure and codebase graph checks
+- oxlint with the React Doctor custom plugin
+- scoring and grouped human output
+
+You get a 0 to 100 score and a list of issues across state and effects, performance, architecture, security, accessibility, framework usage, dependencies, and dead code. Rules toggle automatically based on your framework, React version, and detected libraries.
 
 https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570
 
-## Install for your coding agent
+## React Doctor Skill
 
-Teach your coding agent React best practices so it stops writing the bad code in the first place.
+React Doctor also ships as an agent Skill. The CLI catches problems after code is written; the Skill teaches your coding agent the same React, framework, and performance guidance before it writes the next patch.
 
 ```bash
 npx -y react-doctor@latest install
 ```
 
-You'll be prompted to pick which detected agents to install for. Pass `--yes` to skip prompts.
-
-Works with Claude Code, Cursor, Codex, OpenCode, and 50+ other agents.
+Use the Skill when you want agents to:
 
-## GitHub Actions
+- avoid common state and effect mistakes
+- choose framework-native APIs for Next.js, React Native, Expo, and TanStack Start
+- keep rendering, animation, data fetching, and accessibility choices high-signal
+- understand React Doctor diagnostics and fix the underlying issue instead of hiding it
 
-A composite action ships with this repository. Drop it into `.github/workflows/react-doctor.yml`:
+The installer detects supported coding agents and prompts you to choose where to install the Skill. Pass `--yes` to accept the default detected targets.
 
-```yaml
-name: React Doctor
+## CLI
 
-on:
-  pull_request:
-  push:
-    branches: [main]
+```bash
+react-doctor [directory]
+```
 
-permissions:
-  contents: read
-  pull-requests: write # required to post PR comments
+Useful flags:
 
-jobs:
-  react-doctor:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0 # required for `diff`
-      - uses: millionco/react-doctor@main
-        with:
-          diff: main
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+```bash
+react-doctor apps/web --json
+react-doctor apps/web --json --json-compact
+react-doctor apps/web --no-lint
+react-doctor apps/web --no-dead-code
+react-doctor apps/web --custom-rules-only
+react-doctor apps/web --staged
+react-doctor apps/web --unstaged
+react-doctor apps/web --changed
+react-doctor apps/web --diff main
+react-doctor apps/web --offline
+react-doctor apps/web --fail-on error
 ```
 
-When `github-token` is set on `pull_request` events, findings are posted (and updated) as a PR comment. The action also exposes a `score` output (0–100) you can use in subsequent steps.
+Changed-file modes only inspect matching source files:
 
-**Inputs:** `directory`, `verbose`, `project`, `diff`, `github-token`, `fail-on` (`error` / `warning` / `none`), `offline`, `node-version`. See [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml) for full descriptions.
+- `--staged` scans the git index for pre-commit flows.
+- `--unstaged` scans unstaged and untracked source files.
+- `--changed` scans staged, unstaged, and untracked source files since `HEAD`.
+- `--diff [base]` scans files changed against a base branch, defaulting to `main`.
 
-Prefer not to add a marketplace action? The bare `npx` form works too:
+If no changed source files are found, source checks are skipped instead of falling back to a full scan.
 
-```yaml
-- run: npx -y react-doctor@latest --fail-on warning
-```
+`--fail-on` accepts `error`, `warning`, or `none`.
 
 ## Configuration
 
-Create a `react-doctor.config.json` in your project root:
+React Doctor looks for configuration in:
+
+- `react-doctor.config.json`
+- `package.json#reactDoctor`
+
+Config lookup starts at the requested directory and walks ancestors until a project boundary. `rootDir` is resolved relative to the config source, not the current working directory.
 
 ```json
 {
+  "rootDir": "apps/web",
+  "lint": true,
+  "deadCode": true,
+  "customRulesOnly": false,
+  "offline": true,
+  "failOn": "error",
+  "respectInlineDisables": true,
+  "adoptExistingLintConfig": false,
+  "includeEcosystemRules": true,
+  "ignoredTags": ["design"],
+  "textComponents": ["Trans"],
+  "rawTextWrapperComponents": ["Button"],
   "ignore": {
-    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
+    "rules": ["react-doctor/no-gradient-text"],
     "files": ["src/generated/**"],
     "overrides": [
       {
-        "files": ["components/modules/diff/**"],
-        "rules": ["react-doctor/no-array-index-as-key", "react-doctor/no-render-in-render"]
-      },
-      {
-        "files": ["components/search/HighlightedSnippet.tsx"],
-        "rules": ["react/no-danger"]
+        "files": ["src/legacy/**"],
+        "rules": ["react-doctor/no-default-props"]
       }
     ]
   }
 }
 ```
 
-Three nested keys, three layers of granularity — pick the narrowest one that fits:
+Pick the narrowest ignore that fits:
 
-- **`ignore.rules`** silences a rule across the whole codebase.
-- **`ignore.files`** silences **every** rule on the matched files (use sparingly — it loses coverage for unrelated rules).
+- **`ignore.rules`** silences a rule across the codebase.
+- **`ignore.files`** silences every rule on matched files.
 - **`ignore.overrides`** silences only the listed rules on the matched files, leaving every other rule active. This is what you want when a single file (or glob) legitimately needs an exemption from one or two rules but should still be scanned for everything else.
 
-You can also use the `"reactDoctor"` key in `package.json`. CLI flags always override config values.
+React Doctor scans only its curated rule set by default. Set `adoptExistingLintConfig` to `true` to adopt the first JSON `.oxlintrc.json` or `.eslintrc.json` found while walking ancestors.
 
-React Doctor respects `.gitignore`, `.eslintignore`, `.oxlintignore`, `.prettierignore`, and `linguist-vendored` / `linguist-generated` annotations in `.gitattributes`. Inline `// eslint-disable*` and `// oxlint-disable*` comments are honored too.
+`ignoredTags` lets you trim noisy categories without turning the whole scanner off. For example, `["design"]` keeps structural React checks while skipping subjective visual style suggestions.
 
-If you have a JSON oxlint or eslint config (`.oxlintrc.json` or `.eslintrc.json`), its rules get merged into the scan automatically and count toward the score. Set `adoptExistingLintConfig: false` to opt out.
+For React Native, `textComponents` marks custom components that behave like `<Text>`, while `rawTextWrapperComponents` marks components that safely wrap string-only children in text internally.
 
-#### Optional companion plugins
+## Scoring
 
-When the following ESLint plugins are installed in the scanned project (or hoisted in your monorepo), React Doctor folds their rules into the same scan. Both are listed as **optional peer dependencies** — install only what you want.
+Scores are a simple health signal, not a moral judgment. React Doctor starts at 100, subtracts more for error-level rule families than warning-level families, and counts a repeated rule once so one noisy pattern does not dominate the whole project.
 
-| Plugin                                                                                                                                          | Adds                                                                                                                                                                                                        | Namespace          |
-| ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
-| [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) (v6 or v7)                                               | The React Compiler frontend's correctness rules — fired when a React Compiler is detected in the project.                                                                                                   | `react-hooks-js/*` |
-| [`eslint-plugin-react-you-might-not-need-an-effect`](https://github.com/nickjvandyke/eslint-plugin-react-you-might-not-need-an-effect) (v0.10+) | Complementary effects-as-anti-pattern rules (`no-derived-state`, `no-chain-state-updates`, `no-event-handler`, `no-pass-data-to-parent`, …) that run alongside React Doctor's native State & Effects rules. | `effect/*`         |
+The score can move between releases as rules become more precise, new framework rules are added, or noisy checks are demoted. Treat the detailed diagnostics as the source of truth and use the score for trend tracking across repeated runs.
 
 ### Inline suppressions
 
@@ -139,7 +154,7 @@ When two rules fire on the same line, you have two equivalent options. Comma-sep
 const [localSearch, setLocalSearch] = useState(searchQuery);
 ```
 
-Or stack one comment per rule directly above the diagnostic. Stacked comments are honored as long as nothing but other `react-doctor-disable-next-line` comments sits between them and the target line:
+Or stack one comment per rule directly above the diagnostic:
 
 ```tsx
 // react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers
@@ -147,122 +162,142 @@ Or stack one comment per rule directly above the diagnostic. Stacked comments ar
 const [localSearch, setLocalSearch] = useState(searchQuery);
 ```
 
-A code line between stacked comments breaks the chain: only the comment immediately above the diagnostic (and any contiguous `react-doctor-disable-next-line` comments stacked on top of it) is honored. If a comment looks adjacent but the rule still fires, run `react-doctor --explain <file:line>` — it reports whether a nearby suppression was found, what rules it covers, and why it didn't apply.
-
 Block comments work inside JSX:
 
 <!-- prettier-ignore -->
 ```tsx
-{/* react-doctor-disable-next-line react/no-danger */}
+{/* react-doctor-disable-next-line no-danger */}
 <div dangerouslySetInnerHTML={{ __html }} />
 ```
 
 For multi-line JSX, putting the comment immediately above the opening tag covers the entire attribute list (matching ESLint convention).
 
-## Lint plugin (standalone)
+## Lint Integrations
 
 The same rule set ships as both an oxlint plugin and an ESLint plugin, so you can wire it into whichever lint engine your project already runs.
 
-**oxlint** in `.oxlintrc.json`:
+Oxlint (`.oxlintrc.json`):
 
 ```jsonc
 {
   "jsPlugins": [{ "name": "react-doctor", "specifier": "react-doctor/oxlint-plugin" }],
   "rules": {
     "react-doctor/no-fetch-in-effect": "warn",
-    "react-doctor/no-derived-state-effect": "warn",
   },
 }
 ```
 
-**ESLint** flat config:
+ESLint:
 
 ```js
 import reactDoctor from "react-doctor/eslint-plugin";
 
 export default [
-  reactDoctor.configs.recommended,
-  reactDoctor.configs.next,
-  reactDoctor.configs["react-native"],
-  reactDoctor.configs["tanstack-start"],
-  reactDoctor.configs["tanstack-query"],
+  {
+    plugins: {
+      "react-doctor": reactDoctor,
+    },
+    rules: {
+      "react-doctor/no-fetch-in-effect": "warn",
+    },
+  },
 ];
 ```
 
-The full rule list lives in [`oxlint-config.ts`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/oxlint-config.ts).
+The ESLint wrapper reuses the same rule implementations and metadata as the oxlint plugin.
+
+## SDK
 
-## CLI reference
+```ts
+import { createReactDoctor, inspectReactProject } from "react-doctor";
 
+const result = await inspectReactProject({
+  rootDirectory: "apps/web",
+  lint: true,
+  deadCode: true,
+});
+
+const reactDoctor = createReactDoctor({ rootDirectory: "apps/web" });
+const nextResult = await reactDoctor.inspect();
 ```
-Usage: react-doctor [directory] [options]
-
-Options:
-  -v, --version           display the version number
-  --no-lint               skip linting
-  --no-dead-code          skip dead code detection
-  --verbose               show every rule and per-file details (default shows top 3 rules)
-  --score                 output only the score
-  --json                  output a single structured JSON report
-  -y, --yes               skip prompts, scan all workspace projects
-  --full                  skip prompts, always run a full scan
-  --project <name>        select workspace project (comma-separated for multiple)
-  --diff [base]           scan only files changed vs base branch
-  --staged                scan only staged files (for pre-commit hooks)
-  --offline               skip telemetry
-  --fail-on <level>       exit with error on diagnostics: error, warning, none
-  --annotations           output diagnostics as GitHub Actions annotations
-  --explain <file:line>   diagnose why a rule fired or why a suppression didn't apply
-  --why <file:line>       alias for --explain
-  -h, --help              display help
+
+The result includes project metadata, check results, normalized issues, score, and timing.
+
+```ts
+import { buildReactDoctorJsonReport } from "react-doctor";
+
+const report = buildReactDoctorJsonReport(result);
+```
+
+Typed runtime errors are exported from the main SDK:
+
+```ts
+import { ReactDoctorInvalidConfigError, isReactDoctorError } from "react-doctor";
 ```
 
-When a suppression isn't working, `--explain <file:line>` (or its alias `--why <file:line>`) reports what the scanner sees at that location, including why a nearby `react-doctor-disable-next-line` didn't apply. The diagnosis distinguishes the common failure modes — adjacent comment for a different rule (use the comma form), a code line between the comment and the diagnostic (the chain is broken), or no nearby suppression at all. The same hint surfaces inline with `--verbose` for every flagged site, and in `--json` output as `diagnostic.suppressionHint`, so a single scan doubles as a suppression audit without a separate flag.
+## Compatibility API
 
-`--json` produces a parsable object on stdout with all human-readable output suppressed. Errors still produce a JSON object with `ok: false`, so stdout is always a valid document.
+Deprecated compatibility APIs live under `react-doctor/api` and are intentionally isolated from the main runtime.
 
-### Config keys
+```ts
+import { diagnose, clearCaches } from "react-doctor/api";
 
-| Key                        | Type                             | Default  |
-| -------------------------- | -------------------------------- | -------- |
-| `ignore.rules`             | `string[]`                       | `[]`     |
-| `ignore.files`             | `string[]`                       | `[]`     |
-| `ignore.overrides`         | `{ files, rules? }[]`            | `[]`     |
-| `lint`                     | `boolean`                        | `true`   |
-| `deadCode`                 | `boolean`                        | `true`   |
-| `verbose`                  | `boolean`                        | `false`  |
-| `diff`                     | `boolean \| string`              |          |
-| `failOn`                   | `"error" \| "warning" \| "none"` | `"none"` |
-| `customRulesOnly`          | `boolean`                        | `false`  |
-| `share`                    | `boolean`                        | `true`   |
-| `textComponents`           | `string[]`                       | `[]`     |
-| `rawTextWrapperComponents` | `string[]`                       | `[]`     |
-| `respectInlineDisables`    | `boolean`                        | `true`   |
-| `adoptExistingLintConfig`  | `boolean`                        | `true`   |
+const result = await diagnose("apps/web", {
+  lint: true,
+  deadCode: true,
+});
 
-`textComponents` is the broad escape hatch for `rn-no-raw-text` — list components that themselves behave like React Native's `<Text>` (custom `Typography`, `NativeTabs.Trigger.Label`, etc.) and the rule will treat them as text containers regardless of what their children look like.
+clearCaches();
+```
 
-`rawTextWrapperComponents` is the narrower option for components that are not text elements but safely route string-only children through an internal `<Text>` (e.g. `heroui-native`'s `Button`, which stringifies its children and renders them through a `ButtonLabel`). Listed wrappers suppress `rn-no-raw-text` only when their children are entirely stringifiable. A wrapper with mixed children — e.g. `<Button>Save<Icon /></Button>` — still reports because the wrapper can't safely route raw text alongside a sibling JSX element.
+Prefer `createReactDoctor()` or `inspectReactProject()` for new integrations.
 
-## Node.js API
+## Development
 
-```js
-import { diagnose, toJsonReport, summarizeDiagnostics } from "react-doctor/api";
+Run package checks from the package directory:
+
+```bash
+nr typecheck
+nr test
+nr build
+```
 
-const result = await diagnose("./path/to/your/react-project");
+Run workspace formatting and linting from the repository root:
 
-console.log(result.score); // { score: 82, label: "Great" } or null
-console.log(result.diagnostics); // Diagnostic[]
-console.log(result.project); // detected framework, React version, etc.
+```bash
+nr format:check packages/react-doctor/src packages/react-doctor/tests
+nr lint packages/react-doctor/src packages/react-doctor/tests
 ```
 
-`diagnose` accepts a second argument: `{ lint?: boolean, deadCode?: boolean }`.
+## Regression testing
 
-```js
-const report = toJsonReport(result, { version: "1.0.0" });
-const counts = summarizeDiagnostics(result.diagnostics);
+Drive the sandbox test suite in the sibling [`react-review`](https://github.com/millionco/react-review) repo against a fleet of real React projects, using the local working copy of `react-doctor` (packed into a tarball).
+
+```bash
+pnpm --filter react-doctor test:regression
 ```
 
-`react-doctor/api` re-exports `JsonReport`, `JsonReportSummary`, `JsonReportProjectEntry`, `JsonReportMode`, plus the lower-level `buildJsonReport` and `buildJsonReportError` builders. See [`packages/react-doctor/src/api.ts`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/api.ts) for the full types.
+The script builds the package, packs it into `packages/react-doctor/.regression/react-doctor-<version>.tgz`, then shells out to `~/Developer/react-review/apps/api` and runs `pnpm test` with:
+
+- `GITHUB_TOKEN` from `gh auth token` (required so GitHub does not 403 the tarball downloads).
+- `REACT_DOCTOR_SPECIFIERS` pointing at the local tarball — `react-review`'s sandbox test detects the `.tgz`, uploads it into the Vercel Sandbox, and installs via `file:`.
+- `REACT_DOCTOR_TEST_REPOS` defaulting to the first 10 repos from a curated fleet, comma-separated `owner/repo` entries.
+
+Preconditions the script checks for and surfaces clear errors when missing:
+
+- `gh auth token` succeeds (run `gh auth login` first if not).
+- `~/Developer/react-review/apps/api` exists.
+- `~/Developer/react-review/apps/api/.env.local` exists (run `vercel env pull` inside `~/Developer/react-review/apps/api` to populate `@vercel/sandbox` credentials).
+
+Overrides:
+
+```bash
+REACT_DOCTOR_REGRESSION_SAMPLE=25 pnpm --filter react-doctor test:regression
+REACT_DOCTOR_REGRESSION_SAMPLE=all pnpm --filter react-doctor test:regression
+REACT_DOCTOR_TEST_REPOS="vercel/ai-chatbot,shadcn-ui/ui" pnpm --filter react-doctor test:regression
+```
+
+Each repo runs sequentially inside a Vercel Sandbox; expect a few minutes per repo. The default 10-repo sample is the sane batch size for a single run.
 
 ## Leaderboard
 
@@ -272,7 +307,7 @@ Top React codebases scanned by React Doctor, ranked by score. Updated automatica
 <!-- prettier-ignore -->
 | #  | Repo | Score |
 | -- | ---- | ----: |
-| 1  | [executor](https://github.com/RhysSullivan/executor) | 96 |
+| 1  | [executor](https://github.com/RhysSullivan/executor) | 94 |
 | 2  | [nodejs.org](https://github.com/nodejs/nodejs.org) | 86 |
 | 3  | [tldraw](https://github.com/tldraw/tldraw) | 70 |
 | 4  | [t3code](https://github.com/pingdotgg/t3code) | 68 |
@@ -296,13 +331,15 @@ Looking to contribute back? Clone the repo, install, build, and submit a PR.
 ```bash
 git clone https://github.com/millionco/react-doctor
 cd react-doctor
-pnpm install
-pnpm build
-node packages/react-doctor/bin/react-doctor.js /path/to/your/react-project
+ni
+nr build
+node packages/react-doctor/bin/react-doctor.js apps/web
 ```
 
 Find a bug? Head to the [issue tracker](https://github.com/millionco/react-doctor/issues).
 
+Release notes are published on [GitHub Releases](https://github.com/millionco/react-doctor/releases).
+
 ### License
 
 React Doctor is MIT-licensed open-source software.