Pull Request Split Advisor

Descripción

pull-request-split-advisor examina los archivos modificados en la rama de trabajo respecto a la rama base, los agrupa en bloques semánticos mediante análisis heurístico de dependencias y calcula la distribución óptima en ramas y commits para maximizar la revisabilidad de cada Pull Request.

El resultado es un plan de PRs en cascada (stacked branches) con score de calidad por rama, nombres de rama y mensajes de commit convencionales, y un reporte HTML interactivo exportado automáticamente.

La herramienta puede también aplicar el plan directamente en el repositorio: crea las ramas, realiza los commits y opcionalmente publica en el remoto. Si algo falla, ejecuta un rollback automático.

Una capa de IA opcional (Groq o GitHub Copilot) enriquece los mensajes de commit, slugs de rama y puede rebalancear el plan para mayor cohesión semántica. Sin configuración, la herramienta funciona en modo heurístico puro.

Características principales

| Característica | Desde | |---|---| | Análisis heurístico de dependencias y agrupación semántica | v1.0.0 | | Score de calidad ponderado por rama (M1.3, M1.4, M1.5, M3.2) | v1.0.0 | | Reporte HTML interactivo (hero, resumen, plan de commits, comandos git) | v1.0.0 | | --apply: creación de ramas apiladas y commits con rollback automático | v2.0.0 | | Capa de IA — Groq (Llama 3.3 70B) y GitHub Copilot | v3.0.0 | | Suite de tests ampliada (Vitest, 269 tests, 28 suites) | v3.2.27 | | Subcomando score: score del estado actual sin dividir | v3.2.0 | | Clasificación de origen por archivo: REMOTO, LOCAL, WIP, NUEVO | v3.2.1 | | Todos los artefactos en .pr-split-advisor/ | v3.2.x | | Flags --yes (no interactivo) y --push (publicar tras apply) | v3.2.x | | Advertencia de integridad de cascada con estado completo de ramas hermanas | v3.2.4 | | cascadeBlocked en el JSON exportado para integraciones externas | v3.2.25 | | Endurecimiento de apply, score WIP, wizard/config e historial corrupto | v3.2.27 |

Instalación

# Instalación global (recomendado)
npm install -g pull-request-split-advisor

# Como dependencia de desarrollo
npm install --save-dev pull-request-split-advisor

Al instalar se genera automáticamente pr-split-advisor.config.json con todos los parámetros y sus valores por defecto. Si el archivo ya existe, no se sobreescribe.

El postinstall también intenta añadir a .gitignore tanto pr-split-advisor.config.json como la carpeta de artefactos configurada por defecto. Si luego cambias outputDir, añade manualmente esa nueva ruta a .gitignore.

Uso rápido

# Analizar cambios del working tree
pr-split-advisor

# Aplicar el plan directamente (sin prompt interactivo)
pr-split-advisor --apply

# Modo no interactivo — omite todos los prompts
pr-split-advisor --apply --yes

# Modo no interactivo + publicar ramas en el remoto automáticamente
pr-split-advisor --apply --yes --push

# Especificar rama base explícitamente
pr-split-advisor --base develop

# Score del estado actual sin dividir en PRs
pr-split-advisor score
pr-split-advisor score --base develop
pr-split-advisor score --explain

# Historial de análisis anteriores
pr-split-advisor --stats

# Ver explicación detallada del plan sugerido
pr-split-advisor --explain

# Configurar la capa de IA (wizard interactivo)
pr-split-advisor config

# Configurar IA sin wizard (útil en CI/CD)
pr-split-advisor config --provider groq --api-key gsk_xxx

Artefactos generados

Todos los artefactos se guardan en la carpeta .pr-split-advisor/ de la raíz del proyecto:

| Archivo | Descripción | |---|---| | pr-split-report.html | Reporte HTML con el plan de división | | pr-split-score.html | Reporte HTML del score actual sin dividir | | pr-split-plan.json | Plan exportado en JSON — incluye cascadeBlocked, metadata de contrato y explicación por rama | | .pr-split-history.json | Historial de scores entre análisis |

La instalación intenta agregar estas rutas al .gitignore automáticamente. Si personalizas outputDir después, actualiza .gitignore manualmente.

Si consumes el CLI desde otra herramienta, usa el contrato documentado en docs/INTEGRATIONS.md y no dependas del orden interno de métricas ni del HTML como fuente primaria de datos.

Clasificación de origen por archivo

Cada archivo analizado recibe una etiqueta según su posición en el árbol git:

