react-hook-form-audit

Next.js 向け React Hook Form 監査

Next.js App Router のコードベースで、React Hook Form のアンチパターンを 16 種類検出する静的解析監査です。ripgrep（正規表現で検出可能なルールを素早くチェック）と ts-morph（構造的なルールをチェックする AST パス）を組み合わせています。重大度ごとに分類した Markdown レポートを出力し、ファイル名と行番号、および付属の react-hook-form 蒸留スキルへのリンクを示します。

適用するタイミング

• Next.js プロジェクトで React Hook Form の使用状況を監査、レビュー、または lint するよう依頼されたとき
• 「フォームの再レンダリングが多すぎる」「RHF の原因不明なバグがある」などの症状が報告されたとき
• RHF を多用する新しいコードの PR をレビューする前
• CI のゲートとして（CRITICAL/HIGH の検出結果がある場合は終了コード 1）
• react-hook-form のアップグレード後、古くなったアドバイスを検出するとき

ツール要件

• rg（ripgrep）— brew install ripgrep または使用しているパッケージマネージャーからインストールします
• npm を含む node ≥ 18 — ts-morph を使用して AST 検出器を実行します
• jq — オーケストレーターで JSON を処理します

初回実行時に ts-morph が scripts/node_modules/ にインストールされます（一度のみ、約 30 秒）。このスキルが監査対象プロジェクトの node_modules に触れることはありません。

リスクレベル

読み取り専用です。 このスキルはソースファイルを読み取り、監査対象プロジェクトのルートに Markdown レポートを 1 つ（および任意で JSON サイドカーファイルを）書き込みます。Git 操作、パッケージの変更、ネットワーク呼び出しは行いません。

ワークフローの概要

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

各ステップの仕様、エラー処理、CI との統合については、references/workflow.md を参照してください。

使用方法

# 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

終了コード：

• 0 — CRITICAL または HIGH の検出結果はありません
• 1 — CRITICAL または HIGH の検出結果があります
• 2 — 環境または設定のエラーです（ツールが見つからない、プロジェクトが無効など）

検出器一覧

4 段階の重大度にわたる 16 個の検出器があります。各ルールのパターン、AST の形状、誤検出に関する注記、および検出器が適用するアドバイスについては、references/detectors.md を参照してください。

ID	重大度	検出内容
01	CRITICAL	useForm() と同じコンポーネント内の watch()
02	CRITICAL	引数なしの watch()（すべてのフィールドを購読）
03	CRITICAL	defaultValues のない useForm()
05	CRITICAL	"use client" のないファイルでの RHF のインポート
06	HIGH	useForm() を呼び出す親コンポーネント内に直接記述された <Controller>
07	HIGH	try/catch のない非同期送信ハンドラー
08	HIGH	コンポーネント内で定義されたバリデーションスキーマ
09	HIGH	fetch/axios を呼び出すが setError('root.*') を呼び出さない送信処理
10	HIGH	同じコンポーネント内で RHF と useActionState を併用
11	MEDIUM	説明コメントのない mode: 'onChange'
12	MEDIUM	視覚的な無効化に register({ disabled: <state> }) を使用
13	MEDIUM	field.id をキーとして指定していない useFieldArray の map
14	LOW	reValidateMode: 'onBlur'（現在は推奨度が引き下げられたアドバイス）
15	LOW	useFormContext() の使用（手動レビューが必要）
16	MEDIUM	useFieldArray({ disabled: <state> }) — すべての変更操作が何も起こさずに無視されます
17	MEDIUM	values プロパティの代わりに useEffect と reset(data) を使用

ルール 04（useForm の戻り値に依存する useEffect）は 0.2.0 で削除されました。前提が誤っていたためです。references/detectors.md を参照してください。

使用手順

1. プロジェクトが react-hook-form をインストール済みの Next.js App Router アプリであることを確認します（detect-project.sh が確認します）
2. bash scripts/audit.sh [--project <path>] を実行します
3. プロジェクトルートに生成された .rhf-audit-report.md を読みます
4. 各検出結果について、リンク先の付属の蒸留ルールに従って修正します
5. 修正後、再実行して監査結果が問題ないことを確認します

プロジェクト内で特定の検出器による誤検出が多い場合は、検出器を無効にするのではなく、config.json の include_globs を絞るか、exclude_globs を広げてください。一覧は十分に小さいため、検出結果は実際の問題か、コメントに記録する価値のある例外のいずれかであるべきです。

セットアップ

このスキルには、config.json に適切なデフォルト設定が含まれています。初回実行時に、audit.sh が ts-morph を scripts/node_modules/ にインストールします。設定を変更するには、config.json を編集してください。

• project_root — プロジェクトの絶対パス（デフォルトは現在のディレクトリ）
• report_path / json_report_path — 出力ファイル名（プロジェクトルートからの相対パス）
• rule_link_base — 関連ルールへのリンクに使用するベース URL またはパス
• include_globs / exclude_globs — スキャン対象を絞り込みます

参照ファイル

• references/workflow.md — 詳細なワークフロー、エラー処理、CI 統合
• references/detectors.md — 検出器ごとの仕様、AST の形式、誤検出に関する注意事項
• gotchas.md — 蓄積された失敗事例（追記のみ）

関連スキル

• react-hook-form — この監査ツールが適用する 35 のルールを含む、関連する抽出スキルです。検出結果はその参照ファイルに直接リンクします。
• react-19 — 監査の対象外である Server Action / useActionState のパターン向け