react-doctor 0.2.0-beta.5 → 0.2.0

package/README.md

@@ -20,10 +20,12 @@ Works with Next.js, Vite, and React Native.
 Run this at your project root:
 
 ```bash
-npx -y react-doctor@latest .
+npx 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.
+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, and accessibility. Rules toggle automatically based on your framework and React version.
+
+> **Migration note:** React Doctor used to bundle [knip](https://knip.dev/) for dead-code detection. That integration was removed in v0.2 — if you want dead-code analysis, run `npx knip` directly as part of your own pre-commit or CI pipeline.
 
 https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570
 
@@ -32,7 +34,7 @@ https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570
 Teach your coding agent React best practices so it stops writing the bad code in the first place.
 
 ```bash
-npx -y react-doctor@latest install
+npx react-doctor@latest install
 ```
 
 You'll be prompted to pick which detected agents to install for. Pass `--yes` to skip prompts.
@@ -68,16 +70,87 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-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.
+When `github-token` is set on `pull_request` events, findings are posted (and updated) as a sticky PR comment. The action also exposes a `score` output (0–100) you can use in subsequent steps.
+
+**Inputs:** `directory`, `verbose`, `project`, `diff`, `github-token`, `fail-on` (`error` / `warning` / `none`), `offline`, `annotations`, `node-version`. See [`action.yml`](https://github.com/millionco/react-doctor/blob/main/action.yml) for full descriptions.
+
+#### PR feedback modes
 
-**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.
+Pick one or both; they're independent.
+
+- **Comments only** (default): set `github-token`.
+- **Annotations only**: set `annotations: true`.
+- **Both**: set `github-token` and `annotations: true`. Annotation lines are stripped from the comment body.
+
+```yaml
+- uses: millionco/react-doctor@main
+  with:
+    diff: main
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    annotations: true
+```
 
 Prefer not to add a marketplace action? The bare `npx` form works too:
 
 ```yaml
-- run: npx -y react-doctor@latest --fail-on warning
+- run: npx react-doctor@latest --fail-on warning
+```
+
+## PR blocking and exit codes
+
+Two independent gates can block a PR — pick one or both:
+
+- **`--fail-on <level>`** exits non-zero on diagnostics: `error` (default, any error-severity rule fires), `warning` (any diagnostic fires), or `none` (never). Runs against the `ciFailure` surface, so the default `design`-tag exclusion still applies.
+- **Score floor** — a follow-up step that reads the action's `score` output and `exit 1`s when it's below your threshold.
+
+Combine `--fail-on` with `--diff <base>` to scope the gate to the PR's changed files only — that's the built-in way to fail on **new** regressions without dragging in baseline backlog. There is no separate `--fail-on-new` flag.
+
+`--annotations` (bare `npx` only) and `github-token` (sticky PR comment) are visualization layers and never change the exit code.
+
+### Examples
+
+**Advisory mode** — never blocks, always comments:
+
+```yaml
+- uses: millionco/react-doctor@main
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    fail-on: none
 ```
 
+**Regression-only mode** — fail only on new diagnostics introduced by the PR:
+
+```yaml
+- uses: actions/checkout@v5
+  with:
+    fetch-depth: 0 # required for `diff`
+- uses: millionco/react-doctor@main
+  with:
+    diff: main
+    fail-on: warning
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+**Strict threshold mode** — fail when the baseline score drops below a floor:
+
+```yaml
+- id: doctor
+  uses: millionco/react-doctor@main
+  with:
+    fail-on: error
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+- env:
+    SCORE: ${{ steps.doctor.outputs.score }}
+    FLOOR: "80"
+  run: |
+    if [ -n "$SCORE" ] && [ "$SCORE" -lt "$FLOOR" ]; then
+      echo "::error::React Doctor score $SCORE is below floor $FLOOR"
+      exit 1
+    fi
+```
+
+Pin a specific `react-doctor` version when using a score floor — new rule releases can lower the score even when your code hasn't changed (see [Scoring](#scoring)).
+
 ## Configuration
 
 Create a `react-doctor.config.json` in your project root:
@@ -132,6 +205,19 @@ Diagnostics flow through four independent surfaces — `cli`, `prComment`, `scor
 
 Each surface accepts `includeTags`, `excludeTags`, `includeCategories`, `excludeCategories`, `includeRules`, and `excludeRules`. Include wins over exclude when both match. Run the CLI with `--pr-comment` (the GitHub Action passes it automatically when `github-token` is set) to apply the `prComment` surface to the printed output destined for sticky PR comments.
 
+#### Rule severity (`rules`, `categories`)
+
+Same shape as ESLint / oxlint. `rules` is ESLint's exact field; `categories` mirrors oxlint's, keyed by React Doctor display categories (`"React Native"`, `"Server"`, `"Architecture"`, …).
+
+```json
+{
+  "rules": { "react-doctor/no-array-index-as-key": "error" },
+  "categories": { "React Native": "warn" }
+}
+```
+
+Per-rule wins over per-category. `"off"` short-circuits before the rule runs; `"warn"` / `"error"` re-stamps the diagnostic so every channel — CLI, PR comment, score, `--fail-on` — sees the chosen severity, including for external-plugin rules. Use `surfaces` instead when you only want to hide a rule from one channel; use `ignore.tags` to silence a whole tag-defined family (`"design"`, `"test-noise"`, `"migration-hint"`) that doesn't align with a single category.
+
 #### Optional companion plugins
 
 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.
@@ -326,8 +412,8 @@ React Doctor detects 50+ coding agents (Claude Code, Cursor, Codex, OpenCode, Wi
 - **Install for agents**: `npx react-doctor@latest install` writes agent-specific rule files (SKILL.md, AGENTS.md, .cursorrules) into your project so agents learn React best practices.
 - **JSON output**: `--json` produces a structured `JsonReport` on stdout. Errors still produce a valid JSON document with `ok: false`. Use `--json-compact` for minimal whitespace.
 - **Score-only output**: `--score` outputs just the numeric score (0-100), useful for threshold checks in agent loops.
-- **GitHub Actions annotations**: `--annotations` emits `::error` / `::warning` format for inline PR annotations.
-- **Exit codes**: `--fail-on error` (default) exits non-zero when error-severity diagnostics are found. Use `--fail-on warning` or `--fail-on none` to tune CI gating.
+- **GitHub Actions annotations**: `--annotations` emits `::error` / `::warning` format for inline PR annotations. Annotations don't change the exit code.
+- **Exit codes**: `--fail-on error` (default) exits non-zero when error-severity diagnostics are found. Use `--fail-on warning` or `--fail-on none` to tune CI gating. See [PR blocking and exit codes](#pr-blocking-and-exit-codes) for the full model — including how to fail only on new regressions vs. fail on the baseline score.
 - **Programmatic API**: `import { diagnose } from "react-doctor/api"` for direct integration in scripts and automation.
 
 In CI environments, prompts are automatically skipped and `--offline` is implied (no network round-trip; score is omitted from the output).
@@ -361,16 +447,16 @@ Top React codebases scanned by React Doctor, ranked by score. Updated automatica
 <!-- prettier-ignore -->
 | #  | Repo | Score |
 | -- | ---- | ----: |
-| 1  | [executor](https://github.com/RhysSullivan/executor) | 94 |
+| 1  | [executor](https://github.com/RhysSullivan/executor) | 96 |
 | 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 |
+| 3  | [tldraw](https://github.com/tldraw/tldraw) | 71 |
+| 4  | [t3code](https://github.com/pingdotgg/t3code) | 69 |
 | 5  | [better-auth](https://github.com/better-auth/better-auth) | 64 |
-| 6  | [excalidraw](https://github.com/excalidraw/excalidraw) | 63 |
-| 7  | [mastra](https://github.com/mastra-ai/mastra) | 63 |
+| 6  | [mastra](https://github.com/mastra-ai/mastra) | 63 |
+| 7  | [excalidraw](https://github.com/excalidraw/excalidraw) | 62 |
 | 8  | [payload](https://github.com/payloadcms/payload) | 60 |
 | 9  | [typebot](https://github.com/baptisteArno/typebot.io) | 57 |
-| 10 | [plane](https://github.com/makeplane/plane) | 56 |
+| 10 | [medusajs/admin](https://github.com/medusajs/medusa) | 56 |
 
 <!-- LEADERBOARD:END -->