Migração de Base de Código

O que Migração de Base de Código faz?

Coordene upgrades de frameworks, renomeações de API, reescritas de configuração e refatorações estruturais em centenas de arquivos. As edições locais são conduzidas pelo agente; a CLI do Composio lida com a cerimônia ao redor: rastreamento de issues, PRs por lote e verificação de CI.

Quando Usar

• Upgrade de framework (React 17 → 19, Node 18 → 22, Django 4 → 5).
• Renomeação de API em um monorepo (ex.: getUserById → users.byId).
• Migração de configuração/formato (webpack → vite, eslint → biome, jest → vitest).
• Qualquer tarefa "mudar 200 arquivos da mesma forma" que precise ser entregue em fatias revisáveis.

Pré-requisitos

curl -fsSL https://composio.dev/install | bash
composio login
composio link github        # para PRs + status de CI
composio link linear        # ou jira — para rastreamento de migração

Ferramentas locais que o agente usará diretamente: git, rg, jscodeshift/ts-morph/comby/ast-grep (apropriadas para a linguagem) e seu executor de testes.

Fase de Planejamento

1. Defina a transformação com precisão. Ruim: "migrar para vitest." Bom: "substituir jest.mock por vi.mock, trocar jest.fn() por vi.fn(), renomear jest.config.js → vitest.config.ts usando template X."
2. Escopo do raio de alcance:

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

3. Abra uma issue de rastreamento:

   composio execute LINEAR_CREATE_ISSUE -d '{
     "teamId":"TEAM_ID",
     "title":"Migrar executor de testes: jest → vitest",
     "description":"Lotes de ~25 arquivos. Checkpoint após cada PR ficar verde."
   }'
   

Executar em Lotes Revisáveis

Loop: pegue N arquivos → transforme → teste → PR → espere verde → mescle → próximo lote.

# Auxiliar de lote: primeiros 25 arquivos não tocados que correspondem ao padrão
BATCH=$(rg -l 'jest\.mock' | grep -v done.list | head -25)
echo "$BATCH" > batch.list

O agente executa o codemod em batch.list, depois:

git checkout -b migrate/vitest-batch-03
xargs < batch.list codemod-runner   # ex.: 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":"Parte de LIN-482. 25 arquivos. Codemod: `transforms/jest-to-vitest.ts`."
}'

Em seguida, consulte o CI e mescle quando estiver verde:

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

Script de Workflow

scripts/migrate-batch.ts, executado por lote via 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: `Parte de LIN-482. Veja transforms/jest-to-vitest.ts.`
});

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

Medidas de Segurança

• Uma transformação por PR. Nunca misture uma renomeação com uma mudança de formato.
• Mantenha um done.list dos arquivos já migrados para que o próximo lote os ignore.
• Execute o conjunto completo de testes no último lote, mesmo que os PRs por lote tenham executado --changed.
• Codemod primeiro, edição manual depois. Se o codemod perder 3 arquivos, corrija-os manualmente e anote no corpo do PR.
• Reverter por lote, não globalmente. Cada PR deve reverter limpo.

Loop de Verificação

Após cada mesclagem:

rg 'jest\.(mock|fn|spyOn)' | wc -l     # deve tender a 0
npm test                                # suíte completa
composio execute GITHUB_LIST_WORKFLOW_RUNS_FOR_A_REPOSITORY \
  -d '{"owner":"acme","repo":"app","branch":"main","event":"push"}' \
  | jq '.workflow_runs[0].conclusion'

Solução de Problemas

• Regex do codemod pega demais → alterne para ferramentas baseadas em AST (ast-grep, ts-morph) para correspondências estruturais.
• Testes passam localmente, CI falha → fixe a paridade da versão Node/Python; verifique .nvmrc / pyproject.toml.
• PR grande demais para revisar → reduza o tamanho do lote pela metade; mantenedores não revisarão diffs de 800 linhas.
• Conflitos entre lotes → faça rebase do lote aberto antes de mesclar o lote atual; nunca force push em lotes já mesclados.

Referência completa da CLI: docs.composio.dev/docs/cli