🔍 ImpactLens

Simulador Inteligente de Impacto para Código TypeScript y APIs Node.js.
Predice qué funciones, endpoints y módulos aguas arriba se verán afectados por un cambio de código o firma antes de hacer commit o merge.

---

⚡ Inicio Rápido (En 30 segundos)

No necesitas instalar nada previamente. Puedes ejecutarlo directamente con npx en cualquier proyecto TypeScript:

# 1. Indexar el proyecto (crea el mapa de llamadas local en milisegundos)
npx @pegasus35d/impactlens-cli init

# 2. Modifica una función o archivo en tu editor...

# 3. Descubre de inmediato qué se romperá aguas arriba
npx @pegasus35d/impactlens-cli diff

O si prefieres tener el comando impactlens disponible de forma permanente:

npm install -g @pegasus35d/impactlens-cli

---

📖 Guía de Uso Paso a Paso

💻 1. Uso Local Diario (Mientras programas)

1. Antes de empezar a programar: Ejecuta impactlens init en la raíz de tu proyecto para capturar el estado base.
2. Editas tu código: Modificas firmas, eliminas funciones o cambias parámetros.
3. Analizas el impacto: Ejecutas impactlens diff para ver la lista de llamadores (callers) y endpoints afectados.

---

🌿 2. Comparar Ramas de Git (Antes de hacer Merge)

Si estás en una rama de desarrollo y quieres saber qué romperá respecto a main o master:

# Ver en texto plano
impactlens diff --base main --head feature/mi-nueva-funcion

# Ver en formato Markdown
impactlens diff --base main --head feature/mi-nueva-funcion --format markdown

# Guardar el informe en un archivo
impactlens diff --base main --head feature/mi-nueva-funcion --output reporte.md

---

🤖 3. Automático en Pull Requests de GitHub

Para que ImpactLens comente automáticamente en cada Pull Request de tu equipo con un reporte colapsable y sin generar spam (actualiza el mismo comentario en cada nuevo push):

Crea el archivo .github/workflows/impactlens.yml en tu repositorio:

name: ImpactLens PR Analysis

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  impact-analysis:
    name: Predict Code Impact
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Necesario para diffs entre ramas

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Run ImpactLens
        uses: impactlens/action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          threshold: '0.3'

---

🛠️ Referencia de Comandos y Opciones

impactlens init

Indexa los archivos .ts / .js, extrae firmas y construye el grafo en .impactlens/index.sqlite.

Opción	Descripción	Defecto
--db <ruta>	Ubicación del archivo de base de datos SQLite	.impactlens/index.sqlite
--force	Fuerza la reindexación de todos los archivos ignorando la caché	false

impactlens diff

Calcula la onda expansiva del impacto hacia los llamadores aguas arriba.

Opción	Descripción	Defecto
--base <ref>	Rama o commit base (ej: main, master, HEAD~1)	index local
--head <ref>	Rama o commit con cambios (ej: feature/xyz, HEAD)	working tree
--format <tipo>	Formato de salida (text, markdown, json)	text
--threshold <num>	Umbral de confianza mínimo (0.0 a 1.0)	0.3
--output <archivo>	Guarda el reporte directamente en un archivo	Consola

---

🧪 Repositorio de Demostración

En la carpeta examples/demo-api encontrarás un proyecto Express de prueba con instrucciones para clonar, hacer cambios y probar el análisis en menos de 1 minuto.

---

📄 Licencia

MIT © pegasus35d