pull-request-split-advisor 3.1.2

package/dist/output/report.js

@@ -0,0 +1,726 @@
+/**
+ * report.ts — Generación de reportes HTML profesionales y exportación JSON del plan.
+ *
+ * Expone tres funciones públicas:
+ *
+ * - **`renderHtmlReport`**: genera el HTML completo del reporte como string.
+ *   Se puede usar en tests o para previsualizar sin escribir en disco.
+ *
+ * - **`writeHtmlReport`**: llama a `renderHtmlReport` y escribe el resultado
+ *   en el archivo indicado.
+ *
+ * - **`exportJson`**: serializa el plan de ramas a un archivo JSON estructurado
+ *   para consumo por otras herramientas (CI/CD, dashboards, etc.).
+ *
+ * ### Estructura del HTML
+ * El reporte sigue una arquitectura de componentes dentro de funciones:
+ * - `buildReportStyles()` — el bloque `<style>` completo (CSS custom properties + layout)
+ * - `buildScoreGaugeSvg(score)` — SVG de anillo circular para el score de una rama
+ * - `buildMetricsBreakdownTable(plan, config)` — tabla detallada de métricas con aporte ponderado
+ * - `buildFilesBarsRow(f, maxLines)` — fila de archivo con barras visuales de adiciones/eliminaciones
+ * - `buildCommitTimelineHtml(plan)` — línea de tiempo visual de commits de una rama
+ * - `buildPlanCardHtml(plan, config)` — el `<article>` de cada rama del plan
+ * - `buildTocHtml(plans)` — tabla de contenidos anclada con navegación
+ * - `renderHtmlReport(input)` — el documento HTML completo ensamblado
+ *
+ * ### Seguridad
+ * Todos los valores de usuario (nombres de rama, rutas de archivos, mensajes de commit)
+ * pasan por `esc()` antes de insertarse en el HTML para prevenir XSS.
+ */
+import { writeFileSync } from "node:fs";
+import { APP_REPORT_TITLE } from "../shared/constants.js";
+import { changeTypeLabel } from "../shared/utils.js";
+import { reportStyles } from "./report-styles.generated.js";
+/**
+ * Escapa caracteres HTML especiales (`&`, `<`, `>`) para prevenir XSS.
+ * Todos los valores de cadena provenientes del usuario o del análisis
+ * deben pasar por esta función antes de insertarse en el HTML.
+ *
+ * @param value - Texto a escapar.
+ */
+function esc(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+/**
+ * Devuelve la etiqueta de estado de un plan según su score.
+ *
+ * - ÓPTIMO   : score ≥ targetScore
+ * - ACEPTABLE: score ≥ warnThreshold y score < targetScore
+ * - RIESGO   : score < warnThreshold
+ *
+ * `warnThreshold` se calcula dinámicamente:
+ *   - targetScore >  4 → warnThreshold = 4.0
+ *   - targetScore ≤  4 → warnThreshold = max(0, targetScore − 1)
+ *
+ * Con el default (targetScore = 4): ACEPTABLE = [3.0, 4.0), RIESGO = < 3.0.
+ */
+function scoreLabel(score, targetScore) {
+    if (score >= targetScore)
+        return "ÓPTIMO";
+    const warnThreshold = targetScore > 4 ? 4 : Math.max(0, targetScore - 1);
+    if (score >= warnThreshold)
+        return "ACEPTABLE";
+    return "RIESGO";
+}
+/** Devuelve `"SIN ALERTAS"` si la razón es `"OK"`, `"CON ALERTAS"` en caso contrario. */
+function alertLabel(reason) {
+    return reason === "OK" ? "SIN ALERTAS" : "CON ALERTAS";
+}
+/**
+ * Genera un anillo SVG circular que representa visualmente el score de 0 a 5.
+ *
+ * @param score       - Score a representar (0–5).
+ * @param targetScore - Score objetivo usado para determinar el color del anillo.
+ */
+function buildScoreGaugeSvg(score, targetScore) {
+    const r = 36;
+    const circ = 2 * Math.PI * r;
+    const pct = Math.min(score / 5, 1);
+    const dash = (pct * circ).toFixed(1);
+    const gap = (circ - parseFloat(dash)).toFixed(1);
+    const warnThreshold = targetScore > 4 ? 4 : Math.max(0, targetScore - 1);
+    const color = score >= targetScore ? "#16a34a" : score >= warnThreshold ? "#d97706" : "#dc2626";
+    return `
+  <svg width="100" height="100" viewBox="0 0 100 100" class="gauge-svg" aria-label="Score ${score.toFixed(2)} de 5">
+    <circle cx="50" cy="50" r="${r}" fill="none" stroke="#e2e8f0" stroke-width="10"/>
+    <circle cx="50" cy="50" r="${r}" fill="none" stroke="${color}" stroke-width="10"
+      stroke-dasharray="${dash} ${gap}"
+      stroke-linecap="round" transform="rotate(-90 50 50)" style="transition:stroke-dasharray 0.6s ease"/>
+    <text x="50" y="46" text-anchor="middle" font-size="14" font-weight="800" fill="${color}">${score.toFixed(2)}</text>
+    <text x="50" y="60" text-anchor="middle" font-size="9" fill="#64748b">/ 5.00</text>
+  </svg>`;
+}
+/**
+ * Genera la tabla de desglose detallado de métricas para una rama.
+ * Muestra: código, nombre, valor medido, puntos, peso y aporte ponderado.
+ *
+ * @param plan   - Plan de rama con métricas y datos calculados.
+ * @param config - Configuración activa con definiciones de métricas.
+ */
+function buildMetricsBreakdownTable(plan, config) {
+    // Valores brutos posicionales (mismo orden que config.metrics).
+    // Convención: 0=commits, 1=arch/commit, 2=líneas/commit, 3=total líneas.
+    const displayValues = [
+        `${plan.commits} commits`,
+        `${plan.filesPerCommit} arch/commit`,
+        `${plan.linesPerCommit} líneas/commit`,
+        `${plan.lines} líneas`
+    ];
+    const metricRows = Object.entries(config.metrics).map(([code, def], i) => {
+        const pts = plan.metrics[code] ?? 0;
+        const w = def.weight;
+        const contribution = (pts * w).toFixed(3);
+        const ptsPct = Math.round((pts / 5) * 100);
+        const displayValue = displayValues[i] ?? "—";
+        const barColor = pts >= 4 ? "#16a34a" : pts >= 3 ? "#d97706" : "#dc2626";
+        const ptsClass = pts >= 4 ? "pts-good" : pts >= 3 ? "pts-warn" : "pts-bad";
+        return `<tr>
+      <td><code class="metric-code">${esc(code)}</code></td>
+      <td class="metric-label">${esc(def.label)}</td>
+      <td class="metric-value">${esc(displayValue)}</td>
+      <td>
+        <div class="pts-bar-wrap">
+          <div class="pts-bar" style="width:${ptsPct}%;background:${barColor}"></div>
+        </div>
+        <span class="${ptsClass}">${pts} / 5</span>
+      </td>
+      <td class="metric-weight">${(w * 100).toFixed(0)}%</td>
+      <td class="metric-contrib">${contribution}</td>
+    </tr>`;
+    });
+    return `<table class="metrics-table">
+    <thead>
+      <tr>
+        <th>Cód.</th>
+        <th>Métrica</th>
+        <th>Valor medido</th>
+        <th>Puntos</th>
+        <th>Peso</th>
+        <th>Aporte</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${metricRows.join("")}
+      <tr class="metrics-total-row">
+        <td colspan="5" style="text-align:right;font-weight:700;">Score total</td>
+        <td class="metric-total-value">${plan.score.toFixed(3)}</td>
+      </tr>
+    </tbody>
+  </table>`;
+}
+/**
+ * Genera una fila `<tr>` para la tabla de archivos con mini-barras visuales
+ * proporcionales al máximo de líneas del conjunto.
+ *
+ * @param f        - Estadísticas del archivo.
+ * @param maxLines - Valor máximo de líneas en el conjunto (para normalizar barras).
+ */
+function buildFilesBarsRow(f, maxLines) {
+    const typeStyles = {
+        A: "ct-added",
+        U: "ct-untracked",
+        M: "ct-modified",
+        D: "ct-deleted",
+        R: "ct-renamed"
+    };
+    const ctClass = typeStyles[f.changeType] ?? "ct-default";
+    const totalBar = maxLines > 0 ? Math.round((f.lines / maxLines) * 80) : 0;
+    const addPct = f.lines > 0 ? Math.round((f.additions / f.lines) * totalBar) : 0;
+    const delPct = totalBar - addPct;
+    return `<tr>
+    <td><span class="ct-badge ${ctClass}">${esc(changeTypeLabel(f.changeType))}</span></td>
+    <td class="file-path"><code>${esc(f.path)}</code></td>
+    <td class="num-cell">${f.lines}</td>
+    <td>
+      <div class="diff-bar">
+        <div class="diff-add" style="width:${addPct}px" title="+${f.additions}"></div>
+        <div class="diff-del" style="width:${delPct}px" title="-${f.deletions}"></div>
+      </div>
+      <span class="diff-labels"><span class="add-lbl">+${f.additions}</span> <span class="del-lbl">-${f.deletions}</span></span>
+    </td>
+    <td class="num-cell prio-${f.priority}">${f.priority}</td>
+  </tr>`;
+}
+/**
+ * Genera la línea de tiempo visual de commits de un plan de rama.
+ *
+ * @param plan - Plan de rama con el array `commitPlan`.
+ */
+function buildCommitTimelineHtml(plan) {
+    if (plan.commitPlan.length === 0) {
+        return `<p class="muted">Sin commits en este plan.</p>`;
+    }
+    const items = plan.commitPlan.map((c) => {
+        const typeClass = `ct-${esc(c.suggestedType)}`;
+        const fileList = c.files
+            .map((fp) => `<li><code>${esc(fp)}</code></li>`)
+            .join("");
+        return `<div class="timeline-item">
+      <div class="timeline-dot"></div>
+      <div class="timeline-body">
+        <div class="timeline-header">
+          <span class="commit-index">#${c.index}</span>
+          <span class="commit-type-badge ${typeClass}">${esc(c.suggestedType)}</span>
+          <code class="commit-msg">${esc(c.suggestedMessage)}</code>
+          <button class="copy-btn" data-copy="${esc(c.suggestedMessage)}" onclick="handleCopy(this)" title="Copiar mensaje de commit">📋</button>
+        </div>
+        <div class="timeline-meta">
+          <span>${c.files.length} archivos</span>
+          <span>${c.totalLines} líneas</span>
+          <span>scope: <strong>${esc(c.suggestedScope)}</strong></span>
+        </div>
+        <ul class="commit-files-list">${fileList}</ul>
+      </div>
+    </div>`;
+    });
+    return `<div class="timeline">${items.join("")}</div>`;
+}
+/**
+ * Genera el bloque de comandos git para implementar un plan de rama.
+ *
+ * @param plan - Plan de rama con nombre, commits y archivos.
+ */
+function buildGitCommandsHtml(plan) {
+    const lines = [];
+    if (!plan.isExistingBaseBranch) {
+        lines.push(`<span class="gc-comment"># Crear la rama</span>`, `<span class="gc-cmd">git</span> checkout -b <span class="gc-branch">${esc(plan.name)}</span>`, "");
+    }
+    for (let i = 0; i < plan.commitPlan.length; i++) {
+        const c = plan.commitPlan[i];
+        lines.push(`<span class="gc-comment"># Commit ${c.index} – ${esc(c.suggestedType)}</span>`);
+        if (c.files.length > 0) {
+            const fileList = c.files.map((f) => `<span class="gc-file">${esc(f)}</span>`).join(" ");
+            lines.push(`<span class="gc-cmd">git</span> add ${fileList}`);
+        }
+        lines.push(`<span class="gc-cmd">git</span> commit -m <span class="gc-msg">"${esc(c.suggestedMessage)}"</span>`);
+        if (i < plan.commitPlan.length - 1)
+            lines.push("");
+    }
+    return `<div class="git-commands-block"><pre>${lines.join("\n")}</pre></div>`;
+}
+/**
+ * Genera el HTML del `<article>` para una rama del plan.
+ * Incluye anillo de score, desglose de métricas, bloques y línea de tiempo de commits.
+ *
+ * @param plan   - Datos del plan de rama a renderizar.
+ * @param config - Configuración activa (necesaria para score objetivo y métricas).
+ * @param index  - Índice posicional (0-based) para el anchor de navegación.
+ */
+function buildPlanCardHtml(plan, config, index) {
+    const warnThreshold = config.targetScore > 4 ? 4 : Math.max(0, config.targetScore - 1);
+    const scoreClass = plan.score >= config.targetScore ? "green" : plan.score >= warnThreshold ? "yellow" : "red";
+    const alertClass = plan.reason === "OK" ? "green" : "yellow";
+    const label = scoreLabel(plan.score, config.targetScore);
+    // Resumen de tipos de commit para las pills del header
+    const typeCounts = {};
+    for (const c of plan.commitPlan) {
+        typeCounts[c.suggestedType] = (typeCounts[c.suggestedType] ?? 0) + 1;
+    }
+    const typePills = Object.entries(typeCounts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([t, n]) => `<span class="commit-type-pill ct-${esc(t)}">${esc(t)} ×${n}</span>`)
+        .join(" ");
+    return `
+  <article class="plan-card" id="branch-${index}">
+    <div class="plan-card-header plan-header-${scoreClass}">
+      <div class="plan-header-left">
+        <div class="plan-branch-icon">⎇</div>
+        <div>
+          <div class="plan-branch-name">
+            ${esc(plan.name)}
+            <button class="copy-btn" data-copy="${esc(plan.name)}" onclick="handleCopy(this)" title="Copiar nombre de rama">📋</button>
+          </div>
+          <div class="plan-branch-sub">
+            ${plan.isExistingBaseBranch ? '<span class="existing-badge">rama base actual</span>' : ""}
+            ${plan.files} archivos · ${plan.lines} líneas · ${plan.commits} commits
+          </div>
+          ${typePills ? `<div class="commit-type-pills">${typePills}</div>` : ""}
+        </div>
+      </div>
+      <div class="plan-header-right">
+        ${buildScoreGaugeSvg(plan.score, config.targetScore)}
+        <div class="plan-score-label score-label-${scoreClass}">${label}</div>
+      </div>
+    </div>
+
+    <div class="plan-card-body">
+      <div class="badges" style="margin-bottom:16px">
+        <span class="badge ${scoreClass}">${esc(label)}</span>
+        <span class="badge ${alertClass}">${esc(alertLabel(plan.reason))}</span>
+        ${plan.reason !== "OK" ? `<span class="badge orange">${esc(plan.reason)}</span>` : ""}
+      </div>
+
+      ${plan.recommendation ? `<div class="recommendation-box">
+        <span class="rec-icon">💡</span>
+        <span>${esc(plan.recommendation)}</span>
+      </div>` : ""}
+
+      <div class="kpi-row">
+        <div class="kpi"><div class="kpi-v">${plan.files}</div><div class="kpi-k">Archivos</div></div>
+        <div class="kpi"><div class="kpi-v">${plan.lines}</div><div class="kpi-k">Líneas totales</div></div>
+        <div class="kpi"><div class="kpi-v">${plan.commits}</div><div class="kpi-k">Commits sugeridos</div></div>
+        <div class="kpi"><div class="kpi-v">${plan.filesPerCommit}</div><div class="kpi-k">Arch / commit</div></div>
+        <div class="kpi"><div class="kpi-v">${plan.linesPerCommit}</div><div class="kpi-k">Líneas / commit</div></div>
+        <div class="kpi"><div class="kpi-v">${plan.blocks.length}</div><div class="kpi-k">Bloques</div></div>
+      </div>
+
+      ${plan.excludedCommitTypes?.length
+        ? `<div class="exclusion-note">⚠ Los promedios <strong>arch/commit (M1.4)</strong> y <strong>líneas/commit (M1.5)</strong> excluyen commits de tipo: <strong>${esc(plan.excludedCommitTypes.join(", "))}</strong>. Las métricas M1.3 (cantidad de commits) y M3.2 (líneas totales) consideran todos los commits.</div>`
+        : ""}
+
+      <h4 class="section-title">📊 Desglose de métricas</h4>
+      ${buildMetricsBreakdownTable(plan, config)}
+
+      <h4 class="section-title">🧱 Bloques de trabajo</h4>
+      <table>
+        <thead>
+          <tr>
+            <th>Bloque</th>
+            <th>Prioridad</th>
+            <th>Divisible</th>
+            <th>Líneas</th>
+            <th>Archivos</th>
+            <th>Dep. Score</th>
+            <th>Archivos del bloque</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${plan.blocks.map((block) => `
+          <tr>
+            <td><code class="block-id">${esc(block.id)}</code></td>
+            <td><span class="prio-dot prio-${block.priority}">${block.priority}</span></td>
+            <td>${block.divisible
+        ? '<span class="divisible-yes">✓ Sí</span>'
+        : '<span class="divisible-no">✗ No</span>'}</td>
+            <td class="num-cell">${block.lines}</td>
+            <td class="num-cell">${block.files.length}</td>
+            <td class="num-cell">${block.depScore}</td>
+            <td class="block-files">${block.files.map((fp) => `<code>${esc(fp)}</code>`).join(" ")}</td>
+          </tr>`).join("")}
+        </tbody>
+      </table>
+
+      <h4 class="section-title">🕐 Plan de commits</h4>
+      ${buildCommitTimelineHtml(plan)}
+
+      <h4 class="section-title">⚙️ Cómo implementar</h4>
+      ${buildGitCommandsHtml(plan)}
+
+      <div class="back-to-top">
+        <a href="#" class="back-link">↑ Volver al inicio</a>
+      </div>
+    </div>
+  </article>`;
+}
+/**
+ * Genera la tabla de contenidos de navegación anclada para las ramas del plan.
+ *
+ * @param plans        - Lista de planes de rama.
+ * @param targetScore  - Score objetivo para color del indicador.
+ */
+function buildTocHtml(plans, targetScore) {
+    if (plans.length === 0)
+        return "";
+    const items = plans.map((p, i) => {
+        const warnThreshold = targetScore > 4 ? 4 : Math.max(0, targetScore - 1);
+        const cls = p.score >= targetScore ? "toc-ok" : p.score >= warnThreshold ? "toc-warn" : "toc-bad";
+        const barKey = cls.replace("toc-", "");
+        const barPct = Math.round((p.score / 5) * 100);
+        return `<li>
+      <a href="#branch-${i}" class="toc-link ${cls}">
+        <span class="toc-score">${p.score.toFixed(2)}</span>
+        <div class="toc-bar-wrap"><div class="toc-bar toc-bar-${barKey}" style="width:${barPct}%"></div></div>
+        <span class="toc-name">${esc(p.name)}</span>
+        <span class="toc-commits">· ${p.commitPlan.length} commits</span>
+      </a>
+    </li>`;
+    });
+    return `<div class="toc-box">
+    <div class="toc-title">🗂 Ramas del plan</div>
+    <ul class="toc-list">${items.join("")}</ul>
+  </div>`;
+}
+/**
+ * Devuelve el CSS compilado del reporte HTML (sin etiqueta `<style>`).
+ * El CSS es generado a partir de `src/output/report.scss` en el paso `build:styles`.
+ * El llamador lo inserta dentro de `<style>...</style>` en `renderHtmlReport`.
+ */
+function buildReportStyles() {
+    return reportStyles;
+}
+/**
+ * Genera el reporte HTML completo como string.
+ *
+ * @param input - Todos los datos del análisis necesarios para el reporte.
+ * @returns     Documento HTML completo (UTF-8, lang="es").
+ */
+export function renderHtmlReport(input) {
+    const { currentBranch, baseBranch, config, fileStats, deps, blocks, plans } = input;
+    const totalFiles = fileStats.length;
+    const totalLines = fileStats.reduce((sum, f) => sum + f.lines, 0);
+    const totalAdditions = fileStats.reduce((sum, f) => sum + f.additions, 0);
+    const totalDeletions = fileStats.reduce((sum, f) => sum + f.deletions, 0);
+    const createdFiles = fileStats.filter((f) => f.changeType === "A" || f.changeType === "U").length;
+    const updatedFiles = fileStats.filter((f) => f.changeType === "M").length;
+    const deletedFiles = fileStats.filter((f) => f.changeType === "D").length;
+    const renamedFiles = fileStats.filter((f) => f.changeType === "R").length;
+    const largeFiles = fileStats.filter((f) => f.lines > config.largeFileThreshold).length;
+    const avgScore = plans.length > 0
+        ? plans.reduce((sum, p) => sum + p.score, 0) / plans.length
+        : 0;
+    const warnThreshold = config.targetScore > 4 ? 4 : Math.max(0, config.targetScore - 1);
+    const optimalPlans = plans.filter((p) => p.score >= config.targetScore).length;
+    const acceptablePlans = plans.filter((p) => p.score >= warnThreshold && p.score < config.targetScore).length;
+    const riskPlans = plans.filter((p) => p.score < warnThreshold).length;
+    const maxLinesForBar = fileStats.length > 0 ? Math.max(...fileStats.map((f) => f.lines)) : 1;
+    const timestamp = new Date().toLocaleString("es-PE", {
+        year: "numeric", month: "long", day: "numeric",
+        hour: "2-digit", minute: "2-digit"
+    });
+    return `<!doctype html>
+<html lang="es">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${APP_REPORT_TITLE}</title>
+  <style>${buildReportStyles()}</style>
+</head>
+<body>
+<div class="container">
+
+  <!-- ══ HERO ══════════════════════════════════════════════════════════ -->
+  <header class="hero">
+    <div class="hero-top">
+      <div class="hero-title-area">
+        <h1>🔍 Pull Request Split Advisor</h1>
+        <p>Análisis de cambios, bloques, dependencias heurísticas y plan sugerido de ramas y commits.</p>
+      </div>
+      <div class="hero-timestamp">📅 ${timestamp}</div>
+    </div>
+
+    <div class="hero-grid">
+      <div class="hero-item">
+        <div class="label">Rama analizada</div>
+        <div class="value">⎇ ${esc(currentBranch)}</div>
+      </div>
+      <div class="hero-item">
+        <div class="label">Rama base</div>
+        <div class="value">⎇ ${esc(baseBranch)}</div>
+      </div>
+      <div class="hero-item">
+        <div class="label">Score objetivo</div>
+        <div class="value">${config.targetScore} / 5.00</div>
+      </div>
+      <div class="hero-item">
+        <div class="label">Score promedio del plan</div>
+        <div class="value">${avgScore.toFixed(2)}</div>
+      </div>
+      <div class="hero-item">
+        <div class="label">Ramas ÓPTIMO</div>
+        <div class="value" style="color:#4ade80">${optimalPlans}</div>
+      </div>
+      <div class="hero-item">
+        <div class="label">Ramas ACEPTABLE</div>
+        <div class="value" style="color:#fbbf24">${acceptablePlans}</div>
+      </div>
+      <div class="hero-item">
+        <div class="label">Ramas RIESGO</div>
+        <div class="value" style="color:#f87171">${riskPlans}</div>
+      </div>
+      <div class="hero-item">
+        <div class="label">Archivos modificados</div>
+        <div class="value">${totalFiles}</div>
+      </div>
+    </div>
+  </header>
+  <!-- ══ AVISO DE RESPONSABILIDAD ═══════════════════════════════ -->
+  <section class="disclaimer-banner" role="alert" aria-label="Aviso de responsabilidad">
+    <div class="disclaimer-icon">⚠️</div>
+    <div class="disclaimer-body">
+      <strong>AVISO DE RESPONSABILIDAD</strong>
+      <p>
+        Esta herramienta genera un plan de distribución de cambios.
+        <strong>No ejecuta compilaciones ni suites de pruebas.</strong>
+        La verificación de la integridad del código es
+        <strong>responsabilidad exclusiva del equipo de desarrollo</strong>.
+      </p>
+      <ul>
+        <li>Confirme que el proyecto <strong>compile sin errores</strong> antes de implementar el plan.</li>
+        <li>Confirme que <strong>todas las pruebas finalicen correctamente</strong> antes de crear los PRs.</li>
+      </ul>
+      <p class="disclaimer-footer">
+        Pull Request Split Advisor no asume responsabilidad por ramas o PRs generados a partir de código defectuoso.
+      </p>
+    </div>
+  </section>
+  <!-- ══ RESUMEN DE CAMBIOS ══════════════════════════════════════════ -->
+  <section class="section">
+    <h2 class="section-heading">📁 Resumen de cambios</h2>
+    <div class="summary-grid">
+      <div class="stat-card blue">
+        <div class="label">Total de archivos</div>
+        <div class="value">${totalFiles}</div>
+        <div class="sub">${totalLines} líneas totales</div>
+      </div>
+      <div class="stat-card green">
+        <div class="label">Líneas agregadas</div>
+        <div class="value">+${totalAdditions}</div>
+      </div>
+      <div class="stat-card red">
+        <div class="label">Líneas eliminadas</div>
+        <div class="value">-${totalDeletions}</div>
+      </div>
+      <div class="stat-card green">
+        <div class="label">Archivos nuevos (A + U)</div>
+        <div class="value">${createdFiles}</div>
+      </div>
+      <div class="stat-card blue">
+        <div class="label">Archivos modificados</div>
+        <div class="value">${updatedFiles}</div>
+      </div>
+      <div class="stat-card red">
+        <div class="label">Archivos eliminados</div>
+        <div class="value">${deletedFiles}</div>
+      </div>
+      <div class="stat-card yellow">
+        <div class="label">Archivos renombrados</div>
+        <div class="value">${renamedFiles}</div>
+      </div>
+      <div class="stat-card yellow">
+        <div class="label">Archivos grandes (> ${config.largeFileThreshold} líneas)</div>
+        <div class="value">${largeFiles}</div>
+      </div>
+      <div class="stat-card purple">
+        <div class="label">Ramas sugeridas</div>
+        <div class="value">${plans.length}</div>
+      </div>
+      <div class="stat-card blue">
+        <div class="label">Ideal líneas por PR</div>
+        <div class="value">${config.idealLinesPerPR}</div>
+      </div>
+      <div class="stat-card blue">
+        <div class="label">Máx líneas / commit</div>
+        <div class="value">${config.maxLinesPerCommitIdeal}</div>
+      </div>
+      <div class="stat-card blue">
+        <div class="label">Máx commits / rama</div>
+        <div class="value">${config.maxCommitsPerBranchIdeal}</div>
+      </div>
+      ${(() => {
+        const pct = config.testCoveragePercent ?? 0;
+        const cls = pct >= 20 ? "green" : pct > 0 ? "yellow" : "red";
+        return `<div class="stat-card ${cls}">
+          <div class="label">Cobertura de tests</div>
+          <div class="value">${pct}%</div>
+          <div class="sub">${pct >= 20 ? "Buena cobertura" : pct > 0 ? "Cobertura parcial" : "Sin tests detectados"}</div>
+        </div>`;
+    })()}
+    </div>
+  </section>
+
+  <!-- ══ NAVEGACIÓN DEL PLAN ════════════════════════════════════════ -->
+  ${plans.length > 0 ? `<section class="section">
+    <h2 class="section-heading">🗺 Navegación del plan</h2>
+    ${buildTocHtml(plans, config.targetScore)}
+  </section>` : ""}
+
+  <!-- ══ DETALLE DE ARCHIVOS ════════════════════════════════════════ -->
+  <section class="section">
+    <h2 class="section-heading">📄 Detalle de archivos</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>Tipo</th>
+          <th>Archivo</th>
+          <th>Líneas</th>
+          <th>Cambios (+/-)</th>
+          <th>Prioridad</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${fileStats.map((f) => buildFilesBarsRow(f, maxLinesForBar)).join("")}
+      </tbody>
+    </table>
+  </section>
+
+  <!-- ══ DEPENDENCIAS HEURÍSTICAS ══════════════════════════════════ -->
+  <section class="section">
+    <h2 class="section-heading">🔗 Dependencias heurísticas</h2>
+    ${deps.length
+        ? `<table>
+          <thead>
+            <tr>
+              <th>Archivo origen</th>
+              <th style="width:40px"></th>
+              <th>Archivo dependencia</th>
+            </tr>
+          </thead>
+          <tbody>
+            ${deps.map((d) => `<tr>
+              <td><code>${esc(d.from)}</code></td>
+              <td class="dep-arrow" style="text-align:center">→</td>
+              <td><code>${esc(d.to)}</code></td>
+            </tr>`).join("")}
+          </tbody>
+        </table>`
+        : `<div class="card"><p class="muted" style="margin:0">No se detectaron dependencias heurísticas entre los archivos modificados.</p></div>`}
+  </section>
+
+  <!-- ══ BLOQUES DETECTADOS ════════════════════════════════════════ -->
+  <section class="section">
+    <h2 class="section-heading">🧱 Bloques detectados</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>Bloque</th>
+          <th>Prioridad</th>
+          <th>Divisible</th>
+          <th>Líneas</th>
+          <th>Archivos</th>
+          <th>Dep. Score</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${blocks.map((b) => `<tr>
+          <td><code class="block-id">${esc(b.id)}</code></td>
+          <td><span class="prio-dot prio-${b.priority}">${b.priority}</span></td>
+          <td>${b.divisible
+        ? '<span class="divisible-yes">✓ Sí</span>'
+        : '<span class="divisible-no">✗ No</span>'}</td>
+          <td class="num-cell">${b.lines}</td>
+          <td class="num-cell">${b.files.length}</td>
+          <td class="num-cell">${b.depScore}</td>
+        </tr>`).join("")}
+      </tbody>
+    </table>
+  </section>
+
+  <!-- ══ PLAN RECOMENDADO ══════════════════════════════════════════ -->
+  <section class="section">
+    <h2 class="section-heading">🚀 Plan recomendado</h2>
+
+    <div class="card" style="margin-bottom:24px">
+      <div class="summary-grid">
+        <div class="stat-card purple">
+          <div class="label">Ramas sugeridas</div>
+          <div class="value">${plans.length}</div>
+        </div>
+        <div class="stat-card blue">
+          <div class="label">Score promedio</div>
+          <div class="value">${avgScore.toFixed(2)}</div>
+        </div>
+        <div class="stat-card green">
+          <div class="label">Ramas ÓPTIMO (≥ ${config.targetScore})</div>
+          <div class="value">${optimalPlans}</div>
+        </div>
+        <div class="stat-card yellow">
+          <div class="label">Ramas ACEPTABLE (≥ ${warnThreshold.toFixed(1)})</div>
+          <div class="value">${acceptablePlans}</div>
+        </div>
+        <div class="stat-card red">
+          <div class="label">Ramas RIESGO (< ${warnThreshold.toFixed(1)})</div>
+          <div class="value">${riskPlans}</div>
+        </div>
+        <div class="stat-card yellow">
+          <div class="label">Ramas indivisibles</div>
+          <div class="value">${plans.filter((p) => p.reason.includes("indivisible")).length}</div>
+        </div>
+      </div>
+    </div>
+
+    ${plans.map((plan, i) => buildPlanCardHtml(plan, config, i)).join("")}
+  </section>
+
+  <!-- ══ FOOTER ════════════════════════════════════════════════════ -->
+  <footer class="footer">
+    <p>Generado por <strong>${APP_REPORT_TITLE}</strong> · ${timestamp}</p>
+    <p>Score objetivo: <strong>${config.targetScore}</strong> · Ramas analizadas: <strong>${plans.length}</strong> · Archivos: <strong>${totalFiles}</strong></p>
+  </footer>
+
+</div>
+<script>
+function handleCopy(btn) {
+  var text = btn.getAttribute('data-copy') || '';
+  if (!navigator.clipboard) return;
+  navigator.clipboard.writeText(text).then(function() {
+    var orig = btn.textContent;
+    btn.textContent = '✓';
+    setTimeout(function() { btn.textContent = orig; }, 1500);
+  });
+}
+</script>
+</body>
+</html>`;
+}
+/**
+ * Genera el reporte HTML y lo escribe en disco.
+ *
+ * @param filePath - Ruta de destino del archivo HTML.
+ * @param input    - Datos del análisis.
+ */
+export function writeHtmlReport(filePath, input) {
+    writeFileSync(filePath, renderHtmlReport(input), "utf8");
+}
+/**
+ * Genera el JSON serializado del plan.
+ * @param plans         - Lista de planes de rama.
+ * @param currentBranch - Nombre de la rama activa.
+ * @param baseBranch    - Nombre de la rama base.
+ * @param config        - Configuración activa (se incluye `targetScore` en el JSON).
+ */
+export function exportJson(plans, currentBranch, baseBranch, config) {
+    if (!config.exportJson)
+        return;
+    const payload = {
+        currentBranch,
+        baseBranch,
+        targetScore: config.targetScore,
+        branches: plans
+    };
+    writeFileSync(config.jsonOutputFile, JSON.stringify(payload, null, 2), "utf8");
+}