jscodeshift

Facebook/Meta jscodeshift 最佳实践

面向 AI Agent 和大模型的 jscodeshift codemod 开发综合最佳实践指南。包含 8 个类别中的 40 条规则，按影响程度排序，从关键项（解析器配置、AST 遍历）到渐进优化项（高级模式）。每条规则都包含详细说明、真实示例和具体影响指标。

适用场景

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

• 为代码迁移编写新的 jscodeshift codemod
• 调试转换失败或异常行为
• 优化 codemod 在大型代码库上的性能
• 检查 codemod 代码的正确性
• 测试 codemod 的边缘情况和回归问题

按优先级划分的规则类别

优先级	类别	影响	前缀
1	解析器配置	CRITICAL	parser-
2	AST 遍历模式	CRITICAL	traverse-
3	节点筛选	HIGH	filter-
4	AST 转换	HIGH	transform-
5	代码生成	MEDIUM	codegen-
6	测试策略	MEDIUM	test-
7	Runner 优化	LOW-MEDIUM	runner-
8	高级模式	LOW	advanced-

快速参考

1. 解析器配置（CRITICAL）

• parser-typescript-config - 为 TypeScript 文件使用正确的解析器
• parser-flow-annotation - 为 Flow 类型代码使用 Flow 解析器
• parser-babel5-compat - 避免在现代语法中使用默认的 babel5compat
• parser-export-declaration - 从转换模块导出解析器
• parser-astexplorer-match - 使 AST Explorer 解析器与 jscodeshift 解析器匹配

2. AST 遍历模式（CRITICAL）

• traverse-find-specific-type - 在 find() 调用中使用特定节点类型
• traverse-two-pass-pattern - 对复杂转换使用两遍模式
• traverse-early-return - 无需转换时提前返回
• traverse-find-filter-pattern - 使用带筛选对象的 find()，而不是 filter() 链
• traverse-closest-scope - 对作用域感知型转换使用 closestScope()
• traverse-avoid-repeated-find - 避免对同一节点类型重复调用 find()

3. 节点筛选（HIGH）

• filter-path-parent-check - 转换前检查父路径
• filter-import-binding - 跟踪导入绑定以准确检测使用情况
• filter-nullish-checks - 属性访问前添加空值检查
• filter-jsx-context - 区分 JSX 上下文和普通 JavaScript
• filter-computed-properties - 在筛选器中处理计算属性键

4. AST 转换（HIGH）

• transform-builder-api - 使用构建器 API 创建 AST 节点
• transform-replacewith-callback - 使用 replaceWith 回调执行上下文感知型转换
• transform-insert-import - 在正确位置插入导入语句
• transform-preserve-comments - 替换节点时保留注释
• transform-renameto - 使用 renameTo 重命名变量
• transform-remove-unused-imports - 转换后移除未使用的导入

5. 代码生成（中）

• codegen-tosource-options - 配置 toSource()，以保持格式一致
• codegen-preserve-style - 使用 recast 保留原始代码风格
• codegen-template-literals - 使用模板字面量创建复杂节点
• codegen-print-width - 为长行设置合适的打印宽度

6. 测试策略（中）

• test-inline-snapshots - 使用 defineInlineTest 验证输入和输出
• test-negative-cases - 优先编写负向测试用例
• test-dry-run-exploration - 使用 dry run 模式探索代码库
• test-fixture-files - 使用 fixture 文件处理复杂测试用例
• test-parse-errors - 测试解析错误处理

7. 运行器优化（低至中）

• runner-parallel-workers - 配置工作线程数量，以实现最佳并行处理
• runner-ignore-patterns - 使用忽略模式跳过非源文件
• runner-extensions-filter - 按扩展名筛选文件
• runner-batch-processing - 分批处理大型代码库
• runner-verbose-output - 使用详细输出调试转换

8. 高级模式（低）

• advanced-compose-transforms - 将多个转换组合成流水线
• advanced-scope-analysis - 使用作用域分析安全地转换变量
• advanced-multi-file-state - 通过选项在多个文件间共享状态
• advanced-custom-collections - 创建自定义集合方法

使用方法

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

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

完整汇编文档

如需查看包含所有规则的完整综合文档，请参阅 AGENTS.md。

参考文件

文件	描述
AGENTS.md	包含所有规则的完整汇编指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息