codemod-react-pipeline

Codemod React Pipeline

一套安全、可重复的工作流，用于在大型遗留代码库中应用 JSX / TSX / React codemod——从重命名 50 个文件，到迁移 10 万个文件中的 API。它将 Codemod CLI（JSSG、ast-grep、工作流）组合成内外循环，并要求每次大规模变更都先经过试运行和验证。关于其中每条规则背后的原因，请参阅配套的 codemod 最佳实践参考。

适用场景

在以下情况下使用此技能：

• 你要在大型 React/TS 代码库中迁移某种模式（组件/属性重命名、废弃 API、导入替换、Hook 迁移），而手动运行 codemod jssg run ./t.ts ./src 风险太高。
• 你需要让变更逐步落地且便于审查——按批次提交、失败后可恢复，并且在每个检查点都确保构建、类型检查和测试通过。
• 你希望在大规模改动文件前，查看并验证发现结果（将会改动哪些内容，以及是否安全）。
• 变换必须具有幂等性，并且在大规模应用前证明这一点。

不要将其用于单文件编辑，或适合在单个 PR 中手动完成的变更。

工作流概览

00 plan ─▶ 01 scaffold ─▶ 02 inner loop ─▶ 03 dry-run ─▶ 04 validate ─▶ 05 batched apply ─▶ 06 verify
   goal       templates      fixture tests     preview       gates          per-batch            final
   + blast    (transform/    + 1-file trial    + findings     (idempotency,  apply+verify+commit  assertions
   radius     rule/wf/tests)                    report        type/lint/test) (resumable)
                                                  │                                  │
                                                  └── sentinel ──── required by ──────┘
                              (on any failure: working tree reverted; fix and re-run — nothing committed yet)

步骤	操作	工具 / 脚本	风险
0	记录目标、分类变换、统计影响范围	scripts/00-plan.sh	只读
1	使用模板搭建变换、测试夹具和工作流	scripts/01-scaffold.sh	写入（新文件）
2	测试夹具 + 单文件试运行（自动还原）	scripts/02-inner-loop.sh	只读（会还原）
3	预览变更；编写发现报告 + 试运行哨兵	scripts/03-dry-run.sh	只读（会还原）
4	检查关卡：幂等性、类型检查、Lint、格式化、测试	scripts/04-validate-findings.sh	只读（会还原）
5	分批应用，可恢复地执行，并逐批验证 + 提交	scripts/05-run-batched.sh	破坏性操作（会提交）
6	对整个迁移执行最终断言	scripts/verify.sh	只读

PreToolUse Hook（hooks/hooks.json）会阻止未带 --dry-run 的宽范围 codemod jssg run，前提是尚无试运行哨兵——因此步骤 5（或临时执行的应用操作）无法跳过步骤 3–4。

要求

• Codemod CLI — npm i -g codemod（若不可用，脚本会回退到 npx codemod）。提供 jssg run/test 和 workflow run/validate/resume/status。
• git — 流水线要求工作树干净，并会按批次创建检查点提交。
• jq — 脚本使用它读取 config.json。
• 项目的检查工具 — TypeScript、ESLint、Prettier、测试运行器（根据你在 config.json 中启用的检查项而定）。

设置

为目标仓库编辑 config.json（参见各字段的 _setup_instructions）：

• src_globs：codemod 可能修改的文件（限定影响范围 + 检查范围）
• language：tsx | jsx | typescript | javascript
• typecheck_cmd / lint_cmd / format_cmd / test_cmd：检查命令（留空可禁用相应检查）
• batch_size：外循环中每个检查点处理的文件数
• gates：各项检查的启用/禁用开关

将 state_dir（默认为 .codemod-pipeline）添加到目标仓库的 .gitignore 中。

快速参考

脚本	用途
scripts/00-plan.sh "<goal>" [name]	制定计划 + 估算影响范围
scripts/01-scaffold.sh <name> [--rule]	搭建 JSSG 变换（或 ast-grep 规则）
scripts/02-inner-loop.sh <name> [--watch|--file P|-u]	紧密循环：测试夹具 / 单文件试运行
scripts/03-dry-run.sh <name> [--sample N]	预览；编写发现结果 + 哨兵
scripts/04-validate-findings.sh <name>	运行验证检查
scripts/05-run-batched.sh <name> [--batch-size N|--dry]	可恢复的分批应用 + 提交
scripts/verify.sh <name>	最终签核断言
scripts/selftest.sh	自测此技能的脚本/资源

使用方法

1. 在目标仓库根目录中运行 00-plan.sh "<goal>"，然后阅读生成的 plan.md。
2. 运行 01-scaffold.sh <name>，然后实现 codemods/<name>/transform.ts 及其测试夹具。
3. 运行 02-inner-loop.sh <name> --watch，反复迭代，直到测试夹具通过；尝试对真实文件使用 --file <path>。
4. 运行 03-dry-run.sh <name> 并阅读结果报告；然后运行 04-validate-findings.sh <name>。
5. 只有通过各项门槛后，才能运行 05-run-batched.sh <name>（出现任何问题并修复后，重新运行即可恢复）。
6. 运行 verify.sh <name>，确认迁移已完成且具有幂等性。

关于每个步骤的输入、输出、故障处理和回滚，请参阅 references/workflow.md；关于思维模型，请参阅 references/inner-outer-loop.md； 关于在 10 万个文件规模下的分批处理和回滚，请参阅 references/safety-and-scale.md。

注意事项

请参阅 gotchas.md。其中最重要的几点：工作流中的 commit: 检查点仅适用于云端（流水线会改为在本地提交）；务必排除生成文件和供应商代码目录；并从第一行代码开始就确保幂等性。

相关技能

• codemod — 本流水线实际采用的最佳实践参考（48 条规则）。 此处的步骤会引用具体规则（例如 test-run-on-subset-first、state-use-for-resumability、 pattern-ensure-idempotency、security-minimize-capabilities）。