ast-impact-mapper-mcp

Utiliza el AST de TypeScript para determinar qué pruebas se ven afectadas por cambios en el código.

Documentación

🗺️ ast-impact-mapper-mcp ✨

"Deja de hervir el océano. Ejecuta solo las pruebas que realmente importan para tus cambios." 🐸

ast-impact-mapper-mcp es un servidor avanzado de Model Context Protocol (MCP) que analiza tu base de código TypeScript/JavaScript mediante análisis AST (ts-morph) y trazado de grafos de dependencias. Ayuda a agentes de IA (como Claude o Cursor) a apuntar solo a las pruebas relevantes, encontrar código muerto, identificar dependencias de importación circulares y rastrear mutaciones de API.

🧐 ¿Por qué grafos de importación?

Adivinar las pruebas afectadas basándose en la coincidencia de nombres de archivo (por ejemplo, auth.ts -> auth.test.ts) es muy inexacto. Ejecutar toda la suite de pruebas en cada cambio menor es extremadamente lento.

Los grafos de importación no mienten. Si un archivo de prueba importa transitivamente un archivo fuente modificado, debe ejecutarse. ast-impact-mapper-mcp construye un grafo de dependencias de archivos bidireccional y responde "¿qué pruebas debo ejecutar?" en milisegundos.

💡 Demostración rápida (Flujo e2e del mundo real)

Imagina que tu agente de IA modifica un helper compartido: src/utils/auth.ts. En lugar de ejecutar todas las pruebas a ciegas o adivinar por nombre, el agente usa este servidor MCP:

1. Identificar pruebas afectadas

El agente llama a get_affected_tests con el archivo modificado:

// 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 la conexión

Para entender por qué checkout.spec.ts depende de auth.ts, el agente llama a 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"
  ]
}

¡Ajá! El spec de checkout importa el user-fixture, que importa auth!

3. Comprobar el impacto en tiempo de ejecución

Si el cambio en auth.ts solo añadía una interfaz de TypeScript (cambio solo de tipos), llamar a differentiate_type_impact le dice al agente:

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

¡Éxito! Como es un cambio solo de tipos, el agente puede omitir la ejecución de pruebas por completo, ahorrando valiosos ciclos de CPU y tiempo.

4. Ejecutar pruebas mínimas

Si sí contiene cambios en tiempo de ejecución, el agente solicita el comando de ejecución:

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

🛠️ Referencia de herramientas MCP

Todas las herramientas están configuradas con esquemas consistentes y seguros de tipos (argumentos en snake_case).

1. Mapeo y trazado de impacto

get_affected_tests

Encuentra todos los archivos de prueba que importan transitivamente archivos fuente modificados.
- Argumentos:
  - project_root (string, obligatorio): Ruta absoluta al proyecto TypeScript.
  - changed_files (string[], opcional): Rutas de archivos modificados.
  - git_diff (string, opcional): Salida estándar sin procesar de git diff --name-only.
- Devuelve: Mapa detallado de archivos modificados, pruebas afectadas y totales.
get_affected_tests_by_branch

Compara automáticamente el estado actual contra una rama base usando git para encontrar pruebas afectadas.
- Argumentos:
  - project_root (string, obligatorio)
  - base_branch (string, predeterminado: "main"): Rama contra la que comparar.
get_rename_aware_diff

Análisis de impacto de rama altamente robusto que rastrea movimientos/renombrados de archivos (mediante git diff -M) e ignora cambios de formato/espacios en blanco.
- Argumentos:
  - project_root (string, obligatorio)
  - base_branch (string, predeterminado: "main")
  - similarity_threshold (number, predeterminado: 90): Umbral de similitud % para declarar un movimiento.
explain_impact

Traza y explica la cadena exacta de importaciones que muestra por qué un archivo fuente modificado afecta a una prueba específica.
- Argumentos:
  - project_root (string, obligatorio)
  - changed_file (string, obligatorio)
  - test_file (string, obligatorio)
generate_test_command

Construye comandos CLI para ejecutores de pruebas (vitest, jest o playwright) que coinciden con el subconjunto de pruebas afectadas.
- Argumentos:
  - project_root (string, obligatorio)
  - changed_files (string[], obligatorio)
  - runner (enum: jest, vitest, playwright, predeterminado: vitest)

2. Análisis profundo de código específico de TypeScript

differentiate_type_impact

Inspecciona importaciones y tipos para aislar cambios solo de tipos (interfaces, tipos o exportaciones import type). ¡Ayuda a omitir la ejecución de pruebas por completo si los cambios no afectan al bundle en tiempo de ejecución!
- Argumentos:
  - project_root (string, obligatorio)
  - changed_files (string[], obligatorio)
analyze_api_surface_mutation

Compara un archivo contra su versión HEAD y determina si modifica la API pública (breaking_api_change) o solo contiene ediciones de implementación interna (internal_refactor).
- Argumentos:
  - project_root (string, obligatorio)
  - file_path (string, obligatorio)
generate_skeleton_view

Genera un esqueleto optimizado en tokens de un archivo eliminando los cuerpos de funciones y métodos, conservando solo firmas, JSDocs y números de línea.
- Argumentos:
  - project_root (string, obligatorio)
  - file_path (string, obligatorio)
  - include_jsdoc (boolean, predeterminado: true)
  - include_private_members (boolean, predeterminado: false)
get_symbol_dependency_graph

Traza dependencias a nivel de declaración (funciones, clases, variables) entre archivos, encontrando el uso de declaraciones internas.
- Argumentos:
  - project_root (string, obligatorio)
  - file_path (string, obligatorio)
  - symbol_name (string, opcional): Símbolo de exportación específico a mapear.
  - direction (enum: forward, reverse, bidirectional, predeterminado: bidirectional)

3. Salud del código e información del grafo

identify_unreachable_modules

Encuentra archivos fuente huérfanos que tienen cero importaciones entrantes (código muerto seguro de podar). Respeta automáticamente los puntos de entrada estándar.
- Argumentos:
  - project_root (string, obligatorio)
  - entry_points (string[], opcional): Puntos de entrada explícitos a excluir de la advertencia.
  - limit (number, predeterminado: 50)
detect_architectural_cycles

Localiza bucles de dependencias circulares (por ejemplo, A → B → C → A) que causan órdenes de inicialización de módulos impredecibles.
- Argumentos:
  - project_root (string, obligatorio)
get_dependency_graph

Devuelve importaciones/importadores directos de un archivo en formato JSON o como un diagrama de flujo Mermaid TD visual.
- Argumentos:
  - project_root (string, obligatorio)
  - file_path (string, obligatorio)
  - format (enum: json, mermaid, predeterminado: json)
get_coverage_gaps

Identifica archivos con cobertura de importación cero: aquellos que nunca son importados por ningún archivo de prueba.
- Argumentos:
  - project_root (string, obligatorio)
  - source_dirs (string[], opcional)
  - limit (number, predeterminado: 50)
get_test_summary

Proporciona una vista de alto nivel de la tasa de cobertura de pruebas, las cadenas de importación más profundas y los módulos de alto riesgo más importados.
- Argumentos:
  - project_root (string, obligatorio)
refresh_project

Invalida la caché de grafos AST y de dependencias. Ejecuta esto después de cambiar de rama o de extraer actualizaciones remotas de git.
- Argumentos:
  - project_root (string, obligatorio)

🚀 Instalación y configuración

1. Instalación global

npm install -g ast-impact-mapper-mcp

2. Configurar editor / cliente de agente

VS Code / Cursor

Añade lo siguiente a tu .cursor/mcp.json o .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

💬 Escenario de ejemplo

Imagina que modificas un componente de página compartido: src/pages/login-page.ts.

El agente de IA ejecuta get_rename_aware_diff: Detecta que solo tests/auth.spec.ts importa el objeto de página transitivamente.
El agente de IA ejecuta differentiate_type_impact: Ve que solo añadiste una interfaz de definición de tipos, clasificándolo como type_only_change -> omite la ejecución de pruebas por completo, ¡ahorrando ciclos de desarrollo!
El agente de IA ejecuta explain_impact: Si se le pregunta por qué tests/auth.spec.ts depende de ello, renderiza la ruta: tests/auth.spec.ts → src/fixtures/app.ts → src/pages/login-page.ts.

🔗 El ecosistema

ast-impact-mapper-mcp responde: "¿Qué pruebas se ven afectadas por mis cambios?" 🗺️
flakiness-graph-mcp responde: "De esas pruebas afectadas, ¿cuáles son históricamente inestables?" 📊
Juntos forman un bucle de retroalimentación perfecto para ejecutar una suite de pruebas priorizada, resiliente y mínima.

🛠️ Desarrollo 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

Documentación