codemod

Codemod 最佳实践

面向 AI Agent 和大模型的 Codemod（JSSG、ast-grep、工作流）综合最佳实践指南。包含 11 个类别中的 48 条规则，并按影响程度排序，为自动化重构和代码生成提供指导。

适用场景

在以下情况中参考这些指南：

• 使用 JSSG 或 ast-grep 编写新的 codemod
• 为迁移设计工作流配置
• 调试模式匹配或 AST 遍历问题
• 审查 codemod 代码的性能和安全性
• 为转换验证设置测试样例

按优先级划分的规则类别

优先级	类别	影响	前缀
1	AST 理解	CRITICAL	ast-
2	模式效率	CRITICAL	pattern-
3	解析策略	CRITICAL	parse-
4	节点遍历	HIGH	traverse-
5	语义分析	HIGH	semantic-
6	编辑操作	MEDIUM-HIGH	edit-
7	工作流设计	MEDIUM-HIGH	workflow-
8	测试策略	MEDIUM	test-
9	状态管理	MEDIUM	state-
10	安全性与能力	LOW-MEDIUM	security-
11	包结构	LOW	pkg-

快速参考

1. AST 理解（CRITICAL）

• ast-explore-before-writing - 编写模式前使用 AST Explorer
• ast-understand-named-vs-anonymous - 理解命名节点与匿名节点的区别
• ast-use-kind-for-precision - 使用 kind 约束提高精度
• ast-field-access-for-structure - 使用字段访问进行结构查询
• ast-check-null-before-access - 访问属性前检查 null

2. 模式效率（CRITICAL）

• pattern-use-meta-variables - 使用元变量进行灵活匹配
• pattern-avoid-overly-generic - 避免过于宽泛的模式
• pattern-combine-with-rules - 使用规则运算符组合模式
• pattern-use-constraints - 使用约束实现可复用的匹配逻辑
• pattern-use-relational-patterns - 使用关系模式获取上下文
• pattern-ensure-idempotency - 确保模式具有幂等性

3. 解析策略（CRITICAL）

• parse-select-correct-parser - 为文件类型选择正确的解析器
• parse-handle-embedded-languages - 使用 parseAsync 处理嵌入式语言
• parse-provide-pattern-context - 为含义模糊的模式提供上下文
• parse-early-return-non-applicable - 对不适用的文件尽早返回

4. 节点遍历（HIGH）

• traverse-use-find-vs-findall - 单个匹配使用 find()，多个匹配使用 findAll()
• traverse-single-pass-collection - 在单次遍历中收集多个模式
• traverse-use-stopby-for-depth - 使用 stopBy 控制遍历深度
• traverse-use-siblings-efficiently - 高效使用同级节点导航
• traverse-cache-repeated-lookups - 缓存重复的节点查找

5. 语义分析（高）

• semantic-use-file-scope-first - 优先使用文件作用域语义分析
• semantic-check-null-results - 处理语义分析的 null 结果
• semantic-verify-file-ownership - 跨文件编辑前验证文件所有权
• semantic-cache-cross-file-results - 缓存语义分析结果

6. 编辑操作（中高）

• edit-batch-before-commit - 提交前批量处理编辑
• edit-preserve-formatting - 保留编辑内容周围的格式
• edit-handle-overlapping-ranges - 处理重叠的编辑范围
• edit-use-flatmap-for-conditional - 条件编辑时使用 flatMap
• edit-add-imports-correctly - 在正确位置添加导入

7. 工作流设计（中高）

• workflow-order-nodes-by-dependency - 按依赖关系排列节点
• workflow-use-matrix-for-parallelism - 使用矩阵策略实现并行
• workflow-use-manual-gates - 为关键步骤设置手动关卡
• workflow-validate-before-run - 运行前验证工作流
• workflow-use-conditional-steps - 在动态工作流中使用条件步骤

8. 测试策略（中）

• test-use-fixture-pairs - 使用输入/预期结果样例对
• test-cover-edge-cases - 在测试样例中覆盖边界情况
• test-use-strictness-levels - 选择合适的测试严格度级别
• test-update-fixtures-intentionally - 有意更新测试样例
• test-run-on-subset-first - 先在部分文件上测试，再进行完整运行

9. 状态管理（中）

• state-use-for-resumability - 使用状态支持迁移续跑
• state-make-transforms-idempotent - 使转换具备幂等性，以便安全地重新运行
• state-log-progress-for-observability - 记录长时间运行的迁移进度，以便观测

10. 安全与能力（低中）

• security-minimize-capabilities - 尽量减少请求的能力
• security-validate-external-inputs - 使用外部输入前进行验证
• security-review-before-running-third-party - 运行第三方 codemod 前进行审查

11. 包结构（低）

• pkg-use-semantic-versioning - 对包采用语义化版本控制
• pkg-write-descriptive-metadata - 编写描述性包元数据
• pkg-organize-by-convention - 按惯例组织包

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 用于添加新规则的模板

完整汇编文档

如需查看包含所有完整规则的指南，请参阅 AGENTS.md。