pull-request-split-advisor 3.1.2

package/dist/output/ui.js

@@ -0,0 +1,417 @@
+/**
+ * ui.ts — Capa de presentación en terminal.
+ *
+ * Exporta un objeto singleton `ui` con todos los métodos de salida al terminal.
+ * Centralizar la UI en un solo objeto tiene las siguientes ventajas:
+ * - Un único punto de configuración (colores, anchos, estilos).
+ * - Fácil de mockear en tests (sustituir `ui` completo).
+ * - Semántica clara: `ui.ok()` vs `ui.warn()` vs `ui.error()` expresan intención.
+ *
+ * ### Dependencias externas
+ * - **chalk** — colores y estilos ANSI en terminal
+ * - **cli-table3** — tablas con alineación y word-wrap
+ * - **boxen** — cajas con bordes redondeados para cards y headers
+ *
+ * ### Readline singleton
+ * El módulo mantiene una única instancia de `readline.Interface` compartida
+ * entre `confirm` y `prompt`. Reutilizar una instancia evita listeners colgados
+ * y saltos de línea inesperados al alternar preguntas en modo interactivo. La
+ * instancia se cierra explícitamente con `closeReadlineInterface()` al finalizar.
+ *
+ * ### Modo no interactivo
+ * Esta capa solo escribe a stdout/stderr; no toma decisiones de lógica de negocio.
+ */
+import chalk from "chalk";
+import Table from "cli-table3";
+import boxen from "boxen";
+import readline from "node:readline";
+import { stdin as input, stdout as output } from "node:process";
+// ---------------------------------------------------------------------------
+// Singleton de readline
+// ---------------------------------------------------------------------------
+/**
+ * Instancia compartida de readline.Interface.
+ * Reutilizar una sola instancia evita el riesgo de crear y cerrar múltiples
+ * interfaces en modo interactivo (un close/open por cada confirm/prompt),
+ * lo que puede dejar listeners colgados en stdin o saltos de línea inesperados.
+ */
+let _readline = null;
+function getReadlineInterface() {
+    if (!_readline) {
+        _readline = readline.createInterface({ input, output });
+        _readline.setMaxListeners(50);
+    }
+    return _readline;
+}
+/** Cierra la interfaz readline global. Llamar al terminar la sesión interactiva. */
+export function closeReadlineInterface() {
+    _readline?.close();
+    _readline = null;
+}
+// Garantizar que el handle de readline se cierra si el proceso termina abruptamente
+// (Ctrl+C, SIGHUP, etc.) para evitar fugas de recursos.
+process.once("exit", closeReadlineInterface);
+process.once("SIGINT", () => { closeReadlineInterface(); process.exit(130); });
+process.once("SIGHUP", () => { closeReadlineInterface(); process.exit(129); });
+/**
+ * Spinner minimal de texto para indicar operaciones en curso.
+ *
+ * No usa códigos de reemplazo de cursor (ANSI \r) para mantener compatibilidad
+ * con terminales de CI/CD que registran cada línea como un log separado.
+ * Cada llamada simplemente escribe una nueva línea.
+ */
+class Spinner {
+    active = false;
+    start(text) {
+        this.active = true;
+        process.stdout.write(chalk.cyanBright(`⏳ ${text}`) + "\n");
+    }
+    stop(text) {
+        if (!this.active)
+            return;
+        if (text) {
+            process.stdout.write(chalk.greenBright(`✔ ${text}`) + "\n");
+        }
+        this.active = false;
+    }
+    fail(text) {
+        process.stdout.write(chalk.redBright(`✖ ${text}`) + "\n");
+        this.active = false;
+    }
+}
+/**
+ * Aplica el color `tone` a una cadena usando chalk.
+ * Función utilitaria interna usada por `badge`, `score`, `dashboard` y otros.
+ */
+function colorize(value, tone) {
+    switch (tone) {
+        case "blue":
+            return chalk.blueBright(value);
+        case "green":
+            return chalk.greenBright(value);
+        case "yellow":
+            return chalk.yellowBright(value);
+        case "red":
+            return chalk.redBright(value);
+        case "cyan":
+            return chalk.cyanBright(value);
+        case "magenta":
+            return chalk.magentaBright(value);
+        case "white":
+        default:
+            return chalk.whiteBright(value);
+    }
+}
+/** Rellena `value` con espacios a la derecha hasta alcanzar `size` caracteres. Usado para alinear columnas clave-valor. */
+function padRight(value, size) {
+    if (value.length >= size)
+        return value;
+    return value + " ".repeat(size - value.length);
+}
+/**
+ * Trunca una cadena en el centro si supera `max` caracteres, insertando `...`.
+ * Preferible a truncar por la derecha para rutas de archivo: preserva tanto el
+ * inicio (directorio) como el final (nombre y extensión).
+ *
+ * @param value - Cadena a truncar.
+ * @param max   - Longitud máxima. Por defecto: 48.
+ */
+function truncateMiddle(value, max = 48) {
+    if (value.length <= max)
+        return value;
+    const left = Math.ceil((max - 3) / 2);
+    const right = Math.floor((max - 3) / 2);
+    return `${value.slice(0, left)}...${value.slice(value.length - right)}`;
+}
+/**
+ * Genera una etiqueta tipo «pastilla» con fondo de color para el terminal.
+ *
+ * @param label - Texto a mostrar dentro de la pastilla (se convierte a mayúsculas).
+ * @param tone  - Color del fondo. Por defecto: `"blue"`.
+ */
+function badge(label, tone = "blue") {
+    const content = ` ${label.toUpperCase()} `;
+    switch (tone) {
+        case "green":
+            return chalk.black.bgGreenBright(content);
+        case "yellow":
+            return chalk.black.bgYellowBright(content);
+        case "red":
+            return chalk.white.bgRedBright(content);
+        case "cyan":
+            return chalk.black.bgCyanBright(content);
+        case "magenta":
+            return chalk.white.bgMagentaBright(content);
+        case "white":
+            return chalk.black.bgWhiteBright(content);
+        case "blue":
+        default:
+            return chalk.white.bgBlueBright(content);
+    }
+}
+/**
+ * Determina el tono de color a usar para un score numérico.
+ *
+ * @param score       - Score a evaluar (0–5).
+ * @param targetScore - Score objetivo de la configuración activa. Si se omite, se
+ *                      usa 4.0 como umbral verde (valor por defecto de `targetScore`).
+ *
+ * - Verde   : score ≥ targetScore
+ * - Amarillo: score ≥ warnThreshold (targetScore > 4 → 4.0; else max(0, targetScore − 1))
+ * - Rojo    : score < warnThreshold
+ */
+function scoreColor(score, targetScore = 4.0) {
+    if (score >= targetScore)
+        return "green";
+    const warnThreshold = targetScore > 4 ? 4 : Math.max(0, targetScore - 1);
+    if (score >= warnThreshold)
+        return "yellow";
+    return "red";
+}
+/**
+ * Formatea un score numérico con su color semántico y 2 decimales.
+ *
+ * @param value       - Score a formatear (0–5).
+ * @param targetScore - Score objetivo para determinar el color verde. Por defecto: 4.0.
+ *                      Pasar `config.targetScore` para consistencia con el reporte HTML.
+ */
+function score(value, targetScore = 4.0) {
+    const fixed = value.toFixed(2);
+    return colorize(fixed, scoreColor(value, targetScore));
+}
+/**
+ * Imprime una cabecera de sección delimitada por líneas del `marker` repetido.
+ * Usado para separar visualmente las grandes secciones del reporte en terminal.
+ *
+ * @param title  - Título de la sección.
+ * @param marker - Carácter usado para dibujar la línea. Por defecto: `"="`.
+ */
+function section(title, marker = "=") {
+    const line = marker.repeat(Math.max(18, title.length + 6));
+    process.stdout.write("\n");
+    process.stdout.write(chalk.cyanBright(line) + "\n");
+    process.stdout.write(chalk.bold.whiteBright(`  ${title}`) + "\n");
+    process.stdout.write(chalk.cyanBright(line) + "\n");
+}
+/** Imprime una subseción con símbolo `•` para jerarquías dentro de una sección. */
+function subsection(title) {
+    process.stdout.write("\n");
+    process.stdout.write(chalk.bold.cyan(`• ${title}`) + "\n");
+}
+/**
+ * Imprime la cabecera principal del análisis en un box redondeado.
+ *
+ * @param title    - Título principal.
+ * @param subtitle - Subtítulo opcional.
+ * @param meta     - Pares [clave, valor] mostrados como tabla de metadatos.
+ */
+function header(title, subtitle, meta) {
+    const lines = [];
+    lines.push(chalk.bold.whiteBright(title));
+    if (subtitle) {
+        lines.push(chalk.cyanBright(subtitle));
+    }
+    if (meta?.length) {
+        lines.push("");
+        for (const [key, value] of meta) {
+            lines.push(`${chalk.gray(`${key}:`)} ${chalk.whiteBright(String(value))}`);
+        }
+    }
+    process.stdout.write(boxen(lines.join("\n"), {
+        padding: 1,
+        borderStyle: "round",
+        borderColor: "cyan",
+        width: 90
+    }) + "\n");
+}
+/** Imprime un mensaje informativo con prefijo ℹ en color cyan. */
+function info(message) {
+    process.stdout.write(chalk.cyanBright(`ℹ ${message}`) + "\n");
+}
+/** Imprime un mensaje de éxito con prefijo ✔ en color verde. */
+function ok(message) {
+    process.stdout.write(chalk.greenBright(`✔ ${message}`) + "\n");
+}
+/** Imprime una advertencia con prefijo ⚠ en color amarillo. */
+function warn(message) {
+    process.stdout.write(chalk.yellowBright(`⚠ ${message}`) + "\n");
+}
+/** Imprime un error con prefijo ✖ por **stderr** en color rojo. */
+function error(message) {
+    process.stderr.write(chalk.redBright(`✖ ${message}`) + "\n");
+}
+/** Imprime texto secundario en gris (comentarios, rutas largas, detalles no críticos). */
+function muted(message) {
+    process.stdout.write(chalk.gray(message) + "\n");
+}
+/** Imprime un par clave-valor alineado: la clave en gris con 26 caracteres de ancho, el valor en blanco brillante. */
+function kv(key, value) {
+    process.stdout.write(`${chalk.gray(`${padRight(key, 26)}:`)} ${chalk.whiteBright(String(value))}` + "\n");
+}
+/**
+ * Imprime una tabla formateada con `cli-table3`.
+ *
+ * @param headers - Cabeceras de columna.
+ * @param rows    - Filas de datos (valores se convierten a string automáticamente).
+ * @param compact - Si `true`, usa bordes transparentes para tablas densas.
+ */
+function table(headers, rows, compact = false) {
+    const t = new Table({
+        head: headers.map((h) => chalk.cyanBright(h)),
+        wordWrap: true,
+        style: {
+            head: [],
+            border: compact ? [] : ["gray"]
+        },
+        colAligns: headers.map(() => "left")
+    });
+    for (const row of rows) {
+        t.push(row.map((cell) => String(cell)));
+    }
+    process.stdout.write(t.toString() + "\n");
+}
+/**
+ * Imprime una lista de rutas de archivos con guión y truncado central.
+ *
+ * @param files - Rutas a listar.
+ * @param width - Longitud máxima de cada ruta. Por defecto: 80.
+ */
+function fileList(files, width = 80) {
+    for (const file of files) {
+        process.stdout.write(`  ${chalk.gray("-")} ${chalk.whiteBright(truncateMiddle(file, width))}` + "\n");
+    }
+}
+/**
+ * Imprime una tabla compacta de métricas con etiqueta y valor coloreado.
+ *
+ * @param items - Tripletas `[etiqueta, valor, tono]`. El tono es opcional (por defecto `"blue"`).
+ */
+function dashboard(items) {
+    const rows = items.map(([label, value, tone = "blue"]) => {
+        const renderedValue = colorize(String(value), tone);
+        return [chalk.gray(label), renderedValue];
+    });
+    table(["Métrica", "Valor"], rows, true);
+}
+/**
+ * Imprime una tarjeta con borde redondeado usando `boxen`.
+ *
+ * @param title  - Título en blanco brillante negrita.
+ * @param lines  - Contenido libre (strings ya formateados con chalk si se desea).
+ * @param tone   - Color del borde. Por defecto: `"blue"`.
+ * @param footer - Línea de pie en gris (opcional).
+ */
+function card(title, lines, tone = "blue", footer) {
+    const borderColor = tone === "green"
+        ? "green"
+        : tone === "yellow"
+            ? "yellow"
+            : tone === "red"
+                ? "red"
+                : tone === "magenta"
+                    ? "magenta"
+                    : tone === "cyan"
+                        ? "cyan"
+                        : "blue";
+    const content = [
+        chalk.bold.whiteBright(title),
+        "",
+        ...lines,
+        ...(footer ? ["", chalk.gray(footer)] : [])
+    ].join("\n");
+    process.stdout.write(boxen(content, {
+        padding: 1,
+        borderStyle: "round",
+        borderColor
+    }) + "\n");
+}
+/**
+ * Imprime una tarjeta de resumen con pares clave-valor coloreados.
+ * Usa `card` internamente con tono cyan.
+ *
+ * @param title - Título de la tarjeta.
+ * @param items - Tripletas `[etiqueta, valor, tono]`.
+ */
+function summaryCard(title, items) {
+    const lines = items.map(([label, value, tone = "blue"]) => {
+        return `${chalk.gray(`${label}:`)} ${colorize(String(value), tone)}`;
+    });
+    card(title, lines, "cyan");
+}
+/**
+ * Genera la representación visual de un bloque para tablas y listas.
+ * Distingue bloques grandes (`large::`) de bloques agrupados normales.
+ */
+function blockLabel(id) {
+    if (id.startsWith("large::")) {
+        return badge("large", "yellow") + " " + chalk.whiteBright(id.replace("large::", ""));
+    }
+    const parts = id.split("::");
+    if (parts.length === 2) {
+        return `${badge("block", "blue")} ${chalk.whiteBright(parts[0])} ${chalk.gray("::")} ${chalk.cyanBright(parts[1])}`;
+    }
+    return `${badge("block", "blue")} ${chalk.whiteBright(id)}`;
+}
+/** Imprime una línea horizontal de 100 guiones en gris para separar entradas dentro de una sección. */
+function divider() {
+    process.stdout.write(chalk.gray("─".repeat(100)) + "\n");
+}
+/**
+ * Muestra una pregunta de sí/no y espera respuesta del usuario.
+ *
+ * @param message - Texto de la pregunta (sin el `[y/N]` que se agrega automáticamente).
+ * @returns       `true` si el usuario responde `y` o `yes` (insensible a mayúsculas).
+ */
+async function confirm(message) {
+    const rl = getReadlineInterface();
+    return new Promise((resolve) => {
+        rl.question(`${chalk.yellowBright("?")} ${message} ${chalk.gray("[y/N]: ")}`, (answer) => {
+            const normalized = answer.trim().toLowerCase();
+            resolve(normalized === "y" || normalized === "yes");
+        });
+    });
+}
+/**
+ * Muestra un prompt de texto libre y espera la respuesta del usuario.
+ *
+ * Si el usuario no escribe nada y pulsa Enter, se devuelve `defaultValue`.
+ *
+ * @param message      - Texto del prompt.
+ * @param defaultValue - Valor a usar si el usuario no escribe nada. Por defecto: `""`.
+ */
+async function prompt(message, defaultValue = "") {
+    const rl = getReadlineInterface();
+    return new Promise((resolve) => {
+        const suffix = defaultValue ? chalk.gray(` [predeterminado: ${defaultValue}]`) : "";
+        rl.question(`${chalk.yellowBright("?")} ${message}${suffix}: `, (answer) => {
+            const value = answer.trim();
+            resolve(value || defaultValue);
+        });
+    });
+}
+export const ui = {
+    spinner: new Spinner(),
+    truncateMiddle,
+    header,
+    section,
+    subsection,
+    info,
+    ok,
+    warn,
+    error,
+    muted,
+    kv,
+    table,
+    fileList,
+    dashboard,
+    card,
+    summaryCard,
+    badge,
+    scoreColor,
+    score,
+    blockLabel,
+    divider,
+    confirm,
+    prompt,
+    closeReadlineInterface
+};

