react-hook-form-audit

Next.js 的 React Hook Form 审计

静态分析审计工具，可检测 Next.js App Router 代码库中的 16 种 React Hook Form 反模式。它结合 ripgrep（快速扫描可通过正则表达式检测的规则）与 ts-morph（通过 AST 扫描结构性规则）。输出按严重程度分组的 Markdown 报告，其中包含文件:行号引用，以及指向配套 react-hook-form 提炼技能的链接。

适用场景

• 用户要求审计、审查或检查 Next.js 项目中的 React Hook Form 用法
• 用户报告诸如“表单重新渲染次数太多”或“我们有些 RHF 问题一直找不出原因”等症状
• 在审查包含大量 RHF 代码的 PR 之前
• 用作 CI 门禁（发现 CRITICAL/HIGH 项时退出码为 1）
• 升级 react-hook-form 后，检查相关建议是否已过时

工具要求

• rg（ripgrep）——通过 brew install ripgrep 或你的包管理器安装
• node ≥ 18 和 npm——用于通过 ts-morph 运行 AST 检测器
• jq——用于编排脚本中的 JSON 处理

首次运行时会将 ts-morph 安装到 scripts/node_modules/（一次性操作，约 30 秒）。此技能不会触碰受审计项目的 node_modules。

风险等级

只读。 此技能会读取源文件，并在受审计项目根目录写入一份 Markdown 报告（以及可选的 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 — 环境或配置错误（缺少工具、项目无效）

检测器目录

16 个检测器，分为 4 个严重级别。各规则的模式、AST 结构、误报说明，以及检测器所执行的建议，请参阅 references/detectors.md。

ID	严重程度	检测内容
01	CRITICAL	与 useForm() 位于同一组件中的 watch()
02	CRITICAL	不带参数的 watch()（订阅所有字段）
03	CRITICAL	useForm() 未设置 defaultValues
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	useFieldArray 映射缺少将 field.id 作为 key
14	LOW	reValidateMode: 'onBlur'（此建议现已降级）
15	LOW	使用 useFormContext()（需人工审查）
16	MEDIUM	useFieldArray({ disabled: <state> })——所有变更操作都会静默失效
17	MEDIUM	使用 useEffect + reset(data)，而非 values 属性

规则 04（useEffect 依赖 useForm 返回值）已在 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 模式