# React Doctor

Diagnose React codebase health. React Doctor scans for security, performance, correctness, and architecture issues, then outputs a 0-100 score with actionable diagnostics.

Note: dead-code detection was removed in v0.2. For dead-code analysis, run `npx knip` directly.

# Markdown Docs

Use these markdown docs when you need product, setup, configuration, CI, or API guidance.

- [Docs sitemap](/docs/sitemap.md): structured table of contents for every doc page.

## Overview

- [What is React Doctor?](/docs/overview/what-is-react-doctor.md): A deterministic scanner for React codebases and coding-agent workflows.
- [What is a score?](/docs/overview/what-is-a-score.md): How to interpret the 0-100 React Doctor health signal.

## Getting Started

- [Run your first scan](/docs/getting-started/run-your-first-scan.md): Run React Doctor locally and scan changed files.
- [Install for coding agents](/docs/getting-started/install-for-coding-agents.md): Install the React Doctor skill and optional hooks.
- [How to fix issues](/docs/getting-started/how-to-fix-issues.md): Work through diagnostics and suppressions safely.
- [Skills & recurring usage](/docs/getting-started/skills-and-recurring-usage.md): Use React Doctor as a repeatable agent quality loop.

## CI & PRs

- [GitHub Actions setup](/docs/ci-and-prs/github-actions-setup.md): Scan pull requests with annotations and sticky comments.
- [PR feedback](/docs/ci-and-prs/pr-feedback.md): Choose between logs, annotations, and PR comments.
- [Blocking PRs](/docs/ci-and-prs/blocking-prs.md): Roll out diagnostic gates and score floors.

## Configuration

- [Config files](/docs/configuration/config-files.md): Configure rules, categories, surfaces, and scan behavior.
- [Rules, ignores, suppressions](/docs/configuration/rules-ignores-suppressions.md): Tune diagnostics with narrow project controls.
- [ESLint and oxlint plugins](/docs/configuration/eslint-and-oxlint-plugins.md): Run React Doctor rules inside existing lint tools.
- [Companion plugins](/docs/configuration/companion-plugins.md): Add team-specific oxlint-shaped rule plugins.

## Reference

- [CLI reference](/docs/reference/cli-reference.md): Commands and flags for the React Doctor CLI.
- [Node.js API](/docs/reference/node-api.md): Use React Doctor from scripts and services.

## Community

- [Leaderboard](/docs/community/leaderboard.md): Public benchmark scores for React projects.
- [Contributing and license](/docs/community/contributing-and-license.md): Repository structure, tests, and contribution notes.
- [Changelog](/docs/community/changelog.md): Release notes for the React Doctor CLI, pulled from the GitHub changelog.

## Legal

- [Terms of Service](/docs/legal/terms.md): Terms governing access to and use of React Doctor and Million Software services.
- [Privacy Policy](/docs/legal/privacy.md): Privacy information for React Doctor and Million Software services.
- [Data Use](/docs/legal/data-use.md): How React Doctor handles GitHub repository data during pull request analysis.
- [Security](/docs/legal/security.md): How React Doctor handles your code and data, and how to report security issues.

## Company

- [Support](/docs/company/support.md): Get support for React Doctor.
- [Status](/docs/company/status.md): Current service status for React Doctor.

# Prompts

Fetchable, agent-ready markdown prompts. Edit at the source and every consumer (GitHub Actions, coding agents, CLIs) picks up the new version on its next fetch.

- [Prompts sitemap](/prompts/sitemap.md): structured table of contents for every prompt.
- [Prompts index](/prompts.md): all prompt categories with links.
- [Bot playbook](/prompts/react-doctor-bot.md): daily CI triage for the React Doctor GitHub Actions bot.
- [Agent playbook](/prompts/react-doctor-agent.md): local triage for coding agents (Cursor, Claude Code, Codex). Same loop, edits the working tree.
- [Rule index](/prompts/rules.md): every engine rule grouped by category, with links to each per-rule prompt (validation + fix).
- Individual rule: `/prompts/rules/{plugin}/{rule}.md` (e.g. [`/prompts/rules/effect/no-derived-state.md`](/prompts/rules/effect/no-derived-state.md)).

# CLI Quick Reference

Run this at your project root:

```bash
npx react-doctor@latest
```

Use `--verbose` to see affected files and line numbers:

```bash
npx react-doctor@latest --verbose
```

Use `--diff [base]` to scan only files changed vs a base branch. On the default branch, scans uncommitted working-tree changes; on a feature branch, scans changes vs the base.

```bash
npx react-doctor@latest --verbose --diff
```

Use `--score` to output only the numeric score:

```bash
npx react-doctor@latest --score
```

Use `--json` for a single structured JSON report:

```bash
npx react-doctor@latest --json | jq '.summary'
```

Use `-y` to skip prompts in non-interactive environments like CI or coding agents:

```bash
npx react-doctor@latest -y
```

Use `--staged` for pre-commit hooks:

```bash
npx react-doctor@latest --staged
```

Use `--annotations` to emit GitHub Actions annotations:

```bash
npx react-doctor@latest --annotations
```

Use `--fail-on <level>` to control exit codes (`error`, `warning`, `none`):

```bash
npx react-doctor@latest --fail-on error
```

Use `--offline` to skip the score API and the share URL:

```bash
npx react-doctor@latest --offline
```

Install the skill into your coding agent:

```bash
npx react-doctor@latest install
```