jscodeshift代码转换最佳实践Skill jscodeshift

---

名称: jscodeshift 描述: 来自Facebook/Meta的jscodeshift codemod开发最佳实践。此技能应用于编写、审查或调试jscodeshift codemod时。触发涉及AST转换、代码迁移、自动化重构或codemod开发的任务。

Facebook/Meta jscodeshift 最佳实践

为jscodeshift codemod开发设计的全面最佳实践指南，专为AI代理和LLMs定制。包含8个类别的40条规则，按影响优先级从关键（解析器配置、AST遍历）到渐进（高级模式）排序。每条规则包括详细解释、真实示例和具体影响指标。

何时应用

参考这些指南：

• 为代码迁移编写新的jscodeshift codemod时
• 调试转换失败或意外行为时
• 优化大型代码库上的codemod性能时
• 审查codemod代码的正确性时
• 为边缘案例和回归测试codemod时

按优先级分类的规则类别

优先级	类别	影响	前缀
1	解析器配置	关键	parser-
2	AST遍历模式	关键	traverse-
3	节点过滤	高	filter-
4	AST转换	高	transform-
5	代码生成	中	codegen-
6	测试策略	中	test-
7	运行器优化	低-中	runner-
8	高级模式	低	advanced-

快速参考

1. 解析器配置（关键）

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

2. AST遍历模式（关键）

• 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. 节点过滤（高）

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

4. AST转换（高）

• 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	版本和参考信息