pull-request-split-advisor 3.1.2

package/dist/ai/enricher.js

@@ -0,0 +1,290 @@
+/**
+ * enricher.ts — Enriquecimiento post-heurístico de planes con IA.
+ *
+ * Recibe los planes generados por el motor heurístico (`findBestPlan`) y los
+ * mejora in-place usando el proveedor de IA configurado (Groq, GitHub Models o GitHub Copilot).
+ *
+ * ### Puntos de enriquecimiento
+ * 1. **Mensajes de commit** (`features.commitMessages`):
+ *    Un request por rama con todos sus commits. El LLM devuelve subjects mejorados.
+ *
+ * 2. **Descripción de ramas** (`features.branchDescriptions`):
+ *    Un request por rama derivada (no la rama base existente).
+ *    El LLM devuelve un slug kebab-case mejorado para el nombre de rama.
+ *
+ * 3. **Rebalanceo del plan** (`features.planRebalance`):
+ *    Un único request con el plan completo (todas las ramas y commits).
+ *    El LLM propone mover archivos entre commits y ramas por cohesión semántica.
+ *    La respuesta pasa validación estricta: diff de archivos, commits vacíos y
+ *    reconstrucción completa del `commitPlan` con mensajes nuevos.
+ *
+ * ### Fallback silencioso
+ * Cualquier error individual (timeout, JSON inválido, error HTTP) es capturado.
+ * Se imprime un aviso y el elemento del plan conserva su valor heurístico original.
+ * El plan NUNCA queda en estado inconsistente por un fallo de la IA.
+ *
+ * ### Arquitectura
+ * ```
+ * findBestPlan()  [heurístico, síncrono]
+ *      ↓
+ * aiEnrichPlans() [IA, asíncrono, opcional — si isAiEnabled()]
+ *      ↓
+ * printPlans() / exportJson / writeHtmlReport
+ * ```
+ */
+import { isAiEnabled, callAI } from "./provider.js";
+import { buildCommitMessagesPrompt, buildBranchDescriptionPrompt, buildPlanRebalancePrompt, } from "./prompts.js";
+import { buildSuggestedMessage, buildCommitTitleParts } from "../core/commit-planner.js";
+import { buildDerivedBranchName } from "../git/branch-naming.js";
+import { ui } from "../output/ui.js";
+// ---------------------------------------------------------------------------
+// Helpers de parseo y validación
+// ---------------------------------------------------------------------------
+/** Normaliza un slug a kebab-case válido (a-z0-9-), máx. 50 chars. */
+function sanitizeSlug(raw) {
+    const slug = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/--+/g, "-")
+        .slice(0, 50)
+        .replace(/-+$/, "");
+    return slug.length >= 2 ? slug : null;
+}
+// ---------------------------------------------------------------------------
+// Enriquecimiento de mensajes de commit
+// ---------------------------------------------------------------------------
+async function enrichCommitMessages(plan, config) {
+    const messages = buildCommitMessagesPrompt(plan);
+    const response = await callAI(messages, config);
+    let parsed;
+    try {
+        parsed = JSON.parse(response.content);
+    }
+    catch {
+        return 0; // JSON inválido → conservar heurístico
+    }
+    if (!Array.isArray(parsed.commits))
+        return 0;
+    for (const aiCommit of parsed.commits) {
+        const commit = plan.commitPlan.find((c) => c.index === aiCommit.index);
+        if (!commit)
+            continue;
+        const type = typeof aiCommit.type === "string" && aiCommit.type.trim()
+            ? aiCommit.type.trim()
+            : commit.suggestedType;
+        const scope = typeof aiCommit.scope === "string" && aiCommit.scope.trim()
+            ? aiCommit.scope.trim()
+            : commit.suggestedScope;
+        const subject = typeof aiCommit.subject === "string" && aiCommit.subject.trim()
+            ? aiCommit.subject.trim().slice(0, 72)
+            : commit.suggestedSubject;
+        commit.suggestedType = type;
+        commit.suggestedScope = scope;
+        commit.suggestedSubject = subject;
+        commit.suggestedMessage = buildSuggestedMessage(type, scope, subject, commit.ticketCode);
+    }
+    return response.tokensUsed;
+}
+// ---------------------------------------------------------------------------
+// Enriquecimiento de descripción de rama
+// ---------------------------------------------------------------------------
+async function enrichBranchDescription(plan, config, currentBranch) {
+    // Extraer el slug actual del nombre de rama: type/TEAM-123-<slug>
+    const match = plan.name.match(/^[^/]+\/[A-Za-z]+-\d+-(.+)$/);
+    const currentSlug = match ? match[1] : "";
+    if (!currentSlug)
+        return 0;
+    const messages = buildBranchDescriptionPrompt(plan, currentSlug);
+    const response = await callAI(messages, config);
+    let parsed;
+    try {
+        parsed = JSON.parse(response.content);
+    }
+    catch {
+        return response.tokensUsed;
+    }
+    const rawSlug = typeof parsed.description === "string" ? parsed.description : "";
+    const slug = sanitizeSlug(rawSlug);
+    if (!slug || slug === currentSlug)
+        return response.tokensUsed;
+    const ctx = config.branchNamingContext;
+    if (!ctx)
+        return response.tokensUsed;
+    try {
+        const newName = buildDerivedBranchName(ctx, slug);
+        // No renombrar la rama activa (sería la rama base existente)
+        if (newName && newName !== currentBranch) {
+            plan.name = newName;
+        }
+    }
+    catch {
+        // buildDerivedBranchName puede rechazar slugs inválidos → conservar original
+    }
+    return response.tokensUsed;
+}
+// ---------------------------------------------------------------------------
+// Rebalanceo del plan
+// ---------------------------------------------------------------------------
+async function aiRebalancePlan(plans, config) {
+    const messages = buildPlanRebalancePrompt(plans);
+    const response = await callAI(messages, config);
+    let parsed;
+    try {
+        parsed = JSON.parse(response.content);
+    }
+    catch {
+        return response.tokensUsed;
+    }
+    if (!Array.isArray(parsed.branches))
+        return response.tokensUsed;
+    // Mapa global de archivo → líneas (calculado antes de mutar)
+    const fileLines = new Map();
+    for (const plan of plans) {
+        for (const commit of plan.commitPlan) {
+            const linesEach = commit.files.length > 0
+                ? Math.round(commit.totalLines / commit.files.length)
+                : 0;
+            for (const f of commit.files) {
+                if (!fileLines.has(f))
+                    fileLines.set(f, linesEach);
+            }
+        }
+    }
+    // ── Validación estricta ────────────────────────────────────────────────
+    const inputFiles = new Set(plans.flatMap((p) => p.commitPlan.flatMap((c) => c.files)));
+    if (parsed.branches.length !== plans.length)
+        return response.tokensUsed;
+    const seen = new Set();
+    for (const aiBranch of parsed.branches) {
+        if (aiBranch.branchIndex < 0 ||
+            aiBranch.branchIndex >= plans.length)
+            return response.tokensUsed;
+        for (const commit of aiBranch.commits ?? []) {
+            if (!Array.isArray(commit.files) || commit.files.length === 0)
+                return response.tokensUsed;
+            for (const f of commit.files) {
+                if (seen.has(f) || !inputFiles.has(f))
+                    return response.tokensUsed;
+                seen.add(f);
+            }
+        }
+    }
+    if (seen.size !== inputFiles.size)
+        return response.tokensUsed;
+    // ── Aplicar rebalanceo ─────────────────────────────────────────────────
+    const autoTicket = config.branchNamingContext
+        ? `${config.branchNamingContext.teamCode}-${config.branchNamingContext.storyNumber}`
+        : undefined;
+    for (const aiBranch of parsed.branches) {
+        const plan = plans[aiBranch.branchIndex];
+        if (!plan)
+            continue;
+        const newCommits = aiBranch.commits.map((ac, idx) => {
+            const parts = buildCommitTitleParts(ac.files);
+            const totalLines = ac.files.reduce((sum, f) => sum + (fileLines.get(f) ?? 0), 0);
+            return {
+                index: idx + 1,
+                files: ac.files,
+                totalLines,
+                suggestedType: parts.suggestedType,
+                suggestedScope: parts.suggestedScope,
+                suggestedSubject: parts.suggestedSubject,
+                ticketCode: autoTicket,
+                suggestedMessage: buildSuggestedMessage(parts.suggestedType, parts.suggestedScope, parts.suggestedSubject, autoTicket),
+            };
+        });
+        plan.commitPlan = newCommits;
+        plan.commits = newCommits.length;
+        plan.files = newCommits.reduce((s, c) => s + c.files.length, 0);
+        plan.lines = newCommits.reduce((s, c) => s + c.totalLines, 0);
+        plan.filesPerCommit = Number((plan.files / Math.max(plan.commits, 1)).toFixed(2));
+        plan.linesPerCommit = Number((plan.lines / Math.max(plan.commits, 1)).toFixed(2));
+    }
+    return response.tokensUsed;
+}
+// ---------------------------------------------------------------------------
+// Punto de entrada público
+// ---------------------------------------------------------------------------
+/**
+ * Enriquece los planes del análisis heurístico usando el proveedor de IA configurado.
+ *
+ * Los planes se mutan **in-place**. Si la IA no está configurada o falla,
+ * los planes quedan intactos (modo heurístico puro).
+ *
+ * @param plans         Planes generados por `findBestPlan()`.
+ * @param config        Configuración completa (incluye `config.ai`).
+ * @param currentBranch Nombre de la rama activa (no se renombra).
+ */
+export async function aiEnrichPlans(plans, config, currentBranch) {
+    if (!isAiEnabled(config))
+        return;
+    const features = config.ai.features;
+    const errors = [];
+    let totalTokens = 0;
+    ui.spinner.start("Enriqueciendo plan con IA...");
+    // ── Rebalanceo de archivos entre commits y ramas ───────────────────────
+    if (features.planRebalance) {
+        try {
+            totalTokens += await aiRebalancePlan(plans, config);
+            ui.spinner.stop();
+            ui.ok("IA rebalanceó la distribución de archivos entre commits y ramas.");
+            ui.spinner.start("Enriqueciendo plan con IA...");
+        }
+        catch (err) {
+            const msg = `plan-rebalance: ${err.message}`;
+            errors.push(msg);
+            ui.spinner.stop();
+            ui.warn(`IA falló en rebalanceo — se usará distribución heurística.\n  • ${msg}`);
+            ui.spinner.start("Enriqueciendo plan con IA...");
+        }
+    }
+    for (const plan of plans) {
+        // ── Mensajes de commit ─────────────────────────────────────────────────
+        if (features.commitMessages && plan.commitPlan.length > 0) {
+            try {
+                totalTokens += await enrichCommitMessages(plan, config);
+            }
+            catch (err) {
+                const msg = `commit-messages [${plan.name}]: ${err.message}`;
+                errors.push(msg);
+                ui.spinner.stop();
+                ui.warn(`IA falló — se usará resultado heurístico.\n  • ${msg}`);
+                ui.spinner.start("Enriqueciendo plan con IA...");
+            }
+        }
+        // ── Descripción de rama (solo ramas derivadas, no la base existente) ───
+        if (features.branchDescriptions && !plan.isExistingBaseBranch) {
+            try {
+                totalTokens += await enrichBranchDescription(plan, config, currentBranch);
+            }
+            catch (err) {
+                const msg = `branch-desc [${plan.name}]: ${err.message}`;
+                errors.push(msg);
+                ui.spinner.stop();
+                ui.warn(`IA falló — se usará resultado heurístico.\n  • ${msg}`);
+                ui.spinner.start("Enriqueciendo plan con IA...");
+            }
+        }
+    }
+    ui.spinner.stop("Enriquecimiento con IA completado.");
+    // Post-deduplicación: la IA puede asignar el mismo slug a varias ramas
+    // del mismo módulo, deshaciendo la deduplicación previa de strategy.ts.
+    // Aplicamos el mismo algoritmo: sufijo numérico -1, -2... para los duplicados.
+    const derivedAfterEnrich = plans.filter((p) => !p.isExistingBaseBranch);
+    const nameCount = new Map();
+    for (const p of derivedAfterEnrich) {
+        nameCount.set(p.name, (nameCount.get(p.name) ?? 0) + 1);
+    }
+    const nameIdx = new Map();
+    for (const plan of derivedAfterEnrich) {
+        if ((nameCount.get(plan.name) ?? 0) <= 1)
+            continue;
+        const n = nameIdx.get(plan.name) ?? 1;
+        nameIdx.set(plan.name, n + 1);
+        plan.name = `${plan.name}-${n}`;
+    }
+    if (config.verbose && totalTokens > 0) {
+        ui.muted(`[verbose] Tokens IA usados: ${totalTokens}`);
+    }
+}

