pull-request-split-advisor 3.1.2

package/dist/core/strategy.js

@@ -0,0 +1,486 @@
+/**
+ * strategy.ts — Distribución de bloques en ramas y selección del plan óptimo.
+ *
+ * Este módulo implementa el corazón del algoritmo de división de PRs:
+ *
+ * ### Flujo principal (`findBestPlan`)
+ * ```
+ * 1. Calcular minBranches: mínimo teórico de ramas necesarias.
+ * 2. Para branchCount en [minBranches … minBranches + maxBranchSearchRange]:
+ *    a. distributeBlocks  → asignar bloques a ramas (greedy)
+ *    b. evaluateBranch    → calcular score y validez de cada rama
+ *    c. buildCommitPlan   → plan de commits de cada rama
+ *    d. Si todas las ramas son válidas → aceptar plan y salir (break)
+ * 3. Si ningún plan es válido → usar el fallback con minBranches
+ * 4. markExistingBaseBranch → nombrar ramas correctamente
+ * ```
+ *
+ * ### Algoritmo de distribución greedy (`distributeBlocks`)
+ * Ordena los bloques por prioridad y luego, para cada bloque, elige la rama
+ * con menor penalización acumulada. Las penalizaciones están definidas en
+ * `constants.ts` (`DIST_*`) y consideran: desbordamiento de líneas/archivos,
+ * bloques indivisibles en ramas ocupadas, y separación de dependencias.
+ *
+ * ### Nomenclatura de ramas (`markExistingBaseBranch`)
+ * La rama con mayor score (o más líneas en caso de empate) se marca como
+ * `isExistingBaseBranch: true` y toma el nombre de la rama activa.
+ * Las demás reciben nombres derivados por `buildDerivedBranchName` o el
+ * formato fallback `<rama>-split-<n>`.
+ */
+import { buildDerivedBranchName } from "../git/branch-naming.js";
+import { scorePullRequest } from "./scoring.js";
+import { buildCommitPlan } from "./commit-planner.js";
+import { EVAL_MIN_COMMITS_LINE_THRESHOLD, EVAL_MAX_PR_LINE_THRESHOLD, DIST_PENALTY_OVERFLOW_FILES, DIST_PENALTY_INDIVISIBLE_NONEMPTY, DIST_BONUS_INDIVISIBLE_EMPTY, DIST_PENALTY_LINE_FACTOR, DIST_PENALTY_SPLIT_DEPS, DIST_BONUS_COLOCATE_DEPS } from "../shared/constants.js";
+// ---------------------------------------------------------------------------
+// Tipos internos
+// ---------------------------------------------------------------------------
+/**
+ * Tipos de commit excluidos del cálculo de promedios de M1.4 (arch/commit) y
+ * M1.5 (líneas/commit). M1.3 y M3.2 siempre incluyen todos los tipos de commit.
+ */
+const EXCLUDED_FROM_AVERAGES = new Set(["chore", "style", "docs"]);
+// ---------------------------------------------------------------------------
+// Helper de totales de rama
+// ---------------------------------------------------------------------------
+/**
+ * Calcula el total de líneas y archivos de un conjunto de bloques.
+ * Usado tanto en `evaluateBranch` como en el bucle de penalizaciones de `distributeBlocks`.
+ */
+function branchTotals(blocks) {
+    return {
+        lines: blocks.reduce((sum, b) => sum + b.lines, 0),
+        files: blocks.reduce((sum, b) => sum + b.files.length, 0)
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-score con el plan de commits real
+// ---------------------------------------------------------------------------
+/**
+ * Re-calcula el score de una rama usando el plan de commits ya construido.
+ *
+ * Una vez que `buildCommitPlan` asigna tipos a cada commit, podemos aplicar la
+ * regla de exclusión: M1.4 y M1.5 se calculan solo sobre commits que NO sean
+ * `chore`, `style` ni `docs`. M1.3 y M3.2 usan todos los commits sin filtrar.
+ *
+ * Este re-score reemplaza el score estimado por `evaluateBranch`, que no conocía
+ * los tipos de commit en el momento de calcular archivos/commit y líneas/commit.
+ *
+ * @param base       - Evaluación inicial de la rama (para heredar `files`, `lines`, `commits`, `reason`).
+ * @param commitPlan - Plan de commits con tipos ya asignados.
+ * @param totalLines - Total de líneas de la rama (para M3.2).
+ * @param config     - Configuración activa.
+ */
+function rescoreWithPlan(base, commitPlan, totalLines, config) {
+    // M1.4 y M1.5: excluir commits de tipo chore, style y docs
+    const reviewable = commitPlan.filter((c) => !EXCLUDED_FROM_AVERAGES.has(c.suggestedType));
+    const reviewableCount = reviewable.length || 1; // evitar división por 0
+    // Tipos que realmente aparecen en el plan y son excluidos
+    const excluded = [...new Set(commitPlan
+            .filter((c) => EXCLUDED_FROM_AVERAGES.has(c.suggestedType))
+            .map((c) => c.suggestedType))];
+    const reviewableFiles = reviewable.reduce((sum, c) => sum + c.files.length, 0);
+    const reviewableLines = reviewable.reduce((sum, c) => sum + c.totalLines, 0);
+    const filesPerCommit = Number((reviewableFiles / reviewableCount).toFixed(2));
+    const linesPerCommit = Number((reviewableLines / reviewableCount).toFixed(2));
+    // M1.3 y M3.2: todos los commits sin filtrar
+    const scoring = scorePullRequest({
+        commitCount: commitPlan.length,
+        filesPerCommit,
+        avgLinesPerCommit: linesPerCommit,
+        totalLinesChanged: totalLines
+    }, config);
+    return {
+        ...base,
+        commits: commitPlan.length,
+        filesPerCommit,
+        linesPerCommit,
+        score: scoring.complexity,
+        metrics: Object.fromEntries(Object.keys(config.metrics).map((code) => [code, scoring.metrics[code]?.points ?? 0])),
+        recommendation: scoring.recommendation,
+        ...(excluded.length > 0 ? { excludedCommitTypes: excluded } : {})
+    };
+}
+// ---------------------------------------------------------------------------
+// Evaluación de una rama
+// ---------------------------------------------------------------------------
+/**
+ * Evalúa las métricas de calidad de una distribución de bloques para una rama.
+ *
+ * Calcula el número de commits necesarios aplicando la lógica:
+ * - Máximo entre `ceil(archivos / maxFilesPerCommit)` y `ceil(líneas / maxLinesPerCommitIdeal)`.
+ * - Si solo hay un bloque grande indivisible, fuerza 1 commit (no tiene sentido dividirlo).
+ * - Si la rama tiene más de un bloque o supera el umbral de líneas, mínimo 2 commits.
+ *
+ * Luego llama a `scorePullRequest` con los valores calculados y determina la razón
+ * del estado: `"OK"`, bloque grande, PR grande, o exceso de commits.
+ *
+ * @param blocks - Bloques asignados a esta rama.
+ * @param config - Configuración activa.
+ */
+function evaluateBranch(blocks, config) {
+    const totals = branchTotals(blocks);
+    // Usar reduce en lugar de Math.max(...spread) para evitar RangeError
+    // si el array de bloques tiene cientos o miles de elementos.
+    const maxBlockLines = blocks.reduce((max, b) => (b.lines > max ? b.lines : max), 0);
+    // Garantizar mínimo 1 commit para evitar división por cero en el cálculo de
+    // promedios: puede ocurrir cuando todos los archivos de la rama son
+    // eliminaciones (changeType D) cuyo lineCount es 0.
+    let commits = Math.max(1, Math.ceil(totals.files / config.maxFilesPerCommit), Math.ceil(totals.lines / config.maxLinesPerCommitIdeal));
+    if (commits < 2 && (blocks.length > 1 || totals.lines > EVAL_MIN_COMMITS_LINE_THRESHOLD)) {
+        commits = 2;
+    }
+    const largeIndivisibleBlocks = blocks.filter((b) => !b.divisible);
+    if (largeIndivisibleBlocks.length === 1 &&
+        blocks.length === 1 &&
+        maxBlockLines > config.largeFileThreshold) {
+        commits = 1;
+    }
+    const filesPerCommit = Number((totals.files / commits).toFixed(2));
+    const linesPerCommit = Number((totals.lines / commits).toFixed(2));
+    const scoring = scorePullRequest({
+        commitCount: commits,
+        filesPerCommit,
+        avgLinesPerCommit: linesPerCommit,
+        totalLinesChanged: totals.lines
+    }, config);
+    // Las condiciones se asignan en orden ascendente de prioridad: la última que
+    // aplique sobreescribe a las anteriores. "Contiene bloque grande indivisible"
+    // y "PR demasiado grande" son las razones exentas en findBestPlan y deben
+    // tener mayor prioridad que "Requiere más commits" para evitar rechazar planes
+    // que no pueden subdividirse más.
+    let reason = "OK";
+    if (commits > config.maxCommitsPerBranchIdeal)
+        reason = "Requiere más commits de lo ideal";
+    if (totals.lines > EVAL_MAX_PR_LINE_THRESHOLD)
+        reason = "PR demasiado grande por total de líneas";
+    if (maxBlockLines > config.largeFileThreshold)
+        reason = "Contiene bloque grande indivisible";
+    return {
+        files: totals.files,
+        lines: totals.lines,
+        commits,
+        filesPerCommit,
+        linesPerCommit,
+        score: scoring.complexity,
+        metrics: Object.fromEntries(Object.keys(config.metrics).map((code) => [code, scoring.metrics[code]?.points ?? 0])),
+        recommendation: scoring.recommendation,
+        reason
+    };
+}
+// ---------------------------------------------------------------------------
+// Block distribution
+// ---------------------------------------------------------------------------
+/**
+ * Distribuye un array de bloques en exactamente `branchCount` grupos (ramas).
+ *
+ * Usa una heurística greedy: asigna cada bloque a la rama con menor carga
+ * acumulada (líneas), penalizando la separación de bloques que comparten
+ * aristas de dependencia y premiando agruparlos juntos.
+ *
+ * @param blocks      - Bloques a distribuir.
+ * @param branchCount - Número exacto de ramas destino.
+ * @param config      - Configuración activa del proyecto.
+ * @param deps        - Aristas de dependencia entre archivos.
+ * @returns           Array de arrays de bloques, uno por rama.
+ */
+export function distributeBlocks(blocks, branchCount, config, deps = []) {
+    const branches = Array.from({ length: branchCount }, () => []);
+    const fileToBranchIndex = new Map();
+    // Pre-computar mapa de adyacencia de dependencias: O(D) una sola vez.
+    // Evita el bucle O(F×D) que antes se ejecutaba por cada bloque×rama.
+    const fileNeighbors = new Map();
+    for (const { from, to } of deps) {
+        if (!fileNeighbors.has(from))
+            fileNeighbors.set(from, []);
+        if (!fileNeighbors.has(to))
+            fileNeighbors.set(to, []);
+        fileNeighbors.get(from).push(to);
+        fileNeighbors.get(to).push(from);
+    }
+    // Totales incrementales por rama: evita re-iterar todos los bloques en
+    // cada asignación (branchTotals recorría la rama entera en cada iteración).
+    const runningTotals = Array.from({ length: branchCount }, () => ({ lines: 0, files: 0 }));
+    const ordered = [...blocks].sort((a, b) => {
+        if (a.priority !== b.priority)
+            return a.priority - b.priority;
+        if (a.depScore !== b.depScore)
+            return b.depScore - a.depScore;
+        if (a.divisible !== b.divisible)
+            return a.divisible ? 1 : -1;
+        return b.lines - a.lines;
+    });
+    for (const block of ordered) {
+        let bestIndex = 0;
+        let bestPenalty = Number.MAX_SAFE_INTEGER;
+        for (let i = 0; i < branches.length; i++) {
+            const totals = runningTotals[i];
+            const projectedLines = totals.lines + block.lines;
+            const projectedFiles = totals.files + block.files.length;
+            let penalty = 0;
+            if (projectedLines > config.idealLinesPerPR) {
+                penalty += projectedLines - config.idealLinesPerPR;
+            }
+            if (projectedFiles > config.maxFilesPerCommit * config.maxCommitsPerBranchIdeal) {
+                penalty += DIST_PENALTY_OVERFLOW_FILES;
+            }
+            if (!block.divisible && totals.lines > 0)
+                penalty += DIST_PENALTY_INDIVISIBLE_NONEMPTY;
+            if (!block.divisible && totals.lines === 0)
+                penalty -= DIST_BONUS_INDIVISIBLE_EMPTY;
+            penalty += Math.floor(projectedLines / DIST_PENALTY_LINE_FACTOR);
+            // Penalizar separar bloques con dependencias directas entre sí.
+            // Con el mapa de adyacencia pre-computado el coste es O(F) en lugar de O(F×D).
+            for (const file of block.files) {
+                for (const neighbor of (fileNeighbors.get(file) ?? [])) {
+                    const relatedBranch = fileToBranchIndex.get(neighbor);
+                    if (relatedBranch === undefined)
+                        continue;
+                    if (relatedBranch !== i) {
+                        penalty += DIST_PENALTY_SPLIT_DEPS;
+                    }
+                    else {
+                        penalty -= DIST_BONUS_COLOCATE_DEPS;
+                    }
+                }
+            }
+            if (penalty < bestPenalty) {
+                bestPenalty = penalty;
+                bestIndex = i;
+            }
+        }
+        branches[bestIndex].push(block);
+        runningTotals[bestIndex].lines += block.lines;
+        runningTotals[bestIndex].files += block.files.length;
+        for (const file of block.files) {
+            fileToBranchIndex.set(file, bestIndex);
+        }
+    }
+    return branches;
+}
+// ---------------------------------------------------------------------------
+// Branch naming
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Detección de descripción de rama y nomenclatura
+// ---------------------------------------------------------------------------
+/**
+ * Deriva una descripción genérica en inglés para la rama basada en los patrones
+ * de ruta de los archivos. Heurística por capas (en orden de prioridad):
+ *
+ * 1. Todos los archivos son tests    → `"update-related-tests"`
+ * 2. Todos son documentación         → `"update-documentation"`
+ * 3. Todos son archivos de config    → `"update-configuration"`
+ * 4. Todos son tipos/interfaces      → `"align-shared-types"`
+ * 5. Directorio padre más frecuente (excluyendo genéricos) → `"update-<dir>-layer"`
+ * 6. Fallback                        → `"update-related-files-<índice>"`
+ *
+ * La detección se realiza en un único recorrido que evalúa todas las categorías
+ * y acumula el conteo de directorios simultáneamente, en lugar de múltiples
+ * pasadas `.every()` separadas.
+ *
+ * @param blocks        - Bloques de la rama cuyas rutas se analizan.
+ * @param fallbackIndex - Número de rama usado solo en el fallback genérico.
+ */
+function detectBranchDescription(blocks, fallbackIndex) {
+    const files = blocks.flatMap((b) => b.files).map((f) => f.toLowerCase());
+    if (files.length === 0)
+        return `update-related-files-${fallbackIndex}`;
+    // Un único recorrido para las 4 categorías y el conteo de directorios,
+    // en lugar de cuatro llamadas .every() separadas que re-escaneaban el array.
+    const reTest = /(^|\/)(__tests__|tests?|specs?)(\/|$)|(\.spec\.|\.test\.)/;
+    // Anclar readme, changelog y license para que no hagan match como substrings.
+    // Añadir .adoc y .rst para consistencia con file-stats.ts y commit-planner.ts.
+    const reDocs = /(^|\/)(docs?)(\/|$)|(^|\/)readme(\.[^/]*)?$|(^|\/)changelog(\.[^/]*)?$|(^|\/)license(\.[^/]*)?$|\.md$|\.adoc$|\.rst$/;
+    const reConfig = /(config|configs|configuration|settings|env)(\/|$|\.)/;
+    const reYaml = /\.(ya?ml|toml)$/;
+    const reTypes = /(type|types|interface|interfaces|schema|schemas|dto|dtos|model|models)(\/|$|\.)/;
+    let allTests = true, allDocs = true, allConfig = true, allTypes = true;
+    const dirCounts = new Map();
+    for (const f of files) {
+        if (allTests && !reTest.test(f))
+            allTests = false;
+        if (allDocs && !reDocs.test(f))
+            allDocs = false;
+        if (allConfig && !reConfig.test(f) && !reYaml.test(f))
+            allConfig = false;
+        if (allTypes && !reTypes.test(f))
+            allTypes = false;
+        const parts = f.split("/");
+        if (parts.length >= 2) {
+            const dir = parts[parts.length - 2];
+            if (dir)
+                dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
+        }
+    }
+    if (allTests)
+        return "update-related-tests";
+    if (allDocs)
+        return "update-documentation";
+    if (allConfig)
+        return "update-configuration";
+    if (allTypes)
+        return "align-shared-types";
+    // Directorio padre más frecuente, ignorando carpetas genéricas
+    const genericDirs = new Set(["src", "lib", "app", ".", ""]);
+    let topDir = "", topCount = 0;
+    for (const [d, count] of dirCounts) {
+        if (!genericDirs.has(d) && count > topCount) {
+            topCount = count;
+            topDir = d;
+        }
+    }
+    if (topDir)
+        return `update-${topDir.replace(/[^a-z0-9-]/g, "-")}-layer`;
+    return `update-related-files-${fallbackIndex}`;
+}
+/**
+ * Construye el nombre definitivo de una rama del plan.
+ *
+ * - Rama base existente → devuelve `currentBranch` sin cambios.
+ * - Si hay `branchNamingContext` → usa `buildDerivedBranchName` (patrón `feature/<TEAM>-<NUM>-<desc>`).
+ * - Si no → no es posible llegar aquí; `parseAndValidateWorkingBranch` ya garantiza el formato.
+ */
+function buildBranchPlanName(currentBranch, branchBlocks, index, config, isExistingBaseBranch) {
+    if (isExistingBaseBranch)
+        return currentBranch;
+    const description = detectBranchDescription(branchBlocks, index);
+    // branchNamingContext siempre presente: parseAndValidateWorkingBranch lo garantiza al inicio.
+    if (!config.branchNamingContext) {
+        throw new Error("La rama activa no sigue el formato requerido (feature|bugfix|hotfix/<TEAM>-<NUM>[-<desc>]).");
+    }
+    return buildDerivedBranchName(config.branchNamingContext, description);
+}
+/**
+ * Identifica la rama base existente (la que más score tiene, o más líneas en caso de empate)
+ * y asigna los nombres definitivos a todas las ramas del plan.
+ *
+ * La rama base toma el nombre de `currentBranch` (no se crea, ya existe).
+ * Las demás toman nombres derivados con índices a partir del 2.
+ *
+ * @param plans         - Planes sin nombres definitivos (candidatos).
+ * @param currentBranch - Nombre de la rama activa en el repositorio.
+ * @param config        - Configuración para construir los nombres derivados.
+ * @returns             Plans con `name` e `isExistingBaseBranch` asignados correctamente.
+ */
+function markExistingBaseBranch(plans, currentBranch, config) {
+    if (!plans.length)
+        return plans;
+    const ordered = [...plans].sort((a, b) => {
+        if (a.score !== b.score)
+            return b.score - a.score;
+        if (a.lines !== b.lines)
+            return b.lines - a.lines;
+        return b.files - a.files;
+    });
+    const basePlan = ordered[0];
+    const rewrittenBasePlan = {
+        ...basePlan,
+        name: buildBranchPlanName(currentBranch, basePlan.blocks, 1, config, true),
+        isExistingBaseBranch: true
+    };
+    const derivedPlans = ordered.slice(1).map((plan, index) => ({
+        ...plan,
+        name: buildBranchPlanName(currentBranch, plan.blocks, index + 2, config, false),
+        isExistingBaseBranch: false
+    }));
+    // Deduplicar nombres: si dos ramas derivadas reciben el mismo nombre
+    // (p.ej. ambas tienen el mismo directorio dominante), se añade sufijo numérico.
+    // También es necesario incluir el nombre de la rama base para evitar que
+    // buildDerivedBranchName genere un nombre idéntico a currentBranch, lo que
+    // causaría que createBranchFromSource lance "La rama destino ya existe".
+    const nameOccurrences = new Map();
+    nameOccurrences.set(rewrittenBasePlan.name, 1); // reservar nombre de la rama base
+    for (const p of derivedPlans) {
+        nameOccurrences.set(p.name, (nameOccurrences.get(p.name) ?? 0) + 1);
+    }
+    const nameCounter = new Map();
+    const deduplicatedDerived = derivedPlans.map((plan) => {
+        if ((nameOccurrences.get(plan.name) ?? 0) <= 1)
+            return plan;
+        const n = (nameCounter.get(plan.name) ?? 1);
+        nameCounter.set(plan.name, n + 1);
+        return { ...plan, name: `${plan.name}-${n}` };
+    });
+    return [rewrittenBasePlan, ...deduplicatedDerived];
+}
+// ---------------------------------------------------------------------------
+// Public
+// ---------------------------------------------------------------------------
+/**
+ * Encuentra el plan óptimo de ramas para un conjunto de bloques.
+ *
+ * Explora desde `minBranches` hasta `minBranches + config.maxBranchSearchRange`
+ * distribuciones posibles y selecciona la que maximiza el score promedio
+ * ponderado. El primer elemento del resultado será siempre la rama base
+ * existente (`isExistingBaseBranch: true`).
+ *
+ * @param blocks        - Bloques de trabajo a distribuir.
+ * @param currentBranch - Nombre de la rama activa en el repositorio.
+ * @param config        - Configuración activa del proyecto.
+ * @param deps          - Aristas de dependencia entre archivos.
+ * @returns             Array de {@link BranchPlan} ordenados: base primero, derivadas después.
+ */
+export function findBestPlan(blocks, currentBranch, config, deps = []) {
+    const totalLines = blocks.reduce((sum, b) => sum + b.lines, 0);
+    const totalFiles = blocks.reduce((sum, b) => sum + b.files.length, 0);
+    const largeCount = blocks.filter((b) => !b.divisible).length;
+    let minBranches = 1;
+    minBranches = Math.max(minBranches, Math.ceil(totalLines / config.idealLinesPerPR));
+    minBranches = Math.max(minBranches, Math.ceil(totalFiles / (config.maxFilesPerCommit * config.maxCommitsPerBranchIdeal)));
+    minBranches = Math.max(minBranches, largeCount);
+    let bestPlans = [];
+    for (let branchCount = minBranches; branchCount <= minBranches + config.maxBranchSearchRange; branchCount++) {
+        const distributed = distributeBlocks(blocks, branchCount, config, deps);
+        let valid = true;
+        const plans = [];
+        for (let i = 0; i < distributed.length; i++) {
+            const branchBlocks = distributed[i];
+            if (!branchBlocks.length)
+                continue;
+            const evalResult = evaluateBranch(branchBlocks, config);
+            const commitPlan = buildCommitPlan(branchBlocks, config);
+            const finalEval = rescoreWithPlan(evalResult, commitPlan, branchTotals(branchBlocks).lines, config);
+            if (finalEval.score < config.targetScore &&
+                ![
+                    "Contiene bloque grande indivisible",
+                    "PR demasiado grande por total de líneas"
+                ].includes(evalResult.reason)) {
+                valid = false;
+            }
+            if (finalEval.commits > config.hardMaxCommitsPerBranch) {
+                valid = false;
+            }
+            plans.push({
+                name: `candidate-${i + 1}`,
+                ...finalEval,
+                blocks: branchBlocks,
+                commitPlan,
+                isExistingBaseBranch: false
+            });
+        }
+        if (valid) {
+            bestPlans = plans;
+            // El primer branchCount válido encontrado es siempre el mínimo posible;
+            // iteraciones posteriores solo tendrían más ramas (y nunca menor branchCount).
+            break;
+        }
+    }
+    if (!bestPlans.length) {
+        const fallback = distributeBlocks(blocks, minBranches, config, deps);
+        bestPlans = fallback
+            .filter((b) => b.length)
+            .map((branchBlocks, i) => {
+            const evalResult = evaluateBranch(branchBlocks, config);
+            const commitPlan = buildCommitPlan(branchBlocks, config);
+            const finalEval = rescoreWithPlan(evalResult, commitPlan, branchTotals(branchBlocks).lines, config);
+            return {
+                name: `candidate-${i + 1}`,
+                ...finalEval,
+                blocks: branchBlocks,
+                commitPlan,
+                isExistingBaseBranch: false
+            };
+        });
+    }
+    return markExistingBaseBranch(bestPlans, currentBranch, config);
+}

package/dist/git/branch-naming.js

@@ -0,0 +1,120 @@
+/**
+ * branch-naming.ts — Parsing y generación de nombres de rama.
+ *
+ * Este módulo implementa dos responsabilidades:
+ *
+ * 1. **Validación** (`parseAndValidateWorkingBranch`): verifica que la rama activa
+ *    siga el patrón `feature|bugfix/<TEAM>-<NUM>-<descripcion>` y extrae sus partes
+ *    como un {@link BranchNamingContext}.
+ *
+ * 2. **Generación** (`buildDerivedBranchName`): construye el nombre de una rama
+ *    derivada nueva a partir del contexto extraído y una descripción en inglés.
+ *    Trunca el nombre si supera {@link BRANCH_NAME_MAX_LENGTH}.
+ *
+ * El patrón de rama esperado es:
+ * ```
+ * feature/ABC-123-add-login-endpoint
+ * bugfix/TEAM-456-fix-null-pointer
+ * ```
+ */
+import { BRANCH_NAME_MAX_LENGTH } from "../shared/constants.js";
+// Patrón de rama: `<tipo>/<TEAMCODE>-<NUM>` o `<tipo>/<TEAMCODE>-<NUM>-<slug>`.
+// La descripción es opcional: `feature/TEAM-123` y `feature/TEAM-123-add-login` son ambos válidos.
+// Solo se aceptan los tipos feature, bugfix y hotfix.
+// La descripción acepta mayúsculas y minúsculas ([a-zA-Z0-9-]) para
+// soportar ramas como feature/FASTY-0001-PRUEBA-IA.
+const BRANCH_PATTERN = /^(feature|bugfix|hotfix)\/([A-Za-z]+)-(\d+)(-[a-zA-Z0-9-]+)?$/;
+/**
+ * Valida que el nombre de rama siga el patrón requerido y extrae sus componentes.
+ *
+ * @param branchName - Nombre completo de la rama activa (ej. `"feature/ABC-123-login"`).
+ * @returns          Contexto con las partes de la rama parseadas.
+ * @throws {Error}   Si el nombre no sigue el patrón, con un mensaje descriptivo
+ *                   que incluye el formato esperado y un ejemplo.
+ */
+export function parseAndValidateWorkingBranch(branchName) {
+    const match = branchName.match(BRANCH_PATTERN);
+    if (!match) {
+        throw new Error([
+            "La rama actual no cumple el formato requerido.",
+            "Formato permitido:",
+            "  <tipo>/TEAMCODE-123",
+            "  <tipo>/TEAMCODE-123-descripcion-opcional",
+            "Tipos válidos:",
+            "  feature · bugfix · hotfix",
+            "Ejemplos:",
+            "  feature/TEAM-123-add-login-endpoint",
+            "  bugfix/TEAM-456-null-pointer",
+            "  hotfix/TEAM-789-critical-fix"
+        ].join("\n"));
+    }
+    const [, branchType, rawTeamCode, storyNumber, descWithDash] = match;
+    // La descripción viene con guión inicial (p.ej. "-add-login") o undefined si omitida.
+    const originalDescription = descWithDash ? descWithDash.replace(/^-/, "") : "";
+    return {
+        branchType: branchType,
+        teamCode: rawTeamCode.toUpperCase(),
+        storyNumber,
+        originalDescription
+    };
+}
+/**
+ * Normaliza un texto libre a un slug solo con caracteres `[a-z0-9-]`.
+ *
+ * Pasos aplicados:
+ * 1. Convierte a minúsculas.
+ * 2. Descompone caracteres acentuados (NFD) y elimina los diacríticos.
+ * 3. Reemplaza cualquier carácter que no sea letra/dígito con `-`.
+ * 4. Elimina guiones al inicio y al final.
+ * 5. Colapsa múltiples guiones consecutivos en uno solo.
+ *
+ * @param value - Texto a normalizar (título, descripción, etc.).
+ * @returns     Slug en minúsculas con solo `[a-z0-9-]`.
+ */
+function normalizeEnglishSlugPart(value) {
+    return value
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "")
+        .replace(/--+/g, "-");
+}
+/**
+ * Construye el nombre completo de una rama derivada a partir del contexto
+ * de nomenclatura y una descripción en inglés en slug.
+ *
+ * El nombre resultante sigue el patrón:
+ * `<branchType>/<TEAMCODE>-<storyNumber>-<description>`
+ *
+ * Si el nombre supera {@link BRANCH_NAME_MAX_LENGTH} caracteres, la descripción
+ * se trunca y se emite un aviso por stderr (no lanza excepción).
+ *
+ * @param context     - Contexto extraído por `parseAndValidateWorkingBranch`.
+ * @param description - Descripción en slug inglés (ej. `"update-auth-layer"`),
+ *                      generada típicamente por `detectBranchDescription`.
+ * @throws {Error} Si `description` resulta vacía tras la normalización.
+ */
+export function buildDerivedBranchName(context, description) {
+    const normalizedDescription = normalizeEnglishSlugPart(description);
+    if (!normalizedDescription) {
+        throw new Error("No se pudo generar una descripcion valida en ingles para la rama.");
+    }
+    const prefix = `${context.branchType}/${context.teamCode}-${context.storyNumber}-`;
+    const full = `${prefix}${normalizedDescription}`;
+    if (full.length <= BRANCH_NAME_MAX_LENGTH)
+        return full;
+    // Truncar la descripción para mantener el nombre dentro del límite.
+    const maxDescLength = BRANCH_NAME_MAX_LENGTH - prefix.length;
+    const truncated = maxDescLength > 0
+        ? normalizedDescription.slice(0, maxDescLength).replace(/-+$/, "") || "changes"
+        : "changes";
+    const result = maxDescLength > 0
+        ? `${prefix}${truncated}`
+        : full.slice(0, BRANCH_NAME_MAX_LENGTH).replace(/-+$/, "");
+    process.stderr.write(`[branch-naming warn] El nombre de rama supera ${BRANCH_NAME_MAX_LENGTH} caracteres y se truncará.\n` +
+        `  Original : ${full}\n` +
+        `  Truncado : ${result}\n`);
+    return result;
+}