BumpGuard

BumpGuard

Proteja seus bumps de dependências. BumpGuard é um servidor Model Context Protocol (MCP) que diz ao seu agente de codificação de IA exatamente quais linhas do seu código quebram quando você atualiza uma dependência — e verifica código escrito por IA contra a API que está realmente instalada, para que ele pare de chamar funções que não existem.

Ele faz isso apenas com análise estática. BumpGuard nunca importa ou executa código de terceiros; ele lê a API pública real de um pacote diretamente do seu código-fonte.

Documentações dizem ao seu agente o que deveria existir. BumpGuard diz a ele o que realmente existe aqui.

---

Por que isso existe

A frustração nº 1 que desenvolvedores relatam com ferramentas de codificação de IA é código "quase certo, mas não exatamente." Uma grande parte disso é deriva de API e alucinação:

• O modelo escreve pydantic.BaseSettings ou openai.ChatCompletion.create(...) — perfeitamente válido há duas versões, removido na versão que você tem instalada.
• Você atualiza pandas de 1.5 para 2.2 e descobre a quebra um stack trace por vez.
• Um changelog lista 1.800 mudanças de quebra; você só se importa com as três que seu código realmente toca.

BumpGuard fecha essa lacuna com a verdade do seu ambiente em vez da memória do modelo.

---

O que ele faz

Um exemplo real — atualizando pydantic 1 → 2 em código que usa BaseSettings:

// check_upgrade(package="pydantic", to_version="2.0.3", from_version="1.10.13", code="...")
{
  "safe_to_upgrade": false,
  "summary": { "breaking": 1, "total_api_changes": 4919, "breaking_api_changes": 2015 },
  "findings": [
    {
      "symbol": "pydantic.BaseSettings",
      "line": 2,
      "severity": "breaking",
      "message": "You use 'pydantic.BaseSettings', which no longer exists in the target version...",
      "suggestion": "Consider 'pydantic.v1.env_settings.BaseSettings'"
    }
  ]
}

De 2.015 mudanças de quebra de API, BumpGuard trouxe à tona a única que afeta este código — com o número da linha e uma dica de correção.

---

Ferramentas

Ferramenta	O que ela responde
check_upgrade ⭐	"Se eu atualizar package para to_version, o que neste código quebra?" Compara a API instalada (ou from_version) com a alvo e relata apenas as mudanças que seu código realmente atinge, com severidade e dicas de correção.
diff_versions	"O que mudou entre duas versões desta biblioteca?" A lista bruta de mudanças de quebra, sem varredura de código — bom para planejar uma migração.
verify_snippet	"Os imports e chamadas de API neste código realmente existem aqui?" Detecta nomes de pacotes alucinados/com erros de digitação (slopsquatting) e atributos que não estão no pacote instalado.
check_import	"Este pacote está instalado? Se não, qual é o nome real mais próximo?"
list_symbols	"Qual é a API pública real deste pacote?" Descubra funções/classes/métodos + assinaturas em vez de adivinhar — para a versão instalada ou qualquer versão buscada.
list_languages	Quais provedores de ecossistema estão disponíveis.

Toda resposta é fundamentada em evidências (versão instalada, localização do código-fonte). Como a análise é estática, "nenhum achado" significa "nada comprovadamente quebrado", não uma garantia — BumpGuard é explícito sobre isso em sua saída.

---

Instalação

pip install bumpguard-mcp

Requer Python 3.10+. O servidor fala MCP via stdio.

Instale o BumpGuard no mesmo ambiente do projeto em que você está trabalhando, para que ele veja os pacotes que você realmente tem instalados.

---

Configure seu cliente MCP

Claude Desktop / Claude Code (claude_desktop_config.json):

{
  "mcpServers": {
    "bumpguard": {
      "command": "bumpguard-mcp"
    }
  }
}

Cursor / Windsurf / VS Code (Copilot) — aponte sua configuração MCP para o comando bumpguard-mcp (ou python -m bumpguard.server). Qualquer cliente compatível com MCP funciona.