package/dist/ai/prompts.js

@@ -0,0 +1,231 @@
+/**
+ * prompts.ts — Constructores de mensajes para las llamadas a la API de IA.
+ *
+ * Cada función devuelve un array de `AIMessage` listo para pasar a `callAI`.
+ * Los prompts exigen que el modelo responda estrictamente en JSON.
+ *
+ * ### Contratos de respuesta esperada
+ * | Función                       | JSON esperado                                                    |
+ * |-------------------------------|------------------------------------------------------------------|
+ * | buildCommitMessagesPrompt     | `{ "commits": [{ "index": 1, "type": "feat", "scope": "auth", "subject": "..." }] }` |
+ * | buildBranchDescriptionPrompt  | `{ "description": "kebab-case-slug" }`                          |
+ * | buildPlanRebalancePrompt      | `{ "branches": [{ "branchIndex": 0, "commits": [{ "commitIndex": 0, "files": ["..."] }] }] }` |
+ */
+// ---------------------------------------------------------------------------
+// Commit messages
+// ---------------------------------------------------------------------------
+/**
+ * Construye el prompt para mejorar los mensajes de commit de una rama.
+ *
+ * Envía todos los commits de la rama en un único request para minimizar
+ * el número de llamadas a la API.
+ */
+export function buildCommitMessagesPrompt(plan) {
+    const commitDescriptions = plan.commitPlan
+        .map((c) => {
+        const maxFiles = 30;
+        const shown = c.files.slice(0, maxFiles).join("\n    - ");
+        const overflow = c.files.length > maxFiles ? `\n    - (+${c.files.length - maxFiles} more files)` : "";
+        return [
+            `Commit ${c.index}:`,
+            `  Heuristic suggestion: ${c.suggestedType}(${c.suggestedScope}): ${c.suggestedSubject}`,
+            `  Changed files (${c.files.length}):`,
+            `    - ${shown}${overflow}`,
+            `  Lines changed: ~${c.totalLines} lines`,
+        ].join("\n");
+    })
+        .join("\n\n");
+    // Extraer módulos únicos del plan para dar contexto
+    const modules = [...new Set(plan.commitPlan.flatMap((c) => c.files.map((f) => f.split("/").slice(0, 2).join("/"))))].slice(0, 10).join(", ");
+    return [
+        {
+            role: "system",
+            content: [
+                "You are a senior software engineer expert at writing git conventional commit messages.",
+                "Analyze the changed files carefully — the file paths reveal the domain, layer, and intent.",
+                "Your job: rewrite the heuristic subject lines to be precise, developer-friendly, and actionable.",
+                "",
+                "STRICT RULES:",
+                "- Imperative mood ONLY: 'add', 'fix', 'update', 'implement', 'refactor', 'remove', 'expose', 'wire'...",
+                "  BAD: 'added login', 'fixes bug', 'updating config'",
+                "  GOOD: 'add login endpoint', 'fix null pointer in auth', 'update config schema'",
+                "- Maximum 72 characters per subject",
+                "- Use the heuristic type/scope as starting point; only change if clearly wrong",
+                "- Be SPECIFIC: mention the module, entity, or feature affected — not generic verbs alone",
+                "  BAD: 'update files', 'add code', 'fix stuff'",
+                "  GOOD: 'add user profile picture upload endpoint', 'fix token expiry in refresh flow'",
+                "- No trailing period",
+                "- Do NOT include the ticket code in the subject (it will be prepended automatically)",
+                "- Infer intent from file names: e.g. 'auth/jwt.ts' → JWT/auth changes, 'payments/stripe.ts' → Stripe integration",
+                "",
+                "FEW-SHOT EXAMPLES:",
+                "Files: src/auth/login.ts, src/auth/token.ts  →  feat(auth): implement JWT-based login and token refresh",
+                "Files: src/payments/stripe.ts, src/payments/webhook.ts  →  feat(payments): integrate Stripe payment and webhook handling",
+                "Files: src/users/profile.ts, src/users/avatar.ts  →  feat(users): add profile management and avatar upload",
+                "Files: tests/auth.spec.ts, tests/token.spec.ts  →  test(auth): add unit tests for login and token refresh",
+                "Files: docker-compose.yml, .env.example  →  chore(infra): update Docker compose and env template",
+                "",
+                "Return ONLY a valid JSON object — no markdown, no explanation, no extra text:",
+                '{"commits": [{"index": 1, "type": "feat", "scope": "auth", "subject": "implement JWT-based login and token refresh"}, ...]}',
+            ].join("\n"),
+        },
+        {
+            role: "user",
+            content: [
+                `Branch: ${plan.name}`,
+                `Main modules involved: ${modules || "(unknown)"}`,
+                `Total commits in this branch: ${plan.commitPlan.length}`,
+                "",
+                "Commits to improve:",
+                "",
+                commitDescriptions,
+                "",
+                "Remember: be specific about what each commit does based on its file paths. Avoid generic subjects.",
+            ].join("\n"),
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Branch description slug
+// ---------------------------------------------------------------------------
+/**
+ * Construye el prompt para mejorar el slug de descripción de una rama derivada.
+ */
+export function buildBranchDescriptionPrompt(plan, currentSlug) {
+    const allFiles = plan.commitPlan.flatMap((c) => c.files);
+    const shown = allFiles.slice(0, 40).map((f) => `  - ${f}`).join("\n");
+    const overflow = allFiles.length > 40 ? `\n  - (+${allFiles.length - 40} more files)` : "";
+    // Extraer módulos únicos dominantes para dar más contexto al LLM
+    const moduleFreq = new Map();
+    for (const f of allFiles) {
+        const mod = f.split("/").slice(0, 2).join("/");
+        moduleFreq.set(mod, (moduleFreq.get(mod) ?? 0) + 1);
+    }
+    const topModules = [...moduleFreq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([mod, count]) => `${mod} (${count} files)`)
+        .join(", ");
+    // Recopilar los mensajes de commits enriquecidos para dar más contexto
+    const commitSummary = plan.commitPlan
+        .map((c) => `  - ${c.suggestedMessage || c.suggestedSubject}`)
+        .join("\n");
+    return [
+        {
+            role: "system",
+            content: [
+                "You are a senior software engineer expert at naming git branches.",
+                "Your goal: generate a slug that PRECISELY describes WHAT this branch does, not WHERE the files are.",
+                "",
+                "STRICT RULES:",
+                "- kebab-case ONLY: lowercase letters (a-z), digits (0-9), and hyphens (-)",
+                "- Maximum 50 characters",
+                "- No leading or trailing hyphens, no consecutive hyphens",
+                "- Do NOT include the branch type (feature, fix, chore) or ticket number — they are added automatically",
+                "- Start with a verb or a clear domain noun: 'add-', 'implement-', 'refactor-', 'fix-', 'migrate-'",
+                "- Be SPECIFIC and MEANINGFUL: describe the business feature or technical change",
+                "  BAD: 'update-files', 'changes', 'update-code', 'update-experimental3', 'update-src'",
+                "  GOOD: 'add-stripe-payment-integration', 'refactor-auth-token-refresh', 'implement-user-profile-api'",
+                "- Prefer domain language over technical/folder names",
+                "  BAD: 'update-src-auth', 'update-payments-folder'",
+                "  GOOD: 'add-jwt-authentication', 'integrate-stripe-webhooks'",
+                "",
+                "FEW-SHOT EXAMPLES:",
+                "Modules: src/auth (8 files), Commits: add JWT login, add token refresh  →  add-jwt-auth-and-token-refresh",
+                "Modules: src/payments (5 files), Commits: integrate Stripe, add webhook  →  integrate-stripe-payments",
+                "Modules: src/users (4 files), Commits: add user profile, add avatar  →  add-user-profile-management",
+                "Modules: src/notifications (3 files), Commits: add email notifications  →  add-email-notifications",
+                "Modules: config (2 files), Commits: update Docker config, update env  →  update-infra-config",
+                "",
+                "Return ONLY a valid JSON object — no markdown, no explanation, no extra text:",
+                '{"description": "precise-feature-name-here"}',
+            ].join("\n"),
+        },
+        {
+            role: "user",
+            content: [
+                `Top modules by file count: ${topModules || "(unknown)"}`,
+                `Total files in this branch: ${allFiles.length}`,
+                "",
+                "Changed files:",
+                shown + overflow,
+                "",
+                "Commit messages in this branch:",
+                commitSummary,
+                "",
+                `Current heuristic slug (improve upon this): ${currentSlug}`,
+                "",
+                "Generate a slug that describes the BUSINESS PURPOSE or TECHNICAL CHANGE — not just the folder name.",
+            ].join("\n"),
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Plan rebalance
+// ---------------------------------------------------------------------------
+/**
+ * Construye el prompt para que la IA proponga un rebalanceo semántico del plan:
+ * movimientos de archivos entre commits y ramas basados en cohesión de dominio.
+ *
+ * El modelo recibe el plan heurístico completo (ramas → commits → archivos) y
+ * devuelve la distribución ideal. La respuesta incluye TODOS los archivos de
+ * TODAS las ramas, lo que permite reconciliar y detectar omisiones o duplicados.
+ *
+ * @param plans - Planes heurísticos ya generados por `findBestPlan`.
+ */
+export function buildPlanRebalancePrompt(plans) {
+    const planDescription = plans.map((plan, bi) => {
+        const commits = plan.commitPlan.map((c) => {
+            const files = c.files.map((f) => `        - ${f}`).join("\n");
+            return [`    Commit ${c.index} [${c.suggestedType}]:`, files].join("\n");
+        }).join("\n");
+        return [
+            `Branch ${bi} (${plan.isExistingBaseBranch ? "base existente" : "derivada"}): ${plan.name}`,
+            `  ${plan.files} archivos · ${plan.lines} líneas · ${plan.commits} commits`,
+            commits
+        ].join("\n");
+    }).join("\n\n");
+    const allFiles = plans.flatMap((p) => p.commitPlan.flatMap((c) => c.files));
+    const totalFiles = allFiles.length;
+    return [
+        {
+            role: "system",
+            content: [
+                "You are a senior software architect expert at organizing code changes into logical git commits and branches.",
+                "You will receive a heuristic plan of file distribution across branches and commits.",
+                "Your job: propose a SEMANTICALLY IMPROVED redistribution based on domain cohesion.",
+                "",
+                "CORE PRINCIPLES:",
+                "- Files that belong to the same feature/domain should go in the same commit",
+                "- Files that depend on each other (e.g. service + its DTO + its controller) should be in the same commit or at least the same branch",
+                "- Infrastructure/config changes (chore) should be isolated from feature changes",
+                "- Test files should ALWAYS stay with their source file (same commit)",
+                "- Migration files should go in their own commit, before the entity that uses them",
+                "- Do NOT create new branches — only redistribute files within the existing branch structure",
+                "- Every single file in the input MUST appear exactly once in the output",
+                "",
+                "CONSTRAINTS:",
+                "- Keep the same number of branches and same branch order (branchIndex 0, 1, 2...)",
+                "- You may merge or split commits within a branch — but keep commits reasonable in size",
+                "- An empty commit (no files) is NOT allowed — every commit must have at least 1 file",
+                "- Do not explode into too many single-file commits",
+                "",
+                "RESPONSE FORMAT — return ONLY valid JSON, no markdown, no explanation:",
+                '{"branches":[{"branchIndex":0,"commits":[{"commitIndex":1,"files":["src/example/file.ts"]}]}]}',
+                "",
+                `CRITICAL: your output must contain exactly ${totalFiles} files total — same as the input.`,
+            ].join("\n"),
+        },
+        {
+            role: "user",
+            content: [
+                `Current heuristic plan (${plans.length} branches, ${totalFiles} total files):`,
+                "",
+                planDescription,
+                "",
+                "Analyze domain relationships and propose an improved distribution.",
+                "Remember: same total files, same branch count, no empty commits.",
+            ].join("\n"),
+        },
+    ];
+}