codebase-migrate

Codebase Migrate

Coordinate framework upgrades, API renames, config rewrites, and structural refactors across hundreds of files. Local edits are driven by the agent; the Composio CLI handles the surrounding ceremony: tracking issues, per-batch PRs, and CI verification.

When to Use

• Framework upgrade (React 17 → 19, Node 18 → 22, Django 4 → 5).
• API rename across a monorepo (e.g., getUserById → users.byId).
• Config/format migration (webpack → vite, eslint → biome, jest → vitest).
• Any "change 200 files the same way" task that needs to ship in reviewable slices.

Prereqs

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

Local tools the agent will use directly: git, rg, jscodeshift/ts-morph/comby/ast-grep (language-appropriate), and your test runner.

Planning Phase

1. Define the transform precisely. Bad: "migrate to vitest." Good: "replace jest.mock with vi.mock, swap jest.fn() for vi.fn(), rename jest.config.js → vitest.config.ts using template X."
2. Scope the blast radius:

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

3. File a tracking issue:

   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."
   }'
   

Execute in Reviewable Batches

Loop: pick N files → transform → test → PR → wait for green → merge → next batch.

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

The agent runs the codemod on batch.list, then:

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`."
}'

Then poll CI and merge when green: