ast-impact-mapper-mcp

Usa o AST do TypeScript para determinar quais testes são afetados por alterações no código.

Documentação

🗺️ ast-impact-mapper-mcp ✨

"Pare de tentar esvaziar o oceano. Execute apenas os testes que realmente se importam com suas alterações." 🐸

ast-impact-mapper-mcp é um servidor avançado de Model Context Protocol (MCP) que analisa seu código TypeScript/JavaScript usando parsing de AST (ts-morph) e rastreamento de grafo de dependências. Ele ajuda agentes de IA (como Claude ou Cursor) a mirar apenas os testes relevantes, encontrar código morto, identificar dependências circulares de importação e rastrear mutações de API.

🧐 Por que grafos de importação?

Adivinhar testes afetados com base na correspondência de nomes de arquivos (ex.: auth.ts -> auth.test.ts) é altamente impreciso. Executar toda a suíte de testes a cada mudança menor é extremamente lento.

Grafos de importação não mentem. Se um arquivo de teste importa transitivamente um arquivo-fonte modificado, ele deve ser executado. ast-impact-mapper-mcp constrói um grafo de dependências bidirecional entre arquivos e responde "quais testes devo executar?" em milissegundos.

💡 Demonstração Rápida (Fluxo e2e do Mundo Real)

Imagine que seu agente de IA modifica um helper compartilhado: src/utils/auth.ts. Em vez de executar todos os testes às cegas ou adivinhar pelo nome, o agente usa este servidor MCP:

1. Identificar Testes Afetados

O agente chama get_affected_tests com o arquivo alterado:

// Tool Call: get_affected_tests({ changed_files: ["src/utils/auth.ts"] })
{
  "changed_files": ["/project/src/utils/auth.ts"],
  "affected_tests": ["/project/tests/checkout.spec.ts"],
  "total_affected": 1
}

2. Explicar a Conexão

Para entender por que checkout.spec.ts depende de auth.ts, o agente chama explain_impact:

// Tool Call: explain_impact({ changed_file: "src/utils/auth.ts", test_file: "tests/checkout.spec.ts" })
{
  "found": true,
  "import_chain": [
    "/project/tests/checkout.spec.ts",
    "/project/src/fixtures/user-fixture.ts",
    "/project/src/utils/auth.ts"
  ]
}

Ah! O spec de checkout importa o user-fixture, que importa auth!

3. Verificar Impacto em Tempo de Execução

Se a mudança em auth.ts foi apenas adicionar uma interface TypeScript (mudança somente de tipo), chamar differentiate_type_impact informa ao agente:

{
  "files": [{ "file": "/project/src/utils/auth.ts", "runtime_impact": false }],
  "total_tests_must_run": 0,
  "total_tests_skippable": 1
}

Sucesso! Como é uma mudança somente de tipo, o agente pode pular a execução dos testes completamente, economizando ciclos de CPU e tempo preciosos.

4. Executar Testes Mínimos

Se houver mudanças em tempo de execução, o agente solicita o comando de execução:

// Tool Call: generate_test_command({ changed_files: ["src/utils/auth.ts"], runner: "vitest" })
{
  "command": "npx vitest run tests/checkout.spec.ts"
}

🛠️ Referência das Ferramentas MCP

Todas as ferramentas são configuradas com esquemas consistentes e type-safe (argumentos em snake_case).

1. Mapeamento e Rastreamento de Impacto

get_affected_tests

Encontra todos os arquivos de teste que importam transitivamente arquivos-fonte alterados.
- Argumentos:
  - project_root (string, obrigatório): Caminho absoluto para o projeto TypeScript.
  - changed_files (string[], opcional): Caminhos de arquivos modificados.
  - git_diff (string, opcional): Saída bruta do stdout de git diff --name-only.
- Retorna: Mapa detalhado de arquivos alterados, testes afetados e totais.
get_affected_tests_by_branch

Automaticamente faz diff do estado atual contra uma branch base usando git para encontrar testes afetados.
- Argumentos:
  - project_root (string, obrigatório)
  - base_branch (string, padrão: "main"): Branch para comparar.
get_rename_aware_diff

Análise de impacto de branch altamente robusta que rastreia movimentações/renomeações de arquivos (via git diff -M) e ignora mudanças de formatação/espaçamento.
- Argumentos:
  - project_root (string, obrigatório)
  - base_branch (string, padrão: "main")
  - similarity_threshold (number, padrão: 90): Limiar de % de similaridade para declarar uma movimentação.
explain_impact

Rastreia e explica a cadeia exata de imports mostrando por que um arquivo-fonte alterado afeta um teste específico.
- Argumentos:
  - project_root (string, obrigatório)
  - changed_file (string, obrigatório)
  - test_file (string, obrigatório)
generate_test_command

Constrói comandos CLI para runners de teste (vitest, jest ou playwright) correspondentes ao subconjunto de testes afetados.
- Argumentos:
  - project_root (string, obrigatório)
  - changed_files (string[], obrigatório)
  - runner (enum: jest, vitest, playwright, padrão: vitest)