| Badge | Significado | |---|---| | WIP | Modificación sin commitear — incluido en el plan y las métricas | | NUEVO | Archivo sin rastrear — incluido en el plan y las métricas | | LOCAL | Commiteado solo en local, no publicado — mostrado informativamente | | REMOTO | Publicado en el remoto — mostrado informativamente |

Solo los archivos WIP y NUEVO entran al plan de PRs y al cálculo de score.

En el subcomando score, la rama se modela como un único estado WIP. Si ya tienes commits locales adelantados respecto a la base, se muestran como contexto informativo, pero no alteran las métricas del score instantáneo.

Advertencia de integridad de cascada

Si la rama actual ya tiene commits adelantados respecto a la rama base (caso típico en stacked branches), la herramienta:

1. Genera el reporte HTML normalmente — el plan es informativo con la sección de advertencia de cascada y el estado completo de ramas hermanas numeradas
2. Deshabilita --apply — el JSON exportado incluye "cascadeBlocked": true para que integraciones externas (como la extensión VS Code) puedan detectarlo
3. Muestra el comando exacto para crear la siguiente rama desde el punto correcto de la cascada

Para volver a ejecutar --apply, crea una nueva rama desde el punto recomendado en el reporte.

Configuración

pr-split-advisor.config.json en la raíz del proyecto:

{
  "targetScore": 5,                 // Score mínimo aceptable (0–5)
  "baseBranch": "master",           // Rama base para el análisis
  "maxFilesPerCommit": 8,           // Máximo de archivos por commit
  "maxLinesPerCommitIdeal": 120,    // Líneas ideales por commit
  "idealLinesPerPR": 99,            // Líneas ideales por PR
  "largeFileThreshold": 400,        // Umbral de archivo grande (líneas)
  "mediumFileThreshold": 180,       // Umbral de archivo mediano (líneas)
  "maxCommitsPerBranchIdeal": 2,    // Commits ideales por rama
  "hardMaxCommitsPerBranch": 4,     // Límite absoluto de commits por rama
  "maxBranchSearchRange": 8,        // Iteraciones extras sobre el mínimo teórico de ramas
  "exportJson": true,               // Exportar a .pr-split-advisor/pr-split-plan.json
  "outputDir": ".pr-split-advisor", // Carpeta de artefactos generados
  "verbose": false,                 // Logs de diagnóstico

  // ── Capa de IA (opcional) ─────────────────────────────────────────────────
  "ai": {
    "enabled": false,
    "provider": "groq",               // "groq" | "copilot"
    "model": "llama-3.3-70b-versatile",
    "apiKey": "",                     // Solo para "groq"
    "features": {
      "commitMessages": true,         // Mejorar subjects de commit
      "branchDescriptions": true,     // Mejorar slugs de nombre de rama
      "planRebalance": false          // Redistribuir archivos (opt-in)
    },
    "timeoutMs": 15000,
    "maxTokens": 1024
  }
}

Capa de IA

Groq (free tier)

Obtén una API key gratuita en console.groq.com y configúrala con el wizard:

pr-split-advisor config
# o directamente:
pr-split-advisor config --provider groq --api-key gsk_xxx

GitHub Copilot

Usa el contexto de Visual Studio Code y la autenticación disponible de gh CLI — sin token manual adicional:

gh auth login   # si aún no tienes sesión activa

⚠️ El proveedor copilot solo funciona dentro de Visual Studio Code. Además, el wizard valida que gh auth token esté disponible. En terminal independiente o CI/CD, se desactiva automáticamente y la herramienta continúa en modo heurístico. Usa groq para pipelines.

Puntos de enriquecimiento

| Característica | Default | Descripción | |---|---|---| | commitMessages | ✅ activado | Subjects semánticos con imperative mood | | branchDescriptions | ✅ activado | Slugs de rama kebab-case orientados al negocio | | planRebalance | ❌ opt-in | Redistribución de archivos entre commits y ramas por cohesión semántica |

Si pr-split-advisor.config.json contiene JSON inválido, el comando config aborta y te pide corregirlo antes de continuar. No intenta sobrescribir archivos corruptos.

Métricas de calidad

| Código | Métrica | Peso default | |---|---|---| | M1.3 | Número de commits en el PR | 20% | | M1.4 | Promedio de archivos por commit | 25% | | M1.5 | Promedio de líneas por commit | 25% | | M3.2 | Total de líneas modificadas en el PR | 30% |

Score resultante en escala 1–5. Score ≥ 4 se considera óptimo para revisión.

