MigrateLib: a tool for end-to-end Python library migration

1. O Problema

A migração de bibliotecas é o processo de substituir uma biblioteca de software por outra que oferece funcionalidades semelhantes. Este processo é tradicionalmente manual, demorado e propenso a erros, exigindo que os desenvolvedores:

• Compreendam as APIs de ambas as bibliotecas (origem e destino).
• Mapeiem as APIs equivalentes.
• Realizem transformações de código complexas, que podem envolver mudanças de sintaxe, lógica assíncrona e dependências.

As técnicas automatizadas existentes geralmente limitam-se ao mapeamento de APIs (identificar qual função substitui qual) ou suportam apenas um conjunto restrito de bibliotecas e transformações. Poucas ferramentas realizam a transformação de código completa (substituição real no repositório) de forma end-to-end para pares de bibliotecas arbitrários. Além disso, o uso de Modelos de Linguagem de Grande Escala (LLMs) para essa tarefa enfrenta desafios como a geração de código incompleto, desconhecimento de dependências contextuais e incompatibilidade de versões.

2. Metodologia

Os autores abordaram o problema em três fases distintas, utilizando Python como linguagem de estudo devido à sua popularidade e rico ecossistema de bibliotecas.

Fase 1: Exploração Empírica de LLMs

• Objetivo: Avaliar a capacidade de LLMs de realizar migrações de bibliotecas.
• Dados: Utilizaram o PyMigBench, um benchmark com 314 migrações reais de bibliotecas Python (extraídas do GitHub).
• Modelos Testados: Llama 3.1, GPT-4o mini e GPT-4o.
• Processo: Os modelos foram instruídos a migrar arquivos específicos. A correção foi avaliada comparando as mudanças geradas com as mudanças reais dos desenvolvedores (ground truth) e executando testes unitários.
• Descobertas Iniciais: O GPT-4o foi o melhor desempenho (57% de migrações totalmente corretas), mas todos os modelos enfrentaram desafios como:
  1. Não saber quais arquivos precisam de migração antecipadamente.
  2. Retornar código incompleto (pulando partes não alteradas).
  3. Falha em propagar mudanças de assinatura (ex: tornar funções assíncronas em chamadores transitivos).
  4. Incompatibilidade de versões de bibliotecas.

Fase 2: Construção da Ferramenta MigrateLib

Com base nas descobertas da Fase 1, os autores desenvolveram o MigrateLib, uma ferramenta de linha de comando (CLI) que automatiza o processo completo combinando LLMs com análise estática e dinâmica.

• Entrada: Caminho do projeto Python, bibliotecas de origem e destino (com versões), e versão do Python.
• Passos do Processo:
  1. Preparação: Configuração de ambiente virtual e identificação automática de arquivos que usam a biblioteca de origem (usando análise estática de imports e análise dinâmica de chamadas via call graph gerado durante testes).
  2. Migração com LLM: O GPT-4o é acionado com prompts específicos que incluem as versões das bibliotecas para evitar erros de compatibilidade.
  3. Pós-processamento 1 (Mesclar código pulado): Se o LLM omitir partes do código (comum quando o bloco não precisa mudar), o MigrateLib detecta essas omissões via diff e reintegra o código original ao migrado.
  4. Pós-processamento 2 (Inferir transformação assíncrona): Se a migração tornar uma função assíncrona, a ferramenta identifica todos os chamadores transitivos dessa função e adiciona automaticamente as palavras-chave async e await necessários, além de atualizar os testes.
  5. Validação: Execução contínua de testes unitários para verificar a correção.

Fase 3: Avaliação em Grande Escala

• Dados: 717 cenários de migração simulada em 175 projetos Python reais (não presentes no benchmark inicial).
• Critério de Sucesso: Migrações onde todos os testes que passavam antes continuam passando após a migração, sem intervenção humana.
• Análise de Esforço Manual: Para migrações não totalmente automáticas, os autores realizaram correções manuais em um subconjunto para medir o esforço residual (linhas de código editadas).

3. Principais Contribuições

1. Estudo Empírico: Uma análise sistemática das capacidades e limitações de LLMs na migração de bibliotecas, categorizando tipos de mudanças de código (usando a taxonomia PyMigTax) onde os modelos têm sucesso ou falham.
2. Ferramenta MigrateLib: Desenvolvimento de uma ferramenta de código aberto, end-to-end, que integra LLMs com análise de fluxo de controle e testes para automatizar a migração completa, resolvendo problemas de contexto e integridade de código.
3. Novo Setup de Avaliação: Criação de um método de avaliação baseado em testes simulados em larga escala, permitindo testar migrações em projetos novos sem depender de um "ground truth" de desenvolvedores pré-existente.

4. Resultados

• Fase 1 (Benchmark): O GPT-4o conseguiu realizar 57% das migrações com correção total no benchmark. Com validação baseada em testes, a taxa foi de 64%.
• Fase 3 (MigrateLib em Projetos Reais):
  • Automação Total: O MigrateLib completou 32% das 717 migrações simuladas com 100% de correção, sem nenhuma intervenção humana.
  • Melhoria com Pós-processamento: A correção mediana das migrações aumentou de 65% (apenas LLM) para 86% após os passos de pós-processamento (mesclagem de código e inferência assíncrona).
  • Redução de Esforço: Para as migrações que não foram totalmente automáticas, o MigrateLib realizou uma mediana de 73% das mudanças necessárias. O esforço manual residual necessário para completar a migração foi de apenas 27% das linhas de código alteradas.
  • Falhas Comuns: As principais razões para falhas incluíram lógica complexa do projeto difícil de entender, necessidade de atualizar expectativas de testes (mocks), e mudanças de configuração de ambiente que o LLM não percebeu.

5. Significado e Impacto

O trabalho demonstra que é viável automatizar a migração de bibliotecas de ponta a ponta para pares arbitrários de bibliotecas Python, superando as limitações das ferramentas anteriores que focavam apenas no mapeamento de APIs.

• Redução de Barreira: O MigrateLib reduz significativamente o custo e o risco de atualizar dependências em projetos grandes, permitindo que desenvolvedores foquem apenas nas exceções complexas.
• Validação de LLMs: Confirma que, quando combinados com análise estática/dinâmica e validação por testes, os LLMs podem ser motores confiáveis para tarefas complexas de engenharia de software, indo além da simples geração de código.
• Reprodutibilidade: O código-fonte, dados experimentais e scripts estão disponíveis publicamente, facilitando a reprodução e o avanço da pesquisa na área.

Em resumo, o MigrateLib representa um avanço prático na automação de manutenção de software, transformando uma tarefa manual e propensa a erros em um processo altamente automatizado e confiável para a maioria dos cenários de migração.