# React Audit Playbook

For any finding that maps to a React Doctor rule, never invent the fix. Copy the
reviewer-tested recipe from `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md`,
or run `npx react-doctor@latest rules explain <rule>`. The exact fix is not yours
to approximate; the canonical prompt is.

Use these five categories as the user-facing audit buckets. Judge leverage from
user impact and execution frequency, not from the rule's raw severity alone.
Confirm every finding at its `path:line`, and respect deliberate suppressions,
disabled rules, and documented tradeoffs.

## 1. Bugs & correctness

This category covers behavior that can render the wrong UI, lose state, create
stale data, or break React's rendering model. High leverage means a defect on a
shared route, a hot interaction, or a stateful list—not a theoretical issue in
dead or rarely reached code.

**Hunt for:**

- `no-array-index-as-key` — Array index used as a key; insertion and reordering
  can attach state to the wrong row.
- `no-random-key` — Random value used as a key; every render remounts the item.
- `jsx-key` — Missing key in list; React cannot reconcile siblings reliably.
- `exhaustive-deps` — Missing effect dependencies; closures observe stale state.
- `no-self-updating-effect` — Effect updates its own dependency; feedback loops.
- `no-set-state-in-render` — State update during render; render-loop risk.
- `no-uncontrolled-input` — Uncontrolled input value; controlled behavior drifts.
- `rendering-conditional-render` — Number before `&&` renders stray `0`.

**Beyond the scan:** Check async races, cancellation on unmount, state machines
with impossible transitions, optimistic updates that need rollback, and whether
an effect belongs in an event handler. Look for missing error and Suspense
boundaries around failure-prone or loading-sensitive subtrees.

## 2. Performance

This category covers work repeated in render, layout, the main thread, or the
network. Leverage is impact multiplied by frequency and fan-out: a per-keystroke
editor, provider, or 10,000-row list outranks the same pattern in a settings
dialog. Do not optimize cold paths merely because a rule can be satisfied.

**Hunt for:**

- `jsx-no-constructed-context-values` — Unstable context provider value; all
  consumers can re-render when the provider renders.
- `jsx-no-new-object-as-prop` — New object passed as a prop.
- `jsx-no-new-array-as-prop` — New array passed as a prop.
- `jsx-no-new-function-as-prop` — New function passed as a prop.
- `no-inline-prop-on-memo-component` — Inline prop defeats `memo()`.
- `rerender-dependencies` — Unstable value recreated every render.
- `no-layout-property-animation` — Animating a layout property.
- `no-transition-all` — `transition: all` animates unintended properties.

**Beyond the scan:** Profile before and after. Hunt context fan-out, expensive
selectors, waterfalls, cache misses, image and bundle costs, and work that can
move to a server or transition. Reject premature `useMemo`/`memo` on cold paths:
the optimization can be noise, add dependency hazards, and obscure code.

## 3. Accessibility

This category covers whether keyboard, screen-reader, zoom, and other assistive
technology users can discover and operate the interface. Leverage is highest on
primary navigation, forms, dialogs, and controls used in every session; verify
the semantic and interaction context rather than blindly silencing a rule.

**Hunt for:**

- `alt-text` — Image missing alt text.
- `control-has-associated-label` — Control missing accessible label.
- `click-events-have-key-events` — Click handler missing keyboard handler.
- `no-static-element-interactions` — Interaction on static element.
- `prefer-tag-over-role` — Role used instead of the native HTML tag.
- `no-autofocus` — Autofocus on an element.
- `no-outline-none` — `outline:none` removes the focus ring.
- `no-disabled-zoom` — Zoom disabled on the viewport.

**Beyond the scan:** Test the actual tab order, focus return after dialogs,
keyboard escape and roving focus, live-region announcements, loading and error
states, contrast in real themes, reduced motion, touch target size, and zoom at
200–400%. A valid static label can still be misleading in the product flow.

## 4. Security

This category covers code and configuration that lets attacker-controlled data
become code, authority, secrets, or an unsafe browser action. Leverage is
highest at trust boundaries: client/server transitions, auth, uploads, HTML
sinks, redirects, and privileged mutations. Trace the data, not just the
syntax.

**Hunt for:**

- `no-danger` — Raw HTML injection can run unsafe markup.
- `dangerous-html-sink` — HTML injection sink with dynamic content.
- `jsx-no-script-url` — `javascript:` URL in JSX.
- `jsx-no-target-blank` — Unsafe `target="_blank"` link.
- `no-eval` — `eval()` runs untrusted code strings.
- `no-secrets-in-client-code` — Secret in client code.
- `auth-token-in-web-storage` — Auth token in web storage.
- `untrusted-redirect-following` — Server fetch follows redirects for
  caller-shaped URL.

**Beyond the scan:** Verify authorization server-side, tenant isolation, CSRF
and origin checks, CSP and cookie flags, upload/content-type handling, rate
limits, dependency trust, and logging redaction. A sanitizer at one sink does
not make an untrusted value safe at another; follow it to its source and
privileged effect.

## 5. Maintainability & architecture

This category covers structures that make changes risky, conventions unclear,
and ownership or rendering behavior hard to reason about. Leverage means
repeated cost across a team or a component's centrality—not a preference for
abstraction or a low-risk style nit.

**Hunt for:**

- `no-giant-component` — Large component is hard to read and change.
- `no-nested-component-definition` — Component defined inside another component.
- `no-many-boolean-props` — Boolean prop combinations are hard to test.
- `prefer-module-scope-static-value` — Static value rebuilt every render.
- `prefer-module-scope-pure-function` — Pure function rebuilt every render.
- `no-event-handler` — Event logic handled in an effect.
- `no-mirror-prop-effect` — Prop mirrored into state via effect.
- `design-no-vague-button-label` — Vague button label.

**Beyond the scan:** Examine ownership boundaries, public component APIs,
context design, dependency direction, test seams, duplicated domain logic, and
whether abstractions communicate intent. Hunt missing error/Suspense boundaries,
overloaded providers, optimistic UI opportunities, and premature memoization.
Do not split a component or add a hook just to satisfy a metric.

## Working rule

The scan supplies evidence; the senior audit supplies leverage and context.
For every rule-backed plan, fetch the canonical prompt, quote the current code,
and inline the exact target recipe. For every missed opportunity, label it
separately from a diagnostic finding and state what runtime or product evidence
would confirm its value.
