用途:用于审计、审查或 lint Next.js App Router 项目中的 React Hook Form 用法,可在 PR 审查前使用,或作为 CI 门禁(发现 CRITICAL/HIGH 时退出码为 1)。
主要能力:结合 ripgrep 的快速正则检测与 ts-morph 的 AST 结构检测,共 16 条规则、4 个严重级别。示例规则包括:在 useForm() 同一组件中使用 watch()、无参 watch()、useForm() 缺少 defaultValues、在非 "use client" 文件中导入 RHF、父组件内联 <Controller>、异步提交无 try/catch、组件内定义校验 schema、提交调用 fetch/axios 却未 setError('root.*')、RHF 与 useActionState 混用、useFieldArray map 缺少 field.id 作为 key 等。规则 04 已在 0.2.0 移除,因其前提不成立。
工具依赖:rg(ripgrep)、node ≥ 18 与 npm、jq;ts-morph 首次运行安装到 scripts/node_modules/(约 30 秒),不会触碰被审计项目的 node_modules。
使用方式:运行 bash scripts/audit.sh 审计当前目录;bash scripts/audit.sh --project /path/to/nextjs-app 审计指定项目;bash scripts/audit.sh --dry-run 预览且不写报告文件。退出码:0 无 CRITICAL/HIGH;1 存在 CRITICAL/HIGH;2 环境或配置错误。工作流依次为 detect-project.sh、collect-files.sh、detect-fast.sh、detect-ast.mjs、render-report.mjs。首次运行会安装 ts-morph,可在 config.json 中调整 project_root、report_path/json_report_path、rule_link_base、include_globs/exclude_globs。
适用场景与限制:面向 Next.js App Router 且已安装 react-hook-form 的项目。只读操作:读取源文件并写出一份 Markdown 报告(可选 JSON 附属文件)到被审计项目根目录,无 git 操作、无包变更、无网络调用。不覆盖 Server Action / useActionState 相关模式(参见 react-19 技能)。若某检测器噪声过大,建议收窄 include_globs 或扩大 exclude_globs,而非禁用检测器。