Depois pergunte ao seu agente coisas como:

• "Antes de atualizar o pandas para 2.2, verifique se meu pipeline de dados quebra."
• "Verifique se este trecho realmente usa o SDK OpenAI instalado."
• "Liste os métodos reais em httpx.Client."

---

Como funciona

                 ┌──────────────── language‑neutral core ────────────────┐
   MCP tools  →  │  diff engine · breaking‑change classifier · analyzer  │
                 │  (matches API changes against YOUR usage)             │
                 └───────────────────────┬──────────────────────────────┘
                                         │ Provider interface
                 ┌───────────────────────┴──────────────────────────────┐
                 │  Python provider  │  .NET (NuGet)   │  Java (Maven)   │
                 │  • AST surface    │  • DLL metadata │  • jar bytecode │
                 │  • usage scanner  │  • Roslyn scan  │  • source scan  │
                 │  • wheel fetch    │  • nupkg fetch  │  • jar fetch    │
                 └──────────────────────────────────────────────────────┘

1. Extrai a superfície da API pública de um pacote analisando seu código-fonte com o ast do Python — para a versão instalada e para a versão alvo (baixada como wheel e descompactada, nunca instalada ou executada).
2. Compara as duas superfícies em símbolos removidos / com assinatura alterada / adicionados, e classifica cada um como quebra, potencialmente quebra ou informação.
3. Escaneia seu código (também via ast) em busca de usos — resolvendo aliases de import, re-exports, chamadas de métodos de instância e os argumentos de palavra-chave/posicionais que cada chamada passa.
4. Corresponde os usos às mudanças e relata um veredito preciso, linha por linha.

Segurança: BumpGuard nunca importa código de terceiros, então não há efeitos colaterais de import, nem travamentos por pacotes pesados, nem execução arbitrária de código. Downloads de wheels são isolados em um diretório temporário, com limite de tempo e protegidos contra path traversal / zip bombs.

---

Multi-linguagem por design

BumpGuard é construído em torno de uma interface de provedor plugável. O mecanismo de diff, o classificador de mudanças de quebra, o analisador, o relatório e as ferramentas MCP são todos neutros em relação à linguagem; apenas a extração de superfície e a varredura de usos são específicas do ecossistema.

• ✅ Python (PyPI) — disponível agora.
• ✅ .NET (NuGet) — disponível agora. Lê a API pública de metadados de assembly via carregamento somente-reflexão (nenhum código executado); precisa do .NET SDK (dotnet) no PATH. Um pequeno auxiliar é compilado uma vez no primeiro uso.
• ✅ Java (Maven) — disponível agora. Lê a API pública diretamente do bytecode .jar compilado (constant pool, flags de acesso, descritores) em Python puro — sem JDK ou Maven necessário e nenhum código de terceiros é executado.
• 🔜 JS/TS (npm) — analisa declarações .d.ts.

Adicionar um ecossistema significa implementar um Provider — veja docs/ADD_A_PROVIDER.md.

Especificidades do .NET (v1)

