react-doctor 0.2.0 → 0.2.2

package/README.md

@@ -70,7 +70,7 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-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.
+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 read in subsequent steps — see [PR blocking and exit codes](#pr-blocking-and-exit-codes) for a score-floor recipe.
 
 **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.
 
@@ -143,7 +143,13 @@ Combine `--fail-on` with `--diff <base>` to scope the gate to the PR's changed f
     SCORE: ${{ steps.doctor.outputs.score }}
     FLOOR: "80"
   run: |
-    if [ -n "$SCORE" ] && [ "$SCORE" -lt "$FLOOR" ]; then
+    # `score` is best-effort and may be empty (e.g. when offline is on).
+    # Skip the floor when it's empty so unrelated PRs aren't blocked.
+    if [ -z "$SCORE" ]; then
+      echo "::notice::React Doctor score unavailable — skipping floor check"
+      exit 0
+    fi
+    if [ "$SCORE" -lt "$FLOOR" ]; then
       echo "::error::React Doctor score $SCORE is below floor $FLOOR"
       exit 1
     fi
@@ -158,7 +164,7 @@ Create a `react-doctor.config.json` in your project root:
 ```json
 {
   "ignore": {
-    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
+    "rules": ["react-doctor/no-danger", "react-doctor/no-autofocus"],
     "files": ["src/generated/**"],
     "overrides": [
       {
@@ -167,7 +173,7 @@ Create a `react-doctor.config.json` in your project root:
       },
       {
         "files": ["components/search/HighlightedSnippet.tsx"],
-        "rules": ["react/no-danger"]
+        "rules": ["react-doctor/no-danger"]
       }
     ]
   }
@@ -220,12 +226,13 @@ Per-rule wins over per-category. `"off"` short-circuits before the rule runs; `"
 
 #### 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.
+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. 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/*` |
 
-| 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 8 rules from [`eslint-plugin-react-you-might-not-need-an-effect`](https://github.com/nickjvandyke/eslint-plugin-react-you-might-not-need-an-effect) (NickvanDyke, MIT) are now ported natively into React Doctor — they fire as `react-doctor/no-derived-state`, `react-doctor/no-chain-state-updates`, `react-doctor/no-event-handler`, `react-doctor/no-adjust-state-on-prop-change`, `react-doctor/no-reset-all-state-on-prop-change`, `react-doctor/no-pass-live-state-to-parent`, `react-doctor/no-pass-data-to-parent`, and `react-doctor/no-initialize-state`. No peer dependency required.
 
 ### Inline suppressions
 
@@ -258,7 +265,7 @@ Block comments work inside JSX:
 
 <!-- prettier-ignore -->
 ```tsx
-{/* react-doctor-disable-next-line react/no-danger */}
+{/* react-doctor-disable-next-line react-doctor/no-danger */}
 <div dangerouslySetInnerHTML={{ __html }} />
 ```
 
@@ -355,7 +362,7 @@ When a suppression isn't working, `--explain <file:line>` (or its alias `--why <
 
 `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.
+`offline` skips the score API entirely — no score is shown and no share URL is generated. CI runs (GitHub Actions, GitLab CI, CircleCI) are not offline by default; only the share URL is suppressed. Set `offline: true` (or `--offline`) explicitly when you want zero network.
 
 ### React Native rules in mixed monorepos
 
@@ -383,7 +390,7 @@ The walker stops at function and `Program` boundaries — JSX defined inside a c
 
 The health score formula: `100 - (unique_error_rules x 1.5) - (unique_warning_rules x 0.75)`.
 
-Scoring runs on react.doctor's API and is **network-dependent**: without a successful API round-trip (or under `--offline`) the score is omitted and the rest of the report still renders normally. Key details:
+Scoring runs on react.doctor's API and is **network-dependent**: without a successful API round-trip (or under `--offline`) the score is omitted and the rest of the report still renders normally. Score-based automation must treat an empty value as a no-op (see the strict-threshold example above). Key details:
 
 - The score counts **unique rules triggered**, not total instances. Fixing 49 of 50 `no-barrel-import` violations does not change the score; fixing all 50 removes the 0.75 penalty for that rule.
 - Error-severity rules cost 1.5 points each. Warning-severity rules cost 0.75 points each.
@@ -405,6 +412,52 @@ When on a feature branch without explicit flags, you'll be prompted: "Only scan
 
 `--staged` and `--diff` cannot be combined.
 
+### Pre-commit hooks with Husky + lint-staged
+
+The most common setup is [Husky](https://typicode.github.io/husky/) for the git hook and [lint-staged](https://github.com/lint-staged/lint-staged) to filter which files run through each tool. React Doctor's `--staged` mode is built for this: it reads file contents from the git **index** (not the working tree) and materializes them into a temp directory, so partially-staged files are scanned exactly as they will be committed.
+
+Install both, then wire them up:
+
+```bash
+npx ni -D husky lint-staged
+npx husky init
+```
+
+`husky init` creates `.husky/pre-commit`. Replace its contents with:
+
+```bash
+npx lint-staged
+```
+
+Then add a `lint-staged` block to your `package.json`. Because React Doctor already filters to the staged set via `--staged`, **do not pass the lint-staged-injected file list** — invoke it with a single command and let it discover the index itself:
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": "react-doctor --staged --fail-on warning"
+  }
+}
+```
+
+A few notes that bite people:
+
+- **Don't append `{staged-files}`** — lint-staged would otherwise pass the matched paths as positional arguments and you'd get the union (path filter + index scan) instead of the intent.
+- **Use the function form when you only want the hook to run if any matching file is staged** but still want a single project-wide scan:
+
+  ```js
+  // lint-staged.config.js
+  export default {
+    "*.{ts,tsx,js,jsx}": () => "react-doctor --staged --fail-on warning",
+  };
+  ```
+
+- **`--fail-on warning`** blocks the commit on any diagnostic. Use `--fail-on error` for a softer gate, or `--fail-on none` to lint advisory-only.
+- **Index vs. working tree:** `--staged` reflects `git diff --cached`, not your editor buffer. If you `git add` half a file and keep typing, only the added half is scanned — the unstaged tail is ignored.
+- **Skip in CI:** lint-staged is a pre-commit concern. In CI, use the GitHub Action (above) or `react-doctor --diff <base>` directly; running both does duplicate work.
+- **Other hook managers:** the same `react-doctor --staged --fail-on warning` command works under [Lefthook](https://lefthook.dev/), [pre-commit](https://pre-commit.com/), or a hand-written `.git/hooks/pre-commit` — `--staged` is hook-manager-agnostic.
+
+To bypass the hook for a one-off commit, use `git commit --no-verify`.
+
 ## Agent and CI integration
 
 React Doctor detects 50+ coding agents (Claude Code, Cursor, Codex, OpenCode, Windsurf, and more) and adapts its behavior automatically:
@@ -416,7 +469,7 @@ React Doctor detects 50+ coding agents (Claude Code, Cursor, Codex, OpenCode, Wi
 - **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).
+In CI environments, prompts are automatically skipped. Pass `--offline` explicitly when you need zero network.
 
 ## Node.js API
 

package/dist/chunk-q7NCDQ7-.js

@@ -0,0 +1,26 @@
+import { createRequire } from "node:module";
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
+export { __require as n, __toESM as r, __commonJSMin as t };