package/dist/shared/constants.js

@@ -0,0 +1,59 @@
+/**
+ * constants.ts — Constantes globales del proyecto.
+ *
+ * Centralizar los valores literales aquí permite cambiar un umbral o penalización
+ * desde un solo lugar, afectando todo el sistema.
+ *
+ * Las constantes `DIST_*` y `EVAL_*` son parámetros de ajuste heurístico.
+ * Si el algoritmo produce distribuciones subóptimas en un proyecto concreto,
+ * estos son los primeros valores a revisar.
+ */
+import { createRequire } from "node:module";
+const _require = createRequire(import.meta.url);
+const _pkg = _require("../../package.json");
+/** Nombre legible de la herramienta mostrado en cabeceras y reportes. */
+export const APP_NAME = "PR Split Advisor";
+/** Binario CLI tal como se registra en el campo `bin` de `package.json`. */
+export const APP_BIN = "pr-split-advisor";
+/** Versión sincronizada automáticamente con el campo "version" de package.json. */
+export const APP_VERSION = _pkg.version;
+/** Título que encabeza los reportes HTML. */
+export const APP_REPORT_TITLE = "PR Split Advisor — Reporte de Plan";
+// ---------------------------------------------------------------------------
+// Umbrales de evaluación de ramas (`evaluateBranch`)
+// ---------------------------------------------------------------------------
+/**
+ * Total de líneas a partir del cual se fuerzan mínimo 2 commits en una rama
+ * con más de un bloque.
+ */
+export const EVAL_MIN_COMMITS_LINE_THRESHOLD = 120;
+/**
+ * Total de líneas a partir del cual `evaluateBranch` marca la razón como
+ * "PR demasiado grande por total de líneas". Los planes con esta razón no
+ * se rechazan porque el tamaño grande puede ser inevitable.
+ */
+export const EVAL_MAX_PR_LINE_THRESHOLD = 1200;
+// ---------------------------------------------------------------------------
+// Penalizaciones para `distributeBlocks` (strategy.ts)
+// ---------------------------------------------------------------------------
+/** Penalización cuando los archivos proyectados superarían el límite por rama. */
+export const DIST_PENALTY_OVERFLOW_FILES = 1000;
+/** Penalización por colocar un bloque indivisible en una rama que ya tiene contenido. */
+export const DIST_PENALTY_INDIVISIBLE_NONEMPTY = 800;
+/** Bonificación por colocar un bloque indivisible en una rama vacía. */
+export const DIST_BONUS_INDIVISIBLE_EMPTY = 60;
+/** Divisor para la penalización proporcional al total de líneas proyectadas. */
+export const DIST_PENALTY_LINE_FACTOR = 10;
+/** Penalización por separar bloques con dependencia directa en ramas distintas. */
+export const DIST_PENALTY_SPLIT_DEPS = 600;
+/** Bonificación por colocar bloques con dependencia directa en la misma rama. */
+export const DIST_BONUS_COLOCATE_DEPS = 300;
+// ---------------------------------------------------------------------------
+// Nomenclatura de ramas
+// ---------------------------------------------------------------------------
+/**
+ * Longitud máxima recomendada para un nombre de rama git.
+ * GitHub acepta hasta 255 chars, pero muchas herramientas de CI/CD fallan
+ * con nombres de más de 80 caracteres.
+ */
+export const BRANCH_NAME_MAX_LENGTH = 80;