• Passe language: "dotnet". Exemplo: "Antes de atualizar Azure.AI.OpenAI para 2.1.0, verifique se meu código de cliente quebra (from_version 1.0.0-beta.17)."
• Suportado: check_upgrade, diff_versions, list_symbols, check_import.
• Prefira passar from_version — a linha de base "instalada" é obtida do cache global do NuGet, que não é a versão fixada do seu projeto.
• Sinal confiável: remoções e adições de tipos / métodos / propriedades (por exemplo, a renomeação OpenAIClient → AzureOpenAIClient é detectada como uma remoção de quebra com uma sugestão). Diffs em nível de parâmetro são executados apenas para membros inequívocos de sobrecarga única; membros sobrecarregados são rastreados por presença (um limite documentado da v1).
• Referências totalmente qualificadas são relatadas com confiança; nomes curtos resolvidos via using são relatados como "potencialmente quebra" de menor confiança para evitar falsas quebras duras por colisões de namespace.
• verify_snippet não é suportado para .NET na v1 (detecção precisa de alucinação em C# precisa de vinculação semântica).

Especificidades do Java (v1)

• Passe language: "java" e identifique pacotes pela coordenada Maven group:artifact (por exemplo, com.google.code.gson:gson). Exemplo: "Antes de atualizar com.google.code.gson:gson para 2.10.1, verifique se meu código quebra (from_version 2.8.9)."
• Suportado: check_upgrade, diff_versions, list_symbols, check_import.
• A superfície da API pública é lida diretamente do bytecode .jar (o jar é um zip de arquivos .class; BumpGuard analisa a estrutura do arquivo de classe com struct — lendo metadados, nunca executando). O jar alvo é buscado no Maven Central (isolado, com limite de tamanho e tempo). Sem JDK/Maven necessário.
• Prefira passar from_version — a linha de base "instalada" é lida do seu cache local ~/.m2, que pode não corresponder à versão fixada do seu projeto.
• Sinal confiável: remoções e adições de tipos / métodos / campos / construtores, e mudanças de aridade. Referências totalmente qualificadas quebram duramente; nomes curtos resolvidos via import são relatados como "potencialmente quebra" de menor confiança para evitar falsas quebras duras por colisões de namespace.
• Limites documentados da v1: genéricos são apagados em descritores de bytecode (então mudanças de argumentos de tipo genérico não são vistas); mudanças somente de tipo de retorno e remoção de varargs são rastreadas conservadoramente; membros sobrecarregados são rastreados por presença (remoção por sobrecarga não é detectada); jars multi-release usam a sobreposição de versão mais alta. O scanner de usos de código-fonte é uma heurística robusta, não um parser completo — ele pode pegar a declaração de um nome ou a linha import como referência, mas isso resolve para nomes não qualificados que são limitados a "potencialmente quebra" e nunca podem produzir uma falsa quebra dura. verify_snippet não é suportado para Java na v1 (detecção precisa de alucinação precisa de vinculação semântica).

---

Limitações conhecidas (v1, Python)

BumpGuard é honesto sobre análise estática. Ele pode perder (falsos negativos) ou, raramente, sinalizar demais (falsos positivos):

• APIs geradas dinamicamente (módulos __getattr__, registros de plugins, clientes estilo boto3). BumpGuard detecta módulos __getattr__ e suprime achados confiantes de "símbolo ausente" sob eles.
• Membros criados em tempo de execução que não são visíveis no código-fonte.
• Internos de extensões compiladas (C/Rust) — a superfície em nível de Python ainda é lida.
• Rastreamento profundo de fluxo de instância é limitado a padrões diretos de x = Class(...).
• Re-exports com estrela (from .x import *) não são expandidos.

Trate os achados como orientação de alto sinal, e a ausência de achados como "não comprovadamente inseguro", não uma garantia.

---

Desenvolvimento

git clone https://github.com/appcreationsca/bumpguard-mcp
cd bumpguard-mcp
python -m venv .venv && . .venv/Scripts/activate   # Windows
pip install -e ".[dev]"
pytest

A suíte de testes (42 testes) roda offline usando pacotes de fixture — sem necessidade de rede.

Lançamento

Os lançamentos são automatizados via GitHub Actions. Para cortar um lançamento:

1. Aumente a versão em pyproject.toml e src/bumpguard/__init__.py.
2. Mova as notas "Unreleased" do CHANGELOG.md sob um novo cabeçalho de versão.
3. Faça commit, depois crie a tag e envie:

git tag v0.1.0
git push origin v0.1.0

O fluxo de trabalho Release executa os testes, compila o wheel + sdist e publica no PyPI via Trusted Publishing (OIDC — sem tokens armazenados). O fluxo de trabalho CI executa a matriz de testes (Linux + Windows, Python 3.10/3.13) em cada push e PR.

---

Licença

MIT — veja LICENSE.