jscodeshift Codemods 是一套编写与调试基于 AST 的自动化代码转换（codemod）的方法。核心理念是转换 AST 节点而非文本，由 recast 负责打印以保留格式与结构。
用途：适合 API 迁移（如库升级）、模式标准化、系统性移除废弃 API、大规模重构（重命名函数、调整 import、更新调用模式）。不适合一次性修改、需要语义理解的业务逻辑改动或非确定性转换。
工作流：分为五阶段——识别模式（收集前后示例、记录规则、找边缘情况）、创建测试夹具（输入/输出夹具，先让测试失败）、实现转换（查找节点、应用变换、返回源码）、处理边缘情况（可重复执行/幂等、缺失依赖）、规模化验证（干跑、抽样复查、加 --fail-on-error）。项目结构通常为 codemods/ 下放转换实现与 tests、testfixtures 目录。
转换模块：默认导出一个函数，签名接受 fileInfo、api、options，通过 api.jscodeshift 取自 j，用 j(fileInfo.source) 建根，查找并修改节点后返回 root.toSource()。返回字符串表示转换结果，null 表示跳过该文件，undefined 表示无改动。
主要能力：Collection API 提供 find、filter、forEach、replaceWith、remove、insertBefore/insertAfter、closest、paths、size 等链式方法；覆盖 Identifier、CallExpression、MemberExpression、ImportDeclaration/Specifier、VariableDeclaration、ArrowFunctionExpression 等常见节点类型；文档给出重命名 import 源、重命名具名导入、按需添加 import、重命名函数调用、转换参数、跨作用域追踪变量、替换整个表达式等模式。
测试与调试：使用 jscodeshift/dist/testUtils 的 defineTest 基于夹具测试，可命名夹具覆盖边缘情况；用 npx jest codemods/tests/ 运行测试。调试可用 npx jscodeshift -t my-transform.ts target/ --dry --print 干跑、--verbose=2 看统计、--fail-on-error 出错即失败。
CLI：npx jscodeshift -t transform.ts src/ 为基本用法，TypeScript/TSX 可加 --parser=tsx --extensions=ts,tsx，另有 --dry、--print、--cpus、--ignore-pattern 等选项。
限制与注意：避免过度匹配（只按标识符名匹配会误伤）、忽略作用域、不检查幂等、破坏性重建节点丢失注释与格式、只测正常路径。