react-doctor 0.1.3 → 0.1.5

package/README.md

@@ -41,17 +41,42 @@ Works with Claude Code, Cursor, Codex, OpenCode, and 50+ other agents.
 
 ## GitHub Actions
 
+A composite action ships with this repository. Drop it into `.github/workflows/react-doctor.yml`:
+
 ```yaml
-- uses: actions/checkout@v5
-  with:
-    fetch-depth: 0 # required for --diff
-- uses: millionco/react-doctor@main
-  with:
-    diff: main
-    github-token: ${{ secrets.GITHUB_TOKEN }}
+name: React Doctor
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write # required to post PR comments
+
+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 }}
 ```
 
-When `github-token` is set on `pull_request` events, findings are posted as a PR comment. The action also outputs a `score` (0 to 100) you can use in subsequent steps.
+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.
+
+**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.
+
+Prefer not to add a marketplace action? The bare `npx` form works too:
+
+```yaml
+- run: npx -y react-doctor@latest --fail-on warning
+```
 
 ## Configuration
 
@@ -64,20 +89,39 @@ Create a `react-doctor.config.json` in your project root:
     "files": ["src/generated/**"],
     "overrides": [
       {
-        "files": ["components/diff/**"],
-        "rules": ["react-doctor/no-array-index-as-key"]
+        "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"]
       }
     ]
   }
 }
 ```
 
-`ignore.rules` silences a rule everywhere. `ignore.files` silences every rule on matched files. `ignore.overrides` silences specific rules in specific directories. You can also use the `"reactDoctor"` key in `package.json`. CLI flags always override config values.
+Three nested keys, three layers of granularity — pick the narrowest one 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.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 respects `.gitignore`, `.eslintignore`, `.oxlintignore`, `.prettierignore`, and `linguist-vendored` / `linguist-generated` annotations in `.gitattributes`. Inline `// eslint-disable*` and `// oxlint-disable*` comments are honored too.
 
 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.
 
+#### 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.
+
+| 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/*`         |
+
 ### Inline suppressions
 
 ```tsx
@@ -88,7 +132,24 @@ useEffect(() => {
 }, [value]);
 ```
 
-When two rules fire on the same line, comma-separate the rule ids on a single comment. Block comments work inside JSX:
+When two rules fire on the same line, you have two equivalent options. Comma-separate the rule ids on a single comment:
+
+```tsx
+// react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers, react-doctor/no-derived-useState
+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:
+
+```tsx
+// react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers
+// react-doctor-disable-next-line react-doctor/no-derived-useState
+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
@@ -151,10 +212,11 @@ Options:
   --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
 ```
 
-When a suppression isn't working, `--explain <file:line>` reports what the scanner sees at that location, including why a nearby `react-doctor-disable-next-line` didn't apply. The same hint surfaces inline with `--verbose` and in `--json` output as `diagnostic.suppressionHint`.
+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.
 
 `--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.
 
@@ -211,15 +273,15 @@ Top React codebases scanned by React Doctor, ranked by score. Updated automatica
 | #  | Repo | Score |
 | -- | ---- | ----: |
 | 1  | [executor](https://github.com/RhysSullivan/executor) | 96 |
-| 2  | [nodejs.org](https://github.com/nodejs/nodejs.org) | 87 |
-| 3  | [tldraw](https://github.com/tldraw/tldraw) | 76 |
-| 4  | [t3code](https://github.com/pingdotgg/t3code) | 75 |
-| 5  | [mastra](https://github.com/mastra-ai/mastra) | 70 |
-| 6  | [excalidraw](https://github.com/excalidraw/excalidraw) | 69 |
-| 7  | [payload](https://github.com/payloadcms/payload) | 69 |
-| 8  | [better-auth](https://github.com/better-auth/better-auth) | 69 |
-| 9  | [rocket.chat](https://github.com/RocketChat/Rocket.Chat) | 67 |
-| 10 | [typebot](https://github.com/baptisteArno/typebot.io) | 66 |
+| 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 |
+| 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 |
+| 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 |
 
 <!-- LEADERBOARD:END -->