codebase-migrate

コードベースの移行

エージェントがローカルの編集を行い、Composio CLI が周辺作業（課題の追跡、バッチごとの PR、CI の検証）を担うことで、数百のファイルにわたるフレームワークのアップグレード、API の名前変更、設定の書き換え、構造的なリファクタリングを調整します。

使用する場面

• フレームワークのアップグレード（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

エージェントが直接使用するローカルツール：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 を作成する → CI が成功するまで待つ → マージする → 次のバッチに進む。

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

エージェントは 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 ごとに変換は 1 つだけにします。 名前変更とフォーマット変更を決して混在させないでください。
• 移行済みファイルの 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 行の差分をレビューしません。
• バッチ間で競合が発生する → 現在のバッチをマージする前に、作業中のバッチをリベースします。マージ済みのバッチを強制プッシュしてはいけません。

CLI の全リファレンス：docs.composio.dev/docs/cli