react-hook-form-audit

React Hook Form Audit for Next.js

Static-analysis audit that detects 16 React Hook Form anti-patterns in Next.js App Router codebases. Combines ripgrep (fast pass for regex-detectable rules) with ts-morph (AST pass for structural rules). Outputs a markdown report grouped by severity, with file:line references and links back to the companion react-hook-form distillation skill.

When to Apply

• User asks to audit, review, or lint React Hook Form usage in a Next.js project
• User reports symptoms like "the form re-renders too much" or "we have RHF bugs we can't pin down"
• Before a PR review of new RHF-heavy code
• As a CI gate (exit code 1 on CRITICAL/HIGH findings)
• After upgrading react-hook-form, to catch advice that drifted

Tool Requirements

• rg (ripgrep) — install via brew install ripgrep or your package manager
• node ≥ 18 with npm — used to run the AST detectors via ts-morph
• jq — for JSON munging in the orchestrator

ts-morph is installed on first run into scripts/node_modules/ (one-time, ~30s). The skill never touches the audited project's node_modules.

Risk Level

Read-only. The skill reads source files and writes one markdown report (plus an optional JSON sidecar) to the audited project root. No git operations, no package mutations, no network calls.

Workflow Overview

1. detect-project.sh   Verify Next.js + react-hook-form in package.json
2. collect-files.sh    Ripgrep for "use client" files importing RHF
3. detect-fast.sh      Ripgrep detectors (rules 5, 11, 14)
4. detect-ast.mjs      ts-morph detectors (rules 1-3, 6-10, 12-13, 15-17)
5. render-report.mjs   Render markdown + JSON; print summary; exit 0/1

See references/workflow.md for the per-step contract, error handling, and CI integration.

Usage

# Audit the current directory
bash scripts/audit.sh

# Audit a specific project
bash scripts/audit.sh --project /path/to/nextjs-app

# Preview without writing the report file
bash scripts/audit.sh --dry-run