pull-request-split-advisor 3.1.2

package/dist/config/config.js

@@ -0,0 +1,315 @@
+/**
+ * config.ts — Carga, validación y merge de la configuración del proyecto.
+ *
+ * ### Flujo de `loadConfig`
+ * ```
+ * 1. Si no existe el archivo de config → devuelve defaultConfig directamente.
+ * 2. Parsea el JSON (o YAML si está disponible js-yaml).
+ * 3. Valida tipos básicos de cada campo clave.
+ * 4. Valida rangos y valores permitidos.
+ * 5. Hace deep-merge(defaultConfig, parsed) → merged.
+ * 6. Valida relaciones cruzadas sobre merged.
+ * 7. Valida métricas: regla default presente, suma de pesos = 1.0.
+ * 8. Devuelve merged.
+ * ```
+ *
+ * ### Por qué las validaciones cruzadas van sobre `merged`
+ * Si el usuario solo cambia uno de los dos campos de una relación, el otro sigue
+ * en el valor del default. Validar `parsed` nunca vería el campo no sobreescrito.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { defaultConfig } from "./default-config.js";
+import { PROVIDER_REGISTRY } from "../ai/provider.js";
+const _require = createRequire(import.meta.url);
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Combina recursivamente `base` con `override`.
+ * Las propiedades de `override` sobreescriben las de `base`.
+ * Las propiedades de `base` ausentes en `override` se conservan.
+ * Los valores `null` se descartan (conservando el default) con aviso.
+ */
+function deepMerge(base, override) {
+    if (!isObject(base) || !isObject(override)) {
+        return override ?? base;
+    }
+    const output = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const baseValue = output[key];
+        if (isObject(baseValue) && isObject(value)) {
+            output[key] = deepMerge(baseValue, value);
+        }
+        else if (value !== null) {
+            output[key] = value;
+        }
+        else {
+            process.stderr.write(`[config warn] El campo "${key}" tiene valor null en la configuración. ` +
+                `Se ignorará y se usará el valor por defecto. Para omitirlo correctamente, elimina el campo del JSON.\n`);
+        }
+    }
+    return output;
+}
+/**
+ * Resuelve la ruta del archivo de configuración buscando variantes JSON/YAML.
+ */
+function resolveConfigPath(configPath) {
+    if (configPath !== "pr-split-advisor.config.json")
+        return configPath;
+    const base = "pr-split-advisor.config";
+    for (const ext of ["json", "yaml", "yml"]) {
+        if (existsSync(path.resolve(process.cwd(), `${base}.${ext}`))) {
+            return `${base}.${ext}`;
+        }
+    }
+    return configPath;
+}
+function parseConfigFile(filePath, raw) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith(".yaml") || lower.endsWith(".yml")) {
+        return parseYamlSimple(raw);
+    }
+    return JSON.parse(raw);
+}
+/**
+ * Parser YAML minimalista. Para configs complejas (metrics anidados) se
+ * recomienda instalar js-yaml o usar el formato JSON.
+ */
+function parseYamlSimple(raw) {
+    try {
+        const jsYaml = _require("js-yaml");
+        return jsYaml.load(raw);
+    }
+    catch {
+        // js-yaml no disponible: fallback al parser básico
+    }
+    if (/^\s*-\s+/m.test(raw)) {
+        throw new Error('El archivo YAML contiene arrays. Instala js-yaml (npm install js-yaml) o usa formato JSON.');
+    }
+    const result = {};
+    const lines = raw.split("\n");
+    const stack = [
+        { indent: -1, obj: result }
+    ];
+    for (const line of lines) {
+        const stripped = line.replace(/#.*$/, "").trimEnd();
+        if (!stripped.trim())
+            continue;
+        const indent = stripped.length - stripped.trimStart().length;
+        const content = stripped.trim();
+        const colonIdx = content.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const key = content.slice(0, colonIdx).trim();
+        const valueStr = content.slice(colonIdx + 1).trim();
+        while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+        const currentObj = stack[stack.length - 1].obj;
+        if (valueStr === "" || valueStr === "|" || valueStr === ">") {
+            const nested = {};
+            currentObj[key] = nested;
+            stack.push({ indent, obj: nested });
+        }
+        else {
+            currentObj[key] = parseYamlScalar(valueStr);
+        }
+    }
+    return result;
+}
+function parseYamlScalar(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (value === "null" || value === "~")
+        return null;
+    if (/^-?\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Carga y valida la configuración del proyecto.
+ *
+ * @param configPath - Ruta al archivo de configuración. Por defecto: `pr-split-advisor.config.json`.
+ */
+export function loadConfig(configPath = "pr-split-advisor.config.json") {
+    const resolvedPath = resolveConfigPath(configPath);
+    const fullPath = path.resolve(process.cwd(), resolvedPath);
+    if (!existsSync(fullPath)) {
+        return defaultConfig;
+    }
+    const raw = readFileSync(fullPath, "utf8");
+    let parsed;
+    try {
+        parsed = parseConfigFile(resolvedPath, raw);
+    }
+    catch (cause) {
+        throw new Error(`Error al parsear ${resolvedPath}: ${cause.message}`);
+    }
+    // Campos exclusivos de runtime — no deben aparecer en el archivo de config.
+    const runtimeOnlyFields = [
+        "runtimeExcludedFiles",
+        "branchNamingContext",
+    ];
+    for (const field of runtimeOnlyFields) {
+        if (field in parsed) {
+            throw new Error(`Configuración inválida: "${field}" es un campo de uso interno y no puede ` +
+                `definirse en el archivo de configuración. Elimínalo de ${resolvedPath}.`);
+        }
+    }
+    // Campos eliminados — rechazar con mensaje de migración
+    const removedFields = {
+        "runValidation": "Eliminado. Es responsabilidad del desarrollador no hacer push con errores.",
+        "validationCommand": "Eliminado. Es responsabilidad del desarrollador no hacer push con errores.",
+        "fileGroups": "Eliminado. El distribuidor greedy agrupa archivos automáticamente.",
+        "autoCommitMessagePrefix": "Eliminado. El mensaje se introduce manualmente al crear cada commit.",
+        "buildCommand": "Eliminado. El build y los tests son responsabilidad del desarrollador.",
+        "testCommand": "Eliminado. El build y los tests son responsabilidad del desarrollador.",
+        "runPreChecks": "Eliminado. El build y los tests son responsabilidad del desarrollador.",
+    };
+    for (const [field, reason] of Object.entries(removedFields)) {
+        if (field in parsed) {
+            throw new Error(`Configuración inválida: "${field}" ya no existe. ${reason} Elimínalo de ${resolvedPath}.`);
+        }
+    }
+    // Validaciones de tipos
+    const numericFields = [
+        "largeFileThreshold", "mediumFileThreshold", "maxFilesPerCommit",
+        "maxLinesPerCommitIdeal", "maxCommitsPerBranchIdeal", "idealLinesPerPR",
+        "targetScore", "hardMaxCommitsPerBranch"
+    ];
+    for (const field of numericFields) {
+        if (field in parsed && typeof parsed[field] !== "number") {
+            throw new Error(`Configuración inválida: "${field}" debe ser un número (recibido: ${JSON.stringify(parsed[field])}).`);
+        }
+    }
+    const positiveFields = [
+        "largeFileThreshold", "mediumFileThreshold", "maxFilesPerCommit",
+        "maxLinesPerCommitIdeal", "maxCommitsPerBranchIdeal", "idealLinesPerPR",
+        "hardMaxCommitsPerBranch"
+    ];
+    for (const field of positiveFields) {
+        const val = parsed[field];
+        if (val !== undefined && val <= 0) {
+            throw new Error(`Configuración inválida: "${field}" debe ser mayor que 0 (recibido: ${val}).`);
+        }
+    }
+    if (parsed.targetScore !== undefined) {
+        if (parsed.targetScore <= 0 || parsed.targetScore > 5) {
+            throw new Error(`Configuración inválida: "targetScore" debe ser mayor que 0 y no mayor que 5 (recibido: ${parsed.targetScore}).`);
+        }
+    }
+    if (parsed.maxBranchSearchRange !== undefined) {
+        if (typeof parsed.maxBranchSearchRange !== "number" ||
+            !Number.isInteger(parsed.maxBranchSearchRange) ||
+            parsed.maxBranchSearchRange < 1) {
+            throw new Error(`Configuración inválida: "maxBranchSearchRange" debe ser un entero mayor o igual a 1 (recibido: ${parsed.maxBranchSearchRange}).`);
+        }
+    }
+    if (parsed.maxFilesPerCommit !== undefined && !Number.isInteger(parsed.maxFilesPerCommit)) {
+        throw new Error(`Configuración inválida: "maxFilesPerCommit" debe ser un número entero.`);
+    }
+    if (parsed.hardMaxCommitsPerBranch !== undefined && !Number.isInteger(parsed.hardMaxCommitsPerBranch)) {
+        throw new Error(`Configuración inválida: "hardMaxCommitsPerBranch" debe ser un número entero.`);
+    }
+    if (parsed.hardMaxCommitsPerBranch !== undefined && parsed.hardMaxCommitsPerBranch < 1) {
+        throw new Error(`Configuración inválida: "hardMaxCommitsPerBranch" debe ser >= 1 (recibido: ${parsed.hardMaxCommitsPerBranch}).`);
+    }
+    const merged = deepMerge(defaultConfig, parsed);
+    if (merged.hardMaxCommitsPerBranch <
+        merged.maxCommitsPerBranchIdeal) {
+        throw new Error(`Configuración inválida: "hardMaxCommitsPerBranch" (${merged.hardMaxCommitsPerBranch}) debe ser mayor o igual que "maxCommitsPerBranchIdeal" (${merged.maxCommitsPerBranchIdeal}).`);
+    }
+    if (merged.mediumFileThreshold >=
+        merged.largeFileThreshold) {
+        throw new Error(`Configuración inválida: "mediumFileThreshold" (${merged.mediumFileThreshold}) debe ser menor que "largeFileThreshold" (${merged.largeFileThreshold}).`);
+    }
+    if ("excludeLockfiles" in parsed && typeof parsed.excludeLockfiles !== "boolean") {
+        throw new Error(`Configuración inválida: "excludeLockfiles" debe ser true o false.`);
+    }
+    if ("exportJson" in parsed && typeof parsed.exportJson !== "boolean") {
+        throw new Error(`Configuración inválida: "exportJson" debe ser true o false.`);
+    }
+    const booleanFields = ["verbose"];
+    for (const field of booleanFields) {
+        if (field in parsed && typeof parsed[field] !== "boolean") {
+            throw new Error(`Configuración inválida: "${field}" debe ser true o false (recibido: ${JSON.stringify(parsed[field])}).`);
+        }
+    }
+    const stringFields = ["jsonOutputFile", "historyFile"];
+    for (const field of stringFields) {
+        if (field in parsed && typeof parsed[field] !== "string") {
+            throw new Error(`Configuración inválida: "${field}" debe ser un string (recibido: ${JSON.stringify(parsed[field])}).`);
+        }
+    }
+    if ("baseBranch" in parsed) {
+        if (typeof parsed.baseBranch !== "string" || parsed.baseBranch.trim() === "") {
+            throw new Error(`Configuración inválida: "baseBranch" no puede ser un string vacío.`);
+        }
+    }
+    // Validar métricas sobre el merge final
+    if (isObject(merged.metrics)) {
+        const metricsObj = merged.metrics;
+        let totalWeight = 0;
+        for (const [code, def] of Object.entries(metricsObj)) {
+            if (!isObject(def))
+                continue;
+            const metricDef = def;
+            if (Array.isArray(metricDef["scoring"])) {
+                const hasDefault = metricDef["scoring"].some((rule) => isObject(rule) && rule["default"] === true);
+                if (!hasDefault) {
+                    throw new Error(`Configuración inválida: la métrica "${code}" debe tener al menos una regla con { default: true }.`);
+                }
+            }
+            if (typeof metricDef["weight"] === "number") {
+                totalWeight += metricDef["weight"];
+            }
+        }
+        const metricCount = Object.keys(metricsObj).length;
+        if (metricCount > 0 && metricCount !== 4) {
+            throw new Error(`Configuración inválida: se requieren exactamente 4 métricas (recibido: ${metricCount}).`);
+        }
+        if (metricCount > 0 && Math.abs(totalWeight - 1.0) > 0.01) {
+            throw new Error(`Configuración inválida: la suma de los pesos de las métricas debe ser 1.0 (suma actual: ${totalWeight.toFixed(4)}).`);
+        }
+    }
+    // ── Validar sección ai (opcional) ─────────────────────────────────────────
+    if ("ai" in parsed && isObject(parsed["ai"])) {
+        const ai = parsed["ai"];
+        if ("provider" in ai && !PROVIDER_REGISTRY.has(ai["provider"])) {
+            const knownProviders = [...PROVIDER_REGISTRY.keys()].join(", ");
+            throw new Error(`Configuración inválida: "ai.provider" debe ser uno de: ${knownProviders} (recibido: ${JSON.stringify(ai["provider"])}).`);
+        }
+        if ("model" in ai && (typeof ai["model"] !== "string" || !ai["model"].trim())) {
+            throw new Error(`Configuración inválida: "ai.model" debe ser un string no vacío.`);
+        }
+        if ("timeoutMs" in ai) {
+            const t = ai["timeoutMs"];
+            if (typeof t !== "number" || t < 1000) {
+                throw new Error(`Configuración inválida: "ai.timeoutMs" debe ser un número >= 1000 (recibido: ${JSON.stringify(t)}).`);
+            }
+        }
+        if ("maxTokens" in ai) {
+            const m = ai["maxTokens"];
+            if (typeof m !== "number" || m < 64 || m > 32768) {
+                throw new Error(`Configuración inválida: "ai.maxTokens" debe ser un número entre 64 y 32768 (recibido: ${JSON.stringify(m)}).`);
+            }
+        }
+        if (isObject(ai["features"])) {
+            const f = ai["features"];
+            for (const flag of ["commitMessages", "branchDescriptions"]) {
+                if (flag in f && typeof f[flag] !== "boolean") {
+                    throw new Error(`Configuración inválida: "ai.features.${flag}" debe ser true o false (recibido: ${JSON.stringify(f[flag])}).`);
+                }
+            }
+        }
+    }
+    return merged;
+}

package/dist/config/default-config.js

@@ -0,0 +1,223 @@
+/**
+ * default-config.ts — Valores por defecto de la configuración.
+ *
+ * `loadConfig` hace un deep-merge de estos valores con lo que el usuario
+ * especifica en `pr-split-advisor.config.json`. Cualquier campo omitido
+ * toma su valor de aquí.
+ *
+ * ### Guía de ajuste rápido
+ * Si el plan divide demasiado (muchas ramas) o demasiado poco:
+ * - `idealLinesPerPR`          — cuántas líneas caben en un PR
+ * - `largeFileThreshold`       — a partir de cuántas líneas un archivo es «grande»
+ * - `maxCommitsPerBranchIdeal` — cuántos commits se esperan por rama
+ * - `targetScore`              — score mínimo aceptable
+ *
+ * ### Fórmula del score
+ * ```
+ * score = Σ(points(métrica_i) × weight(métrica_i))
+ * ```
+ * Un score de 5 indica un PR ideal: pequeño, atómico y fácil de revisar.
+ */
+export const defaultConfig = {
+    // ── Git ──────────────────────────────────────────────────────────────────
+    baseBranch: "master",
+    // ── Archivos ─────────────────────────────────────────────────────────────
+    excludeLockfiles: true,
+    /**
+     * Número de líneas a partir del cual un archivo se considera «grande».
+     * El archivo se convierte en un bloque indivisible con 1 commit propio.
+     *
+     * Guía:
+     * - Proyectos nuevos / pequeños : 200–300
+     * - Proyectos medianos           : 400 (default)
+     * - Proyectos legacy / grandes   : 600–800
+     */
+    largeFileThreshold: 400,
+    /**
+     * Umbral de tamaño «mediano» (líneas). Los archivos medianos o grandes
+     * se aíslan en su propio commit.
+     */
+    mediumFileThreshold: 180,
+    // ── Commits y ramas ──────────────────────────────────────────────────────
+    /**
+     * Máximo de archivos por commit.
+     * El motor calcula commits = max(ceil(archivos/maxFilesPerCommit), ceil(líneas/maxLinesPerCommitIdeal)).
+     */
+    maxFilesPerCommit: 8,
+    /** Número ideal de líneas por commit. */
+    maxLinesPerCommitIdeal: 120,
+    /**
+     * Número ideal de commits por rama. Si una rama necesita más, la razón se
+     * marca como "Requiere más commits de lo ideal".
+     */
+    maxCommitsPerBranchIdeal: 2,
+    /**
+     * Límite DURO de commits por rama. Si una rama supera este valor el plan
+     * completo se descarta y el motor prueba con más ramas.
+     * Debe ser siempre mayor que `maxCommitsPerBranchIdeal`.
+     */
+    hardMaxCommitsPerBranch: 4,
+    /**
+     * Total de líneas que debe tener idealmente un PR.
+     * Es el parámetro más directo para controlar cuántas ramas genera el plan:
+     * `minBranches = ceil(totalLíneas / idealLinesPerPR)`
+     *
+     * Guía por tamaño de equipo:
+     * - Equipo pequeño (1–3 devs)  : 80–150
+     * - Equipo mediano (4–8 devs)  : 150–250
+     * - Equipo grande (>8 devs)    : 250–400
+     *
+     * El default agresivo de 99 líneas maximiza la división para proyectos
+     * nuevos; auméntalo si el plan genera demasiadas ramas.
+     */
+    idealLinesPerPR: 99,
+    /**
+     * Score mínimo para que el plan sea válido.
+     * - < 3.0 : casi cualquier distribución es válida
+     * - 4.0   : balance razonable (default)
+     * - 5.0   : solo PRs perfectamente pequeños
+     */
+    targetScore: 4,
+    /**
+     * Cuántos valores de `branchCount` explorar por encima del mínimo teórico.
+     * El motor se detiene en la primera iteración que produce un plan válido.
+     */
+    maxBranchSearchRange: 8,
+    // ── Exportación ──────────────────────────────────────────────────────────
+    exportJson: true,
+    jsonOutputFile: "pr-split-plan.json",
+    historyFile: ".pr-split-history.json",
+    // ── Runtime (campos internos — no configurar en JSON) ────────────────────
+    runtimeExcludedFiles: [],
+    branchNamingContext: undefined,
+    verbose: false,
+    // ── Métricas de scoring ───────────────────────────────────────────────────
+    //
+    // Orden posicional REQUERIDO (no cambiar el orden de las claves):
+    //   posición 0 → commitCount      (M1.3)
+    //   posición 1 → filesPerCommit   (M1.4)
+    //   posición 2 → avgLinesPerCommit (M1.5)
+    //   posición 3 → totalLinesChanged (M3.2)
+    //
+    metrics: {
+        /**
+         * M1.3 — Cantidad de commits en el PR.
+         * Peso: 0.20  |  Contribución máxima: 1.00 punto
+         */
+        "M1.3": {
+            label: "Cantidad de commits en PR",
+            weight: 0.2,
+            scoring: [
+                { lte: 2, points: 5 },
+                { lte: 4, points: 4 },
+                { eq: 5, points: 3 },
+                { lte: 7, points: 2 },
+                { default: true, points: 1 }
+            ]
+        },
+        /**
+         * M1.4 — Promedio de archivos por commit (excluye chore/style/docs).
+         * Peso: 0.25  |  Contribución máxima: 1.25 puntos
+         */
+        "M1.4": {
+            label: "Promedio de archivos por commit en PR",
+            weight: 0.25,
+            scoring: [
+                { lt: 15, points: 5 },
+                { lt: 20, points: 4 },
+                { lt: 30, points: 3 },
+                { lt: 40, points: 2 },
+                { default: true, points: 1 }
+            ]
+        },
+        /**
+         * M1.5 — Promedio de líneas por commit (excluye chore/style/docs).
+         * Peso: 0.25  |  Contribución máxima: 1.25 puntos
+         */
+        "M1.5": {
+            label: "Promedio de líneas por commit en PR",
+            weight: 0.25,
+            scoring: [
+                { lt: 100, points: 5 },
+                { lt: 150, points: 4 },
+                { lt: 250, points: 3 },
+                { lt: 350, points: 2 },
+                { default: true, points: 1 }
+            ]
+        },
+        /**
+         * M3.2 — Total de líneas cambiadas en el PR (incluye todos los commits).
+         * Peso: 0.30  |  Contribución máxima: 1.50 puntos
+         */
+        "M3.2": {
+            label: "Líneas modificadas en PR",
+            weight: 0.3,
+            scoring: [
+                { lte: 50, points: 5 },
+                { lte: 300, points: 4 },
+                { lte: 500, points: 3 },
+                { lte: 1200, points: 2 },
+                { default: true, points: 1 }
+            ]
+        }
+    },
+    // ── Reglas de recomendación ───────────────────────────────────────────────
+    recommendationRules: [
+        {
+            when: { eq: 5 },
+            message: "Score óptimo — listo para revisión"
+        },
+        {
+            when: { gte: 4, lt: 5 },
+            message: "Score aceptable — revisar detalles menores"
+        },
+        {
+            when: { gte: 3, lt: 4 },
+            message: "Score moderado — considera dividir más"
+        },
+        {
+            when: { gte: 1, lt: 3 },
+            message: "Score bajo — se recomienda refactorizar el plan"
+        },
+        {
+            when: { gte: 0 },
+            message: "Sin datos suficientes para recomendar"
+        }
+    ],
+    // ── Capa de IA ───────────────────────────────────────────────────────────────────────────────
+    //
+    // Configurar vía `pr-split-advisor config` o editando directamente el JSON.
+    //
+    // Opciones de `provider` soportadas: "groq" | "github" | "copilot"
+    //   groq    → requiere GROQ_API_KEY  (console.groq.com, free tier)
+    //   github  → requiere GITHUB_TOKEN  (github.com/marketplace/models, free)
+    //   copilot → sin token — usa automáticamente credenciales de gh CLI
+    //
+    // API key: preferir `apiKeyEnvVar` (ej: GROQ_API_KEY) antes que literal `apiKey`.
+    // Configurar con el asistente: pr-split-advisor config
+    //
+    ai: {
+        enabled: false,
+        provider: "groq",
+        model: "llama-3.3-70b-versatile",
+        apiKey: "",
+        apiKeyEnvVar: "GROQ_API_KEY",
+        features: {
+            commitMessages: true,
+            branchDescriptions: true,
+            planRebalance: false,
+        },
+        timeoutMs: 15000,
+        maxTokens: 1024,
+    },
+};
+/**
+ * Campos de `defaultConfig` exclusivamente de uso interno en tiempo de ejecución.
+ * No deben aparecer en el archivo `pr-split-advisor.config.json` del proyecto.
+ *
+ * `postinstall.cjs` importa esta constante para eliminarlos del JSON generado.
+ */
+export const RUNTIME_ONLY_FIELDS = [
+    "runtimeExcludedFiles",
+    "branchNamingContext",
+];

package/dist/core/blocks.js

@@ -0,0 +1,145 @@
+/**
+ * blocks.ts — Agrupación de archivos en bloques de trabajo.
+ *
+ * Un **bloque** es la unidad mínima de distribución: un conjunto de archivos
+ * relacionados que `distributeBlocks` asigna íntegro a una rama.
+ *
+ * ### Reglas de agrupación
+ * 1. **Archivos grandes** (`lines > largeFileThreshold`): bloque propio e indivisible.
+ *    No pueden compartir commit con otros archivos.
+ * 2. **Demás archivos**: se agrupan por la clave `directorio::nombreBase`.
+ *    `getGroupKey` elimina la extensión y el sufijo `test`/`spec`, por eso
+ *    `auth.service.ts` y `auth.service.spec.ts` quedan en el mismo bloque.
+ * 3. **Archivos de test**: siempre van con su fuente en el mismo bloque e indivisibles.
+ *    - Si el bloque mezcla test + fuente → `divisible: false` (mismo commit obligatorio).
+ *    - Si la fuente es un archivo grande (bloque `large::`): los tests se fusionan en
+ *      ese bloque para garantizar que nunca queden en una rama distinta.
+ *    Esto evita que SonarQube detecte cobertura negativa en «new code» al analizar
+ *    un PR sin los tests correspondientes.
+ *
+ * ### Cálculo de `depScore`
+ * Se cuenta el número de aristas de dependencia que tocan cada archivo,
+ * usando un mapa de frecuencias construido en O(n+m) (n=archivos, m=aristas).
+ * Un bloque con `depScore` alto está muy acoplado con otros bloques; el algoritmo
+ * greedy de distribución lo tiene en cuenta para penalizar separarlos.
+ */
+import { basename, dirname } from "node:path";
+/**
+ * Genera la clave de agrupación para un archivo.
+ *
+ * Combina el directorio padre y el nombre base sin extensión ni sufijo
+ * `test`/`spec`. Esto asegura que un archivo y su test unitario queden en
+ * el mismo bloque, lo que mantiene coherencia en los commits.
+ *
+ * Ejemplo:
+ *   `src/auth/auth.service.ts`      → `src/auth::auth.service`
+ *   `src/auth/auth.service.spec.ts` → `src/auth::auth.service`
+ *
+ * @param file - Ruta relativa del archivo.
+ */
+function getGroupKey(file) {
+    const dir = dirname(file);
+    const base = basename(file).replace(/\.[^.]+$/, "").replace(/\.?(test|spec)$/, "");
+    return `${dir === "." ? "root" : dir}::${base}`;
+}
+/**
+ * Determina si un archivo es un test/spec basándose en su nombre o ruta.
+ *
+ * Patrones reconocidos:
+ * - Extensión doble: `*.test.ts`, `*.spec.ts`, `*.test.js`, `*.spec.js`, etc.
+ * - Directorios convencionales: `__tests__/`, `tests/`, `test/`, `spec/`, `specs/`.
+ * - Python: `test_foo.py`, `foo_test.py`.
+ *
+ * @param file - Ruta relativa del archivo.
+ */
+function isTestFile(file) {
+    const lower = file.toLowerCase();
+    if (/\.(test|spec)\.[a-z]+$/.test(lower))
+        return true;
+    if (/(?:^|\/)(__tests__|tests|test|spec|specs)\//.test(lower))
+        return true;
+    if (/(?:^|\/)test_[^/]+\.py$/.test(lower))
+        return true;
+    if (/(?:^|\/)[^/]+_test\.py$/.test(lower))
+        return true;
+    return false;
+}
+/**
+ * Agrupa los {@link FileStat}s en bloques de trabajo coherentes.
+ *
+ * - Archivos que superan `config.largeFileThreshold` se convierten en bloques
+ *   individuales e indivisibles.
+ * - El resto se agrupa por directorio + nombre base (sin extensión ni sufijo test/spec).
+ * - Los bloques que contienen archivos de test son siempre **indivisibles** para
+ *   garantizar que test y fuente se commiteen juntos (requerido por SonarQube new coverage).
+ * - Si la fuente es grande (bloque `large::`), los tests se fusionan en ese bloque
+ *   en lugar de quedar en un bloque separado que podría acabar en otra rama.
+ * - La propiedad `depScore` de cada bloque refleja cuántas aristas de dependencia
+ *   tocan alguno de sus archivos (calculado en O(n+m) con mapa de frecuencias).
+ *
+ * @param fileStats - Lista de estadísticas de archivos cambiados.
+ * @param config    - Configuración activa del proyecto.
+ * @param deps      - Aristas de dependencia calculadas por {@link buildDependencyEdges}.
+ * @returns         Array de bloques ordenados para su distribución en ramas.
+ */
+export function buildBlocks(fileStats, config, deps) {
+    const groups = new Map();
+    const blocks = [];
+    // Mapa groupKey → bloque large para fusionar tests con su fuente grande.
+    const largeBlockByGroupKey = new Map();
+    for (const fs of fileStats) {
+        if (fs.lines > config.largeFileThreshold) {
+            const block = {
+                id: `large::${fs.path}`,
+                priority: fs.priority,
+                divisible: false,
+                lines: fs.lines,
+                files: [fs.path],
+                depScore: 0
+            };
+            blocks.push(block);
+            largeBlockByGroupKey.set(getGroupKey(fs.path), block);
+            continue;
+        }
+        const key = getGroupKey(fs.path);
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(fs);
+    }
+    for (const [key, files] of groups.entries()) {
+        const hasTest = files.some((f) => isTestFile(f.path));
+        // Si el grupo contiene solo tests y existe un bloque large con la misma clave,
+        // fusionar los tests en ese bloque para que no queden en ramas separadas.
+        if (hasTest && files.every((f) => isTestFile(f.path))) {
+            const largeBlock = largeBlockByGroupKey.get(key);
+            if (largeBlock) {
+                for (const f of files) {
+                    largeBlock.files.push(f.path);
+                    largeBlock.lines += f.lines;
+                    largeBlock.priority = Math.min(largeBlock.priority, f.priority);
+                }
+                continue; // El test queda absorbido en el bloque large; no crear bloque separado.
+            }
+        }
+        blocks.push({
+            id: key,
+            priority: Math.min(...files.map((f) => f.priority)),
+            // Si el bloque contiene al menos un test, marcarlo como indivisible para
+            // garantizar que test y fuente se commiteen en el mismo commit.
+            divisible: !hasTest,
+            lines: files.reduce((sum, f) => sum + f.lines, 0),
+            files: files.map((f) => f.path),
+            depScore: 0
+        });
+    }
+    // Calcular depScore con un mapa de frecuencias: O(n+m) en lugar de O(n×m).
+    const fileEdgeCount = new Map();
+    for (const { from, to } of deps) {
+        fileEdgeCount.set(from, (fileEdgeCount.get(from) ?? 0) + 1);
+        fileEdgeCount.set(to, (fileEdgeCount.get(to) ?? 0) + 1);
+    }
+    for (const block of blocks) {
+        block.depScore = block.files.reduce((sum, file) => sum + (fileEdgeCount.get(file) ?? 0), 0);
+    }
+    return blocks;
+}