react-doctor 0.2.0-beta.4 → 0.2.0-beta.6

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
+
+Pick one or both; they're independent.
 
-**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.
+- **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:
@@ -113,6 +186,38 @@ React Doctor respects `.gitignore`, `.eslintignore`, `.oxlintignore`, `.prettier
 
 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.
 
+#### Surface controls (CLI, PR comments, score, CI failure)
+
+Diagnostics flow through four independent surfaces — `cli`, `prComment`, `score`, and `ciFailure` — and each one can be tuned per tag, category, or rule id. By default the `design` tag (Tailwind shorthand cleanup like `w-5 h-5 → size-5`, pure-black backgrounds, gradient text, …) stays visible on the local CLI but is excluded from the PR comment, the score, and the `--fail-on` gate so style cleanup can't dilute meaningful React findings:
+
+```json
+{
+  "surfaces": {
+    "prComment": {
+      "includeTags": ["design"],
+      "excludeCategories": ["Performance"]
+    },
+    "score": { "includeRules": ["react-doctor/design-no-redundant-size-axes"] },
+    "ciFailure": { "excludeTags": ["test-noise"] }
+  }
+}
+```
+
+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.
@@ -210,6 +315,8 @@ Options:
   --offline               skip the score API and share URL (no score shown)
   --fail-on <level>       exit with error on diagnostics: error, warning, none
   --annotations           output diagnostics as GitHub Actions annotations
+  --pr-comment            tune CLI output for sticky PR comments (drops design
+                          cleanup from the printed list and fail-on gate)
   --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
@@ -235,6 +342,7 @@ When a suppression isn't working, `--explain <file:line>` (or its alias `--why <
 | `offline`                  | `boolean`                        | `false`  |
 | `textComponents`           | `string[]`                       | `[]`     |
 | `rawTextWrapperComponents` | `string[]`                       | `[]`     |
+| `serverAuthFunctionNames`  | `string[]`                       | `[]`     |
 | `respectInlineDisables`    | `boolean`                        | `true`   |
 | `adoptExistingLintConfig`  | `boolean`                        | `true`   |
 | `ignore.tags`              | `string[]`                       | `[]`     |
@@ -243,10 +351,34 @@ When a suppression isn't working, `--explain <file:line>` (or its alias `--why <
 
 `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.
 
+`serverAuthFunctionNames` teaches `server-auth-actions` about custom auth guards your codebase wraps around its auth library (e.g. `requireWorkspaceMember`, `ensureSignedIn`). Listed names are accepted as a valid top-of-action auth check whether called bare (`requireWorkspaceMember()`) or as a member (`guards.requireWorkspaceMember()`), and — unlike the built-in default list — are treated as distinctive so the receiver is not re-validated.
+
 `ignore.tags` suppresses entire categories of rules by tag. For example, `"tags": ["design"]` disables all opinionated design rules (gradient text, pure black backgrounds, side tab borders, default Tailwind palettes). Available tags: `"design"`.
 
 `offline` skips the score API entirely — no score is shown and no share URL is generated. Automatically enabled in CI environments (GitHub Actions, GitLab CI, CircleCI) so CI runs don't depend on the network.
 
+### React Native rules in mixed monorepos
+
+`rn-*` rules respect per-package boundaries automatically. In a mixed React Native + web monorepo (`apps/mobile` alongside `apps/web` / `apps/vite-app` / `packages/storybook` / `apps/docs`), every `rn-*` rule walks up to the file's nearest `package.json` before running:
+
+- Packages that declare `react-native`, `react-native-tvos`, `expo`, `expo-router`, `@expo/*`, `react-native-windows`, `react-native-macos`, anything under the `@react-native/` or `@react-native-` namespaces (`@react-native-firebase/app`, `@react-native-async-storage/async-storage`, …), or Metro's top-level `"react-native"` resolution field → rules ON.
+- Packages that declare a web-only framework (`next`, `vite`, `react-scripts`, `gatsby`, `@remix-run/*`, `@docusaurus/*`, `@storybook/*`, or plain `react-dom` without an RN sibling) → rules OFF.
+- Packages with no clear local signal → fall back to the project-level framework detection.
+
+File extensions override the package classification when they're unambiguous: `*.web.tsx` / `*.web.jsx` are always skipped (Metro resolves these only against `react-native-web`); `*.ios.tsx` / `*.android.tsx` / `*.native.tsx` are always scanned (mobile-only).
+
+The detection is bidirectional: a web-rooted monorepo (root `package.json` declares `next` or `vite`) still loads the `rn-*` rules when any workspace targets React Native — the file-level boundary then keeps them silent on the web workspaces and active on the mobile ones.
+
+`rn-no-raw-text` additionally short-circuits raw text inside platform-fork branches:
+
+- `if (Platform.OS === "web") { … }` consequent — and the `else` branch of `if (Platform.OS !== "web")`.
+- `Platform.OS === "web" ? <X /> : …` ternaries, `Platform.OS === "web" && <X />` short-circuits, and the reversed-operand form `"web" === Platform.OS`.
+- `switch (Platform.OS) { case "web": … }` case bodies (other cases still report).
+- `Platform.select({ web: <X />, default: <Y /> })` — only the `web` arm is exempt.
+- `Platform?.OS === "web"` (optional chain) and `Platform.OS! === "web"` (TS non-null assertion) parse the same way as the bare form.
+
+The walker stops at function and `Program` boundaries — JSX defined inside a callback hoisted out of a `Platform.OS` branch does not inherit the parent guard. Negative platform checks like `Platform.OS === "ios"` are deliberately NOT treated as web exemptions; only the explicit web branch is.
+
 ## Scoring
 
 The health score formula: `100 - (unique_error_rules x 1.5) - (unique_warning_rules x 0.75)`.
@@ -280,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).