Historial de versiones

| Versión | Cambios principales | |---|---| | 3.2.29 | Limpieza automática de dist antes de compilar para evitar publicar artefactos obsoletos en npm | | 3.2.28 | Patch release estable del hardening del CLI, documentación actualizada y publicación en npm | | 3.2.27 | Endurecimiento de --apply, score WIP más preciso, wizard/config con validación estricta, historial corrupto protegido y suite ampliada a 241 tests / 25 suites | | 3.2.25 | cascadeBlocked en JSON exportado para integraciones externas | | 3.2.24 | Advertencia de cascada solo en terminal (sin card ni tablas de estado) | | 3.2.23 | Eliminación de output de cascada del terminal — solo en HTML | | 3.2.22 | --apply habilitado incluso con cascada comprometida (revertido en 3.2.23) | | 3.2.20 | Flag --push para publicar ramas tras apply | | 3.2.19 | Flag --yes para modo totalmente no interactivo | | 3.2.10 | Pipeline de análisis opera exclusivamente sobre archivos WIP | | 3.2.8 | Estado completo de la cascada en terminal y HTML | | 3.2.4 | Detección de integridad de cascada y bloqueo de apply | | 3.2.3 | Métricas calculadas solo sobre archivos WIP | | 3.2.1 | Clasificación de origen por archivo (REMOTO / LOCAL / WIP / NUEVO) | | 3.2.0 | Subcomando score con reporte HTML independiente | | 3.1.0 | Suite inicial de tests (Vitest) | | 3.0.0 | Capa de IA multi-proveedor (Groq + Copilot) | | 2.0.0 | --apply con stacked branches y rollback automático |

Mantenimiento del release

Para releases del paquete desde este repositorio existen estos comandos:

npm run release:validate
npm run release:dry-run
npm run release:patch
npm run release:minor
npm run release:resume -- 3.2.33

• release:validate ejecuta la validación reusable del release: tests, build, verificación del tarball y smoke test real instalando el paquete en un proyecto temporal y corriendo score dentro de un repo git temporal.
• release:dry-run calcula el siguiente patch release, ejecuta release:validate y restaura package.json y package-lock.json sin publicar ni crear refs git.
• release:patch y release:minor validan working tree limpio, rama permitida, sincronización con origin, autenticación en npm, inexistencia previa de la versión objetivo y ejecutan npm publish antes de crear commit, tag y push.
• release:resume finaliza una versión que ya fue publicada en npm pero cuyo commit/tag/push quedó pendiente. Si tu copia local ya tiene package.json bumped, puedes ejecutarlo sin versión; si estás en una copia limpia o en CI, pásala explícitamente con npm run release:resume -- <version>.

Después de publicar, el script también verifica que el registry refleje la nueva versión y que dist-tags.latest apunte a ella. Si detecta desalineación temporal, aplica reintentos con backoff exponencial y luego intenta corregirla automáticamente con npm dist-tag add.

Puedes ajustar la tolerancia del chequeo de latest con estas variables de entorno:

RELEASE_LATEST_TAG_CHECK_ATTEMPTS=6
RELEASE_LATEST_TAG_CHECK_BASE_DELAY_MS=3000
RELEASE_LATEST_TAG_CHECK_BACKOFF_FACTOR=2

El workflow .github/workflows/ci-release-validation.yml ejecuta release:dry-run en CI sobre Ubuntu, macOS y Windows para validar el pipeline completo fuera del entorno local.

El workflow manual .github/workflows/publish-npm.yml también usa el mismo script de release del repositorio y acepta patch, minor o resume. Cuando usas resume, pide además la versión ya publicada que debe finalizar.

Requisitos

| Requisito | Versión mínima | |---|---| | Node.js | ≥ 18 | | Git | Cualquier versión moderna en PATH | | Repositorio | Con rama base accesible en el remoto |

Extensión VS Code

Usa PR Split Advisor directamente desde VS Code con el panel lateral integrado:

PR Split Advisor — VS Code Marketplace

Licencia

© 2026 Felix Junior Chacaliaza Gutierrez — [email protected]

Este software se distribuye bajo los términos de una licencia freeware:

• ✅ Uso personal, educativo e interno permitido de forma gratuita
• ❌ Modificación o creación de obras derivadas no permitida
• ❌ Redistribución o publicación no permitida
• ❌ Uso comercial o venta no permitidos

Para cualquier uso no contemplado, contacte al autor. Consulte LICENSE para los términos completos.