2. Análise Profunda de Código Específica para TypeScript

differentiate_type_impact

Inspeciona imports e tipos para isolar mudanças somente de tipo (interfaces, types ou exports import type). Ajuda a pular a execução de testes completamente se as mudanças não impactarem o bundle em tempo de execução!
- Argumentos:
  - project_root (string, obrigatório)
  - changed_files (string[], obrigatório)
analyze_api_surface_mutation

Compara um arquivo contra sua versão HEAD e determina se ele modifica a API pública (breaking_api_change) ou contém apenas edições de implementação interna (internal_refactor).
- Argumentos:
  - project_root (string, obrigatório)
  - file_path (string, obrigatório)
generate_skeleton_view

Gera um esqueleto otimizado em tokens de um arquivo removendo corpos de funções e métodos, mantendo apenas assinaturas, JSDocs e números de linha.
- Argumentos:
  - project_root (string, obrigatório)
  - file_path (string, obrigatório)
  - include_jsdoc (boolean, padrão: true)
  - include_private_members (boolean, padrão: false)
get_symbol_dependency_graph

Rastreia dependências no nível de declarações (funções, classes, variáveis) entre arquivos, encontrando o uso de declarações internas.
- Argumentos:
  - project_root (string, obrigatório)
  - file_path (string, obrigatório)
  - symbol_name (string, opcional): Símbolo de export específico para mapear.
  - direction (enum: forward, reverse, bidirectional, padrão: bidirectional)

3. Saúde do Código e Insights do Grafo

identify_unreachable_modules

Encontra arquivos-fonte órfãos que têm zero imports de entrada (código morto seguro para podar). Respeita automaticamente pontos de entrada padrão.
- Argumentos:
  - project_root (string, obrigatório)
  - entry_points (string[], opcional): Pontos de entrada explícitos para excluir do aviso.
  - limit (number, padrão: 50)
detect_architectural_cycles

Localiza loops de dependência circular (ex.: A → B → C → A) que causam ordens imprevisíveis de inicialização de módulos.
- Argumentos:
  - project_root (string, obrigatório)
get_dependency_graph

Retorna imports/importadores diretos de um arquivo em formato JSON ou como um fluxograma visual Mermaid TD.
- Argumentos:
  - project_root (string, obrigatório)
  - file_path (string, obrigatório)
  - format (enum: json, mermaid, padrão: json)
get_coverage_gaps

Identifica arquivos com cobertura de import zero — aqueles que nunca são importados por nenhum arquivo de teste.
- Argumentos:
  - project_root (string, obrigatório)
  - source_dirs (string[], opcional)
  - limit (number, padrão: 50)
get_test_summary

Fornece uma visão de alto nível da taxa de cobertura de testes, cadeias de import mais profundas e módulos de alto risco mais importados.
- Argumentos:
  - project_root (string, obrigatório)
refresh_project

Invalida o cache de grafos de AST e dependências. Execute após trocar de branches ou puxar atualizações git remotas.
- Argumentos:
  - project_root (string, obrigatório)

🚀 Instalação e Configuração

1. Instalação Global

npm install -g ast-impact-mapper-mcp

2. Configurar Editor / Cliente de Agente

VS Code / Cursor

Adicione o seguinte ao seu .cursor/mcp.json ou .vscode/mcp.json:

{
  "mcpServers": {
    "ast-impact-mapper": {
      "command": "npx",
      "args": ["-y", "ast-impact-mapper-mcp"]
    }
  }
}

Claude Code CLI

claude mcp add ast-impact-mapper npx -- -y ast-impact-mapper-mcp

💬 Cenário de Exemplo

Imagine que você modifica um componente de página compartilhado: src/pages/login-page.ts.

Agente de IA executa get_rename_aware_diff: Ele detecta que apenas tests/auth.spec.ts importa o objeto de página transitivamente.
Agente de IA executa differentiate_type_impact: Ele vê que você apenas adicionou uma interface de definição de tipo, classificando-a como type_only_change -> ele pula a execução de testes completamente, economizando ciclos de desenvolvimento!
Agente de IA executa explain_impact: Se perguntado por que tests/auth.spec.ts depende dele, ele renderiza o caminho: tests/auth.spec.ts → src/fixtures/app.ts → src/pages/login-page.ts.

🔗 O Ecossistema

ast-impact-mapper-mcp responde: "Quais testes são afetados pelas minhas mudanças?" 🗺️
flakiness-graph-mcp responde: "Desses testes afetados, quais são historicamente instáveis?" 📊
Juntos, eles formam um loop de feedback perfeito para executar uma suíte de testes priorizada, resiliente e mínima.

🛠️ Desenvolvimento CLI

npm run build        # Compile TypeScript to dist/
npm run lint         # Run ESLint validation
npm run format       # Format files via Prettier
npm test             # Run unit tests via Vitest

ast-impact-mapper-mcp

Documentação