codebase-migrate

代码库迁移

跨数百个文件协调框架升级、API 重命名、配置重写和结构重构。本地修改由 Agent 驱动；Composio CLI 负责处理外围流程：跟踪问题、为每个批次创建 PR，以及 CI 验证。

适用场景

• 框架升级（React 17 → 19、Node 18 → 22、Django 4 → 5）。
• 在单体代码库中重命名 API（例如，getUserById → users.byId）。
• 配置／格式迁移（webpack → vite、eslint → biome、jest → vitest）。
• 任何需要以便于审查的批次分阶段交付的“以相同方式修改 200 个文件”任务。

前置条件

curl -fsSL https://composio.dev/install | bash
composio login
composio link github        # for PRs + CI status
composio link linear        # or jira — for migration tracking

Agent 将直接使用的本地工具：git、rg、jscodeshift／ts-morph／comby／ast-grep（根据语言选择），以及你的测试运行器。

规划阶段

1. 精确定义转换内容。 不好的描述：“迁移到 vitest。” 好的描述：“将 jest.mock 替换为 vi.mock，将 jest.fn() 换成 vi.fn()，并使用模板 X 将 jest.config.js 重命名为 vitest.config.ts。”
2. 界定影响范围：

   rg -l 'jest\.(mock|fn|spyOn)' | wc -l
   rg -l 'from "jest"' | sort
   

3. 创建跟踪问题：

   composio execute LINEAR_CREATE_ISSUE -d '{
     "teamId":"TEAM_ID",
     "title":"Migrate test runner: jest → vitest",
     "description":"Batches of ~25 files. Checkpoint after each PR lands green."
   }'
   

分批执行，便于审查

循环：选择 N 个文件 → 转换 → 测试 → 创建 PR → 等待检查通过 → 合并 → 进入下一批。

# Batch helper: first 25 untouched files matching the pattern
BATCH=$(rg -l 'jest\.mock' | grep -v done.list | head -25)
echo "$BATCH" > batch.list

Agent 在 batch.list 中运行 codemod，然后：

git checkout -b migrate/vitest-batch-03
xargs < batch.list codemod-runner   # e.g. jscodeshift / ts-morph / comby
npm test -- --changed
git add -A && git commit -m "migrate(test): jest → vitest (batch 3)"
git push -u origin migrate/vitest-batch-03

composio execute GITHUB_CREATE_A_PULL_REQUEST -d '{
  "owner":"acme","repo":"app",
  "head":"migrate/vitest-batch-03","base":"main",
  "title":"migrate(test): jest → vitest (batch 3)",
  "body":"Part of LIN-482. 25 files. Codemod: `transforms/jest-to-vitest.ts`."
}'

接着轮询 CI，并在检查通过后合并：

composio execute GITHUB_LIST_WORKFLOW_RUNS_FOR_A_REPOSITORY \
  -d '{"owner":"acme","repo":"app","branch":"migrate/vitest-batch-03"}'

工作流脚本

scripts/migrate-batch.ts，每个批次通过 composio run --file scripts/migrate-batch.ts -- --batch 3 运行：

const batch = process.argv[process.argv.indexOf("--batch") + 1];

const pr = await execute("GITHUB_CREATE_A_PULL_REQUEST", {
  owner: "acme", repo: "app",
  head: `migrate/vitest-batch-${batch}`, base: "main",
  title: `migrate(test): jest → vitest (batch ${batch})`,
  body: `Part of LIN-482. See transforms/jest-to-vitest.ts.`
});

await execute("LINEAR_CREATE_COMMENT", {
  issueId: "LIN-482",
  body: `Opened PR #${pr.number}: ${pr.html_url}`
});

安全措施

• 每个 PR 只做一种转换。 绝不要将重命名与格式更改混在一起。
• 维护一份 done.list，记录已迁移的文件，让下一批跳过这些文件。
• 在最后一批运行完整测试套件，即使每批的 PR 都运行了 --changed。
• 先运行 codemod，再手动编辑。 如果 codemod 漏掉了 3 个文件，请手动修复，并在 PR 正文中说明。
• 按批次回滚，不要全局回滚。每个 PR 都应能干净地撤销。

验证循环

每次合并后：

rg 'jest\.(mock|fn|spyOn)' | wc -l     # should trend to 0
npm test                                # full suite
composio execute GITHUB_LIST_WORKFLOW_RUNS_FOR_A_REPOSITORY \
  -d '{"owner":"acme","repo":"app","branch":"main","event":"push"}' \
  | jq '.workflow_runs[0].conclusion'

故障排除

• Codemod 正则匹配过多内容 → 改用基于 AST 的工具（ast-grep、ts-morph）进行结构匹配。
• 本地测试通过，但 CI 失败 → 确保 Node/Python 版本一致；检查 .nvmrc／pyproject.toml。
• PR 太大，难以审查 → 将批次大小减半；维护者不会审查 800 行的差异。
• 批次之间发生冲突 → 合并当前批次前，先对尚未合并的批次进行 rebase；绝不要对已合并的批次强制推送。

CLI 完整参考：docs.composio.dev/docs/cli