package/dist/shared/types.js

@@ -0,0 +1,7 @@
+/**
+ * types.ts — Definiciones de tipos y contratos compartidos en todo el proyecto.
+ *
+ * Jerarquía de datos (flujo de análisis):
+ *   Config → FileStat[] → DependencyEdge[] → Block[] → BranchPlan[] (+ CommitPlan[])
+ */
+export {};

package/dist/shared/utils.js

@@ -0,0 +1,73 @@
+/**
+ * utils.ts — Utilidades compartidas de bajo nivel.
+ *
+ * Funciones exportadas:
+ * - `isTrackedFile`          — consulta el Set pre-cargado de archivos tracked (O(1))
+ * - `resetTrackedFilesCache` — limpia la caché entre ejecuciones
+ * - `changeTypeLabel`        — etiqueta legible para los changeTypes de FileStat
+ * - `normalizePathValue`     — normaliza separadores de ruta (Windows/POSIX)
+ * - `fileExistsInRepoOrFs`   — detecta si un archivo existe en disco o en git
+ */
+import { existsSync } from "node:fs";
+import { normalize } from "node:path";
+import { shSafe } from "../git/git.js";
+/**
+ * Caché del conjunto de archivos bajo seguimiento git, construida una vez
+ * por análisis para evitar un subproceso `git ls-files` por cada archivo.
+ */
+let _trackedFilesCache = null;
+function getTrackedFilesSet() {
+    if (!_trackedFilesCache) {
+        _trackedFilesCache = new Set(shSafe("git ls-files")
+            .split("\n")
+            .map((s) => s.trim())
+            .filter(Boolean));
+    }
+    return _trackedFilesCache;
+}
+/**
+ * Limpia la caché interna del Set de archivos tracked.
+ * Útil en tests y en escenarios con múltiples análisis en el mismo proceso.
+ */
+export function resetTrackedFilesCache() {
+    _trackedFilesCache = null;
+}
+/**
+ * Devuelve `true` si el archivo está bajo seguimiento git.
+ * O(1) por llamada después del primer acceso que construye el Set.
+ *
+ * @param file - Ruta relativa al raíz del repositorio.
+ */
+export function isTrackedFile(file) {
+    return getTrackedFilesSet().has(file);
+}
+/**
+ * Devuelve una etiqueta legible para el tipo de cambio de un archivo git.
+ * Centraliza la lógica compartida entre `cli.ts` y `report.ts`.
+ */
+export function changeTypeLabel(changeType) {
+    switch (changeType) {
+        case "A": return "A + creado";
+        case "M": return "M ~ actualizado";
+        case "D": return "D - eliminado";
+        case "R": return "R > renombrado";
+        case "U": return "U ? nuevo local";
+        default: return changeType;
+    }
+}
+/**
+ * Normaliza una ruta de archivo para comparaciones consistentes
+ * en sistemas Windows (backslash) y POSIX (forward slash).
+ */
+export function normalizePathValue(p) {
+    return normalize(p).replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+ * Devuelve `true` si el archivo existe en el filesystem local O en el repositorio git.
+ * Detecta archivos eliminados que aún viven en el HEAD del repositorio.
+ */
+export function fileExistsInRepoOrFs(file) {
+    if (existsSync(file))
+        return true;
+    return getTrackedFilesSet().has(file);
+}

package/node_modules/@colors/colors/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Original Library
+  - Copyright (c) Marak Squires
+
+Additional Functionality
+ - Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
+ - Copyright (c) DABH (https://github.com/DABH)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.