@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/lib/pr-analyzer.js

@@ -1,399 +1,399 @@
-'use strict';
-
-/**
- * pr-analyzer.js
- *
- * Analizador cuantitativo de PRs/diffs. Calcula complejidad (0-1), categoría
- * de tamaño, tiempo estimado de revisión y factores de riesgo a partir de un
- * `git diff` o un texto en formato diff unificado.
- *
- * Port a Node de `pr-analyzer.py` (377 LOC, MIT) del repo
- * `anthropic-skills/code-review-skill` analizado en `temp/code-review-skill-main/`
- * (sesión 2026-05-24). Adaptado a estilo SWL: zero-deps, módulo CommonJS
- * exportable, API en español-MX, retorno JSON parseable.
- *
- * Uso programático:
- *   const { analizar } = require('./scripts/lib/pr-analyzer');
- *   const reporte = analizar(diffText);
- *
- * Uso CLI (pendiente de wrapper en /swl:analizar-pr o /swl:revisar):
- *   git diff main...HEAD | node -e "
- *     const { analizar, formatear } = require('./scripts/lib/pr-analyzer');
- *     let buf = ''; process.stdin.on('data', d => buf += d);
- *     process.stdin.on('end', () => console.log(formatear(analizar(buf))));
- *   "
- *
- * @module scripts/lib/pr-analyzer
- */
-
-// ── constantes ────────────────────────────────────────────────────────────────
-
-const EXT_A_LENGUAJE = {
-  '.py': 'Python',
-  '.js': 'JavaScript',
-  '.mjs': 'JavaScript',
-  '.cjs': 'JavaScript',
-  '.ts': 'TypeScript',
-  '.tsx': 'TypeScript/React',
-  '.jsx': 'JavaScript/React',
-  '.rs': 'Rust',
-  '.go': 'Go',
-  '.c': 'C',
-  '.h': 'C/C++',
-  '.cpp': 'C++',
-  '.hpp': 'C++',
-  '.cc': 'C++',
-  '.cxx': 'C++',
-  '.java': 'Java',
-  '.kt': 'Kotlin',
-  '.swift': 'Swift',
-  '.rb': 'Ruby',
-  '.php': 'PHP',
-  '.cs': 'C#',
-  '.vue': 'Vue',
-  '.svelte': 'Svelte',
-  '.sql': 'SQL',
-  '.md': 'Markdown',
-  '.json': 'JSON',
-  '.yaml': 'YAML',
-  '.yml': 'YAML',
-  '.toml': 'TOML',
-  '.css': 'CSS',
-  '.scss': 'SCSS',
-  '.less': 'Less',
-  '.html': 'HTML',
-  '.sh': 'Shell',
-};
-
-const PATRONES_TEST = [
-  /test_.*\.py$/,
-  /.*_test\.py$/,
-  /.*\.test\.(js|jsx|ts|tsx|mjs|cjs)$/,
-  /.*\.spec\.(js|jsx|ts|tsx|mjs|cjs)$/,
-  /tests?\//,
-  /__tests__\//,
-];
-
-const PATRONES_CONFIG = [
-  /\.env(\.|$)/,
-  /(^|\/)config\./,
-  /package\.json$/,
-  /tsconfig\.json$/,
-  /Cargo\.toml$/,
-  /pyproject\.toml$/,
-  /requirements.*\.txt$/,
-  /\.ya?ml$/,
-];
-
-const PATRONES_SEGURIDAD = ['.env', 'auth', 'security', 'password', 'token', 'secret', 'credential'];
-
-const PATRONES_MIGRACION = [/migration/i, /\bmigrate\b/i, /alembic/i];
-
-// ── detección por archivo ─────────────────────────────────────────────────────
-
-/**
- * Detecta lenguaje a partir de la extensión del archivo.
- * @param {string} filename
- * @returns {string}
- */
-function detectarLenguaje(filename) {
-  const idx = filename.lastIndexOf('.');
-  if (idx < 0) return 'unknown';
-  const ext = filename.slice(idx).toLowerCase();
-  return EXT_A_LENGUAJE[ext] || 'unknown';
-}
-
-function esTest(filename) {
-  return PATRONES_TEST.some((p) => p.test(filename));
-}
-
-function esConfig(filename) {
-  return PATRONES_CONFIG.some((p) => p.test(filename));
-}
-
-// ── parser de diff ────────────────────────────────────────────────────────────
-
-/**
- * Parsea un diff unificado y extrae stats por archivo.
- * Soporta tanto `diff --git a/path b/path` como bloques sueltos `+++ b/path`.
- * @param {string} diffText
- * @returns {Array<{filename, additions, deletions, isTest, isConfig, language}>}
- */
-function parsearDiff(diffText) {
-  const archivos = [];
-  let actual = null;
-  const lineas = String(diffText || '').split(/\r?\n/);
-
-  for (const linea of lineas) {
-    if (linea.startsWith('diff --git')) {
-      if (actual) archivos.push(actual);
-      // Regex anclado: el `(?:.+) b/` greedy hace backtrack hasta el ÚLTIMO
-      // " b/" del string, que es el separador real entre oldpath y newpath
-      // del formato `diff --git a/<oldpath> b/<newpath>`. Esto resuelve
-      // paths que contienen "b/" como subcadena interna (ej. `src/b/foo.ts`).
-      // Bug previo: el patrón `b\/(.+)$` capturaba desde el PRIMER `b/`,
-      // incluyendo el separador en el filename.
-      const m = linea.match(/^diff --git a\/(?:.+) b\/(.+)$/);
-      if (m) {
-        const filename = m[1].trim();
-        actual = {
-          filename,
-          additions: 0,
-          deletions: 0,
-          isTest: esTest(filename),
-          isConfig: esConfig(filename),
-          language: detectarLenguaje(filename),
-        };
-      } else {
-        actual = null;
-      }
-    } else if (actual) {
-      if (linea.startsWith('+') && !linea.startsWith('+++')) {
-        actual.additions += 1;
-      } else if (linea.startsWith('-') && !linea.startsWith('---')) {
-        actual.deletions += 1;
-      }
-    }
-  }
-
-  if (actual) archivos.push(actual);
-  return archivos;
-}
-
-// ── métricas ──────────────────────────────────────────────────────────────────
-
-function calcularComplejidad(archivos) {
-  if (!archivos.length) return 0;
-  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
-  // sizeFactor, fileFactor y langFactor están clamped por construcción con
-  // Math.min. noTestRatio y el score final NO lo estaban: con datos
-  // patológicos (additions negativos por corrupción de parser, archivos
-  // manipulados externamente) noTestRatio podía exceder 1.0 e inflar el
-  // score muy por encima de 1.0. Defensa en profundidad: clamp explícito.
-  const sizeFactor   = Math.min(Math.max(totalCambios, 0) / 1000, 1.0);
-  const fileFactor   = Math.min(archivos.length / 20, 1.0);
-  const testLineas   = archivos.filter((f) => f.isTest).reduce((s, f) => s + f.additions + f.deletions, 0);
-  const noTestRatio  = Math.max(0, Math.min(1, 1 - testLineas / Math.max(totalCambios, 1)));
-  const lenguajes    = new Set(archivos.map((f) => f.language).filter((l) => l !== 'unknown'));
-  const langFactor   = Math.min(lenguajes.size / 5, 1.0);
-  const score = sizeFactor * 0.4 + fileFactor * 0.2 + noTestRatio * 0.2 + langFactor * 0.2;
-  const scoreClamped = Math.max(0, Math.min(1, score));
-  return Math.round(scoreClamped * 100) / 100;
-}
-
-function categorizarTamano(totalCambios) {
-  if (totalCambios < 50)  return 'XS (muy pequeño)';
-  if (totalCambios < 200) return 'S (pequeño)';
-  if (totalCambios < 400) return 'M (mediano)';
-  if (totalCambios < 800) return 'L (grande)';
-  return 'XL (muy grande) — considerar dividir';
-}
-
-function estimarTiempoRevision(archivos, complejidad) {
-  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
-  const baseMin   = totalCambios / 20;       // ~1 min por 20 líneas
-  const ajustado  = baseMin * (1 + complejidad);
-  return Math.max(5, Math.min(120, Math.round(ajustado)));
-}
-
-function identificarRiesgos(archivos) {
-  const riesgos = [];
-  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
-  const testCambios  = archivos.filter((f) => f.isTest).reduce((s, f) => s + f.additions + f.deletions, 0);
-
-  if (totalCambios > 400) {
-    riesgos.push({ tipo: 'PR_GRANDE', mensaje: `PR grande (${totalCambios} líneas) — más difícil de revisar a fondo` });
-  }
-  if (testCambios === 0 && totalCambios > 50) {
-    riesgos.push({ tipo: 'SIN_TESTS', mensaje: 'No hay cambios en tests — verificar cobertura' });
-  }
-  if (totalCambios > 100 && testCambios / Math.max(totalCambios, 1) < 0.2) {
-    riesgos.push({ tipo: 'BAJA_RATIO_TESTS', mensaje: 'Ratio de tests <20% — considerar agregar más' });
-  }
-
-  for (const f of archivos) {
-    const lower = f.filename.toLowerCase();
-    if (PATRONES_SEGURIDAD.some((p) => lower.includes(p))) {
-      riesgos.push({ tipo: 'ARCHIVO_SENSIBLE', mensaje: `Archivo sensible a seguridad: ${f.filename}` });
-      break;
-    }
-  }
-
-  for (const f of archivos) {
-    if (PATRONES_MIGRACION.some((p) => p.test(f.filename)) || f.language === 'SQL') {
-      riesgos.push({ tipo: 'CAMBIOS_BD', mensaje: 'Cambios en BD/migración detectados — revisar con cuidado' });
-      break;
-    }
-  }
-
-  const configs = archivos.filter((f) => f.isConfig);
-  if (configs.length) {
-    riesgos.push({ tipo: 'CONFIG', mensaje: `Cambios de configuración en ${configs.length} archivo(s)` });
-  }
-
-  return riesgos;
-}
-
-function generarSugerencias(archivos, complejidad, riesgos) {
-  const sugerencias = [];
-  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
-
-  if (totalCambios > 800) sugerencias.push('Considerar dividir este PR en cambios más enfocados');
-  if (complejidad > 0.7) {
-    sugerencias.push('Complejidad alta — reservar tiempo extra de revisión');
-    sugerencias.push('Considerar revisión en pareja para secciones críticas');
-  }
-  if (riesgos.some((r) => r.tipo === 'SIN_TESTS')) {
-    sugerencias.push('Pedir tests antes de aprobar');
-  }
-
-  const lenguajes = new Set(archivos.map((f) => f.language));
-  if (lenguajes.has('TypeScript') || lenguajes.has('TypeScript/React')) {
-    sugerencias.push('Verificar uso de tipos (evitar `any` y aserciones inseguras)');
-  }
-  if (lenguajes.has('Rust')) {
-    sugerencias.push('Verificar `unwrap()` y `expect()` en código de producción');
-  }
-  if (lenguajes.has('C') || lenguajes.has('C++') || lenguajes.has('C/C++')) {
-    sugerencias.push('Verificar memory safety, bounds y UB');
-  }
-  if (lenguajes.has('SQL')) {
-    sugerencias.push('Revisar inyección SQL y desempeño de queries');
-  }
-  if (lenguajes.has('Python')) {
-    sugerencias.push('Verificar excepciones específicas (no `except:` desnudo) y type hints');
-  }
-
-  if (!sugerencias.length) sugerencias.push('Revisión estándar suficiente');
-  return sugerencias;
-}
-
-/**
- * Sugiere el agente revisor SWL más apropiado según el lenguaje predominante.
- * Útil para `/swl:revisar` cuando no se especifica explícitamente el stack.
- * @param {Array} archivos
- * @returns {string|null}
- */
-function sugerirRevisorSWL(archivos) {
-  const conteo = {};
-  for (const f of archivos) {
-    if (f.isTest || f.isConfig) continue;
-    conteo[f.language] = (conteo[f.language] || 0) + (f.additions + f.deletions);
-  }
-  const ordenados = Object.entries(conteo).sort((a, b) => b[1] - a[1]);
-  if (!ordenados.length) return null;
-  const [predominante] = ordenados[0];
-  const mapa = {
-    'TypeScript': 'revisor-typescript-swl',
-    'TypeScript/React': 'revisor-react-swl',
-    'JavaScript/React': 'revisor-react-swl',
-    'JavaScript': 'revisor-typescript-swl',
-    'Python': 'revisor-codigo-swl',
-    'Go': 'revisor-go-swl',
-    'Rust': 'revisor-rust-swl',
-    'Java': 'revisor-java-swl',
-    'Kotlin': 'revisor-kotlin-swl',
-    'Swift': 'revisor-swift-swl',
-    'C#': 'revisor-csharp-swl',
-    'PHP': 'revisor-php-swl',
-  };
-  return mapa[predominante] || 'revisor-codigo-swl';
-}
-
-// ── API pública ───────────────────────────────────────────────────────────────
-
-/**
- * Analiza un diff y devuelve un objeto reporte estructurado.
- * @param {string} diffText
- * @returns {object}
- */
-function analizar(diffText) {
-  const archivos = parsearDiff(diffText);
-  const totalAdiciones  = archivos.reduce((s, f) => s + f.additions, 0);
-  const totalEliminaciones = archivos.reduce((s, f) => s + f.deletions, 0);
-  const totalCambios    = totalAdiciones + totalEliminaciones;
-  const complejidad     = calcularComplejidad(archivos);
-  const riesgos         = identificarRiesgos(archivos);
-  const sugerencias     = generarSugerencias(archivos, complejidad, riesgos);
-  const revisorSugerido = sugerirRevisorSWL(archivos);
-
-  return {
-    totalArchivos:  archivos.length,
-    totalAdiciones,
-    totalEliminaciones,
-    totalCambios,
-    complejidad,
-    categoriaTamano:        categorizarTamano(totalCambios),
-    tiempoRevisionEstimado: estimarTiempoRevision(archivos, complejidad),
-    riesgos,
-    sugerencias,
-    revisorSugerido,
-    archivos,
-  };
-}
-
-/**
- * Formatea el reporte para output legible en consola.
- * @param {object} reporte
- * @param {{detalleArchivos?: boolean}} [opts]
- * @returns {string}
- */
-function formatear(reporte, opts = {}) {
-  const out = [];
-  out.push('═══════════════════════════════════════════════════════════');
-  out.push('  REPORTE DE ANÁLISIS DE PR');
-  out.push('═══════════════════════════════════════════════════════════');
-  out.push('');
-  out.push('Resumen:');
-  out.push(`  Archivos cambiados: ${reporte.totalArchivos}`);
-  out.push(`  Adiciones:          +${reporte.totalAdiciones}`);
-  out.push(`  Eliminaciones:      -${reporte.totalEliminaciones}`);
-  out.push(`  Cambios totales:    ${reporte.totalCambios}`);
-  out.push('');
-  out.push(`Tamaño:        ${reporte.categoriaTamano}`);
-  out.push(`Complejidad:   ${reporte.complejidad}/1.0`);
-  out.push(`Tiempo estim.: ~${reporte.tiempoRevisionEstimado} min`);
-  if (reporte.revisorSugerido) {
-    out.push(`Revisor SWL sugerido: ${reporte.revisorSugerido}`);
-  }
-  if (reporte.riesgos.length) {
-    out.push('');
-    out.push('Riesgos:');
-    for (const r of reporte.riesgos) out.push(`  - [${r.tipo}] ${r.mensaje}`);
-  }
-  out.push('');
-  out.push('Sugerencias:');
-  for (const s of reporte.sugerencias) out.push(`  - ${s}`);
-  if (opts.detalleArchivos) {
-    out.push('');
-    out.push('Archivos por lenguaje:');
-    const porLang = {};
-    for (const f of reporte.archivos) {
-      (porLang[f.language] = porLang[f.language] || []).push(f);
-    }
-    for (const [lang, lista] of Object.entries(porLang).sort()) {
-      out.push(`  [${lang}]`);
-      for (const f of lista) {
-        const tag = f.isTest ? 'test' : f.isConfig ? 'conf' : 'src';
-        out.push(`    ${tag}  ${f.filename} (+${f.additions}/-${f.deletions})`);
-      }
-    }
-  }
-  out.push('═══════════════════════════════════════════════════════════');
-  return out.join('\n');
-}
-
-module.exports = {
-  analizar,
-  formatear,
-  parsearDiff,
-  detectarLenguaje,
-  esTest,
-  esConfig,
-  calcularComplejidad,
-  categorizarTamano,
-  estimarTiempoRevision,
-  identificarRiesgos,
-  generarSugerencias,
-  sugerirRevisorSWL,
-};
+'use strict';
+
+/**
+ * pr-analyzer.js
+ *
+ * Analizador cuantitativo de PRs/diffs. Calcula complejidad (0-1), categoría
+ * de tamaño, tiempo estimado de revisión y factores de riesgo a partir de un
+ * `git diff` o un texto en formato diff unificado.
+ *
+ * Port a Node de `pr-analyzer.py` (377 LOC, MIT) del repo
+ * `anthropic-skills/code-review-skill` analizado en `temp/code-review-skill-main/`
+ * (sesión 2026-05-24). Adaptado a estilo SWL: zero-deps, módulo CommonJS
+ * exportable, API en español-MX, retorno JSON parseable.
+ *
+ * Uso programático:
+ *   const { analizar } = require('./scripts/lib/pr-analyzer');
+ *   const reporte = analizar(diffText);
+ *
+ * Uso CLI (pendiente de wrapper en /swl:analizar-pr o /swl:revisar):
+ *   git diff main...HEAD | node -e "
+ *     const { analizar, formatear } = require('./scripts/lib/pr-analyzer');
+ *     let buf = ''; process.stdin.on('data', d => buf += d);
+ *     process.stdin.on('end', () => console.log(formatear(analizar(buf))));
+ *   "
+ *
+ * @module scripts/lib/pr-analyzer
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+const EXT_A_LENGUAJE = {
+  '.py': 'Python',
+  '.js': 'JavaScript',
+  '.mjs': 'JavaScript',
+  '.cjs': 'JavaScript',
+  '.ts': 'TypeScript',
+  '.tsx': 'TypeScript/React',
+  '.jsx': 'JavaScript/React',
+  '.rs': 'Rust',
+  '.go': 'Go',
+  '.c': 'C',
+  '.h': 'C/C++',
+  '.cpp': 'C++',
+  '.hpp': 'C++',
+  '.cc': 'C++',
+  '.cxx': 'C++',
+  '.java': 'Java',
+  '.kt': 'Kotlin',
+  '.swift': 'Swift',
+  '.rb': 'Ruby',
+  '.php': 'PHP',
+  '.cs': 'C#',
+  '.vue': 'Vue',
+  '.svelte': 'Svelte',
+  '.sql': 'SQL',
+  '.md': 'Markdown',
+  '.json': 'JSON',
+  '.yaml': 'YAML',
+  '.yml': 'YAML',
+  '.toml': 'TOML',
+  '.css': 'CSS',
+  '.scss': 'SCSS',
+  '.less': 'Less',
+  '.html': 'HTML',
+  '.sh': 'Shell',
+};
+
+const PATRONES_TEST = [
+  /test_.*\.py$/,
+  /.*_test\.py$/,
+  /.*\.test\.(js|jsx|ts|tsx|mjs|cjs)$/,
+  /.*\.spec\.(js|jsx|ts|tsx|mjs|cjs)$/,
+  /tests?\//,
+  /__tests__\//,
+];
+
+const PATRONES_CONFIG = [
+  /\.env(\.|$)/,
+  /(^|\/)config\./,
+  /package\.json$/,
+  /tsconfig\.json$/,
+  /Cargo\.toml$/,
+  /pyproject\.toml$/,
+  /requirements.*\.txt$/,
+  /\.ya?ml$/,
+];
+
+const PATRONES_SEGURIDAD = ['.env', 'auth', 'security', 'password', 'token', 'secret', 'credential'];
+
+const PATRONES_MIGRACION = [/migration/i, /\bmigrate\b/i, /alembic/i];
+
+// ── detección por archivo ─────────────────────────────────────────────────────
+
+/**
+ * Detecta lenguaje a partir de la extensión del archivo.
+ * @param {string} filename
+ * @returns {string}
+ */
+function detectarLenguaje(filename) {
+  const idx = filename.lastIndexOf('.');
+  if (idx < 0) return 'unknown';
+  const ext = filename.slice(idx).toLowerCase();
+  return EXT_A_LENGUAJE[ext] || 'unknown';
+}
+
+function esTest(filename) {
+  return PATRONES_TEST.some((p) => p.test(filename));
+}
+
+function esConfig(filename) {
+  return PATRONES_CONFIG.some((p) => p.test(filename));
+}
+
+// ── parser de diff ────────────────────────────────────────────────────────────
+
+/**
+ * Parsea un diff unificado y extrae stats por archivo.
+ * Soporta tanto `diff --git a/path b/path` como bloques sueltos `+++ b/path`.
+ * @param {string} diffText
+ * @returns {Array<{filename, additions, deletions, isTest, isConfig, language}>}
+ */
+function parsearDiff(diffText) {
+  const archivos = [];
+  let actual = null;
+  const lineas = String(diffText || '').split(/\r?\n/);
+
+  for (const linea of lineas) {
+    if (linea.startsWith('diff --git')) {
+      if (actual) archivos.push(actual);
+      // Regex anclado: el `(?:.+) b/` greedy hace backtrack hasta el ÚLTIMO
+      // " b/" del string, que es el separador real entre oldpath y newpath
+      // del formato `diff --git a/<oldpath> b/<newpath>`. Esto resuelve
+      // paths que contienen "b/" como subcadena interna (ej. `src/b/foo.ts`).
+      // Bug previo: el patrón `b\/(.+)$` capturaba desde el PRIMER `b/`,
+      // incluyendo el separador en el filename.
+      const m = linea.match(/^diff --git a\/(?:.+) b\/(.+)$/);
+      if (m) {
+        const filename = m[1].trim();
+        actual = {
+          filename,
+          additions: 0,
+          deletions: 0,
+          isTest: esTest(filename),
+          isConfig: esConfig(filename),
+          language: detectarLenguaje(filename),
+        };
+      } else {
+        actual = null;
+      }
+    } else if (actual) {
+      if (linea.startsWith('+') && !linea.startsWith('+++')) {
+        actual.additions += 1;
+      } else if (linea.startsWith('-') && !linea.startsWith('---')) {
+        actual.deletions += 1;
+      }
+    }
+  }
+
+  if (actual) archivos.push(actual);
+  return archivos;
+}
+
+// ── métricas ──────────────────────────────────────────────────────────────────
+
+function calcularComplejidad(archivos) {
+  if (!archivos.length) return 0;
+  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
+  // sizeFactor, fileFactor y langFactor están clamped por construcción con
+  // Math.min. noTestRatio y el score final NO lo estaban: con datos
+  // patológicos (additions negativos por corrupción de parser, archivos
+  // manipulados externamente) noTestRatio podía exceder 1.0 e inflar el
+  // score muy por encima de 1.0. Defensa en profundidad: clamp explícito.
+  const sizeFactor   = Math.min(Math.max(totalCambios, 0) / 1000, 1.0);
+  const fileFactor   = Math.min(archivos.length / 20, 1.0);
+  const testLineas   = archivos.filter((f) => f.isTest).reduce((s, f) => s + f.additions + f.deletions, 0);
+  const noTestRatio  = Math.max(0, Math.min(1, 1 - testLineas / Math.max(totalCambios, 1)));
+  const lenguajes    = new Set(archivos.map((f) => f.language).filter((l) => l !== 'unknown'));
+  const langFactor   = Math.min(lenguajes.size / 5, 1.0);
+  const score = sizeFactor * 0.4 + fileFactor * 0.2 + noTestRatio * 0.2 + langFactor * 0.2;
+  const scoreClamped = Math.max(0, Math.min(1, score));
+  return Math.round(scoreClamped * 100) / 100;
+}
+
+function categorizarTamano(totalCambios) {
+  if (totalCambios < 50)  return 'XS (muy pequeño)';
+  if (totalCambios < 200) return 'S (pequeño)';
+  if (totalCambios < 400) return 'M (mediano)';
+  if (totalCambios < 800) return 'L (grande)';
+  return 'XL (muy grande) — considerar dividir';
+}
+
+function estimarTiempoRevision(archivos, complejidad) {
+  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
+  const baseMin   = totalCambios / 20;       // ~1 min por 20 líneas
+  const ajustado  = baseMin * (1 + complejidad);
+  return Math.max(5, Math.min(120, Math.round(ajustado)));
+}
+
+function identificarRiesgos(archivos) {
+  const riesgos = [];
+  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
+  const testCambios  = archivos.filter((f) => f.isTest).reduce((s, f) => s + f.additions + f.deletions, 0);
+
+  if (totalCambios > 400) {
+    riesgos.push({ tipo: 'PR_GRANDE', mensaje: `PR grande (${totalCambios} líneas) — más difícil de revisar a fondo` });
+  }
+  if (testCambios === 0 && totalCambios > 50) {
+    riesgos.push({ tipo: 'SIN_TESTS', mensaje: 'No hay cambios en tests — verificar cobertura' });
+  }
+  if (totalCambios > 100 && testCambios / Math.max(totalCambios, 1) < 0.2) {
+    riesgos.push({ tipo: 'BAJA_RATIO_TESTS', mensaje: 'Ratio de tests <20% — considerar agregar más' });
+  }
+
+  for (const f of archivos) {
+    const lower = f.filename.toLowerCase();
+    if (PATRONES_SEGURIDAD.some((p) => lower.includes(p))) {
+      riesgos.push({ tipo: 'ARCHIVO_SENSIBLE', mensaje: `Archivo sensible a seguridad: ${f.filename}` });
+      break;
+    }
+  }
+
+  for (const f of archivos) {
+    if (PATRONES_MIGRACION.some((p) => p.test(f.filename)) || f.language === 'SQL') {
+      riesgos.push({ tipo: 'CAMBIOS_BD', mensaje: 'Cambios en BD/migración detectados — revisar con cuidado' });
+      break;
+    }
+  }
+
+  const configs = archivos.filter((f) => f.isConfig);
+  if (configs.length) {
+    riesgos.push({ tipo: 'CONFIG', mensaje: `Cambios de configuración en ${configs.length} archivo(s)` });
+  }
+
+  return riesgos;
+}
+
+function generarSugerencias(archivos, complejidad, riesgos) {
+  const sugerencias = [];
+  const totalCambios = archivos.reduce((s, f) => s + f.additions + f.deletions, 0);
+
+  if (totalCambios > 800) sugerencias.push('Considerar dividir este PR en cambios más enfocados');
+  if (complejidad > 0.7) {
+    sugerencias.push('Complejidad alta — reservar tiempo extra de revisión');
+    sugerencias.push('Considerar revisión en pareja para secciones críticas');
+  }
+  if (riesgos.some((r) => r.tipo === 'SIN_TESTS')) {
+    sugerencias.push('Pedir tests antes de aprobar');
+  }
+
+  const lenguajes = new Set(archivos.map((f) => f.language));
+  if (lenguajes.has('TypeScript') || lenguajes.has('TypeScript/React')) {
+    sugerencias.push('Verificar uso de tipos (evitar `any` y aserciones inseguras)');
+  }
+  if (lenguajes.has('Rust')) {
+    sugerencias.push('Verificar `unwrap()` y `expect()` en código de producción');
+  }
+  if (lenguajes.has('C') || lenguajes.has('C++') || lenguajes.has('C/C++')) {
+    sugerencias.push('Verificar memory safety, bounds y UB');
+  }
+  if (lenguajes.has('SQL')) {
+    sugerencias.push('Revisar inyección SQL y desempeño de queries');
+  }
+  if (lenguajes.has('Python')) {
+    sugerencias.push('Verificar excepciones específicas (no `except:` desnudo) y type hints');
+  }
+
+  if (!sugerencias.length) sugerencias.push('Revisión estándar suficiente');
+  return sugerencias;
+}
+
+/**
+ * Sugiere el agente revisor SWL más apropiado según el lenguaje predominante.
+ * Útil para `/swl:revisar` cuando no se especifica explícitamente el stack.
+ * @param {Array} archivos
+ * @returns {string|null}
+ */
+function sugerirRevisorSWL(archivos) {
+  const conteo = {};
+  for (const f of archivos) {
+    if (f.isTest || f.isConfig) continue;
+    conteo[f.language] = (conteo[f.language] || 0) + (f.additions + f.deletions);
+  }
+  const ordenados = Object.entries(conteo).sort((a, b) => b[1] - a[1]);
+  if (!ordenados.length) return null;
+  const [predominante] = ordenados[0];
+  const mapa = {
+    'TypeScript': 'revisor-typescript-swl',
+    'TypeScript/React': 'revisor-react-swl',
+    'JavaScript/React': 'revisor-react-swl',
+    'JavaScript': 'revisor-typescript-swl',
+    'Python': 'revisor-codigo-swl',
+    'Go': 'revisor-go-swl',
+    'Rust': 'revisor-rust-swl',
+    'Java': 'revisor-java-swl',
+    'Kotlin': 'revisor-kotlin-swl',
+    'Swift': 'revisor-swift-swl',
+    'C#': 'revisor-csharp-swl',
+    'PHP': 'revisor-php-swl',
+  };
+  return mapa[predominante] || 'revisor-codigo-swl';
+}
+
+// ── API pública ───────────────────────────────────────────────────────────────
+
+/**
+ * Analiza un diff y devuelve un objeto reporte estructurado.
+ * @param {string} diffText
+ * @returns {object}
+ */
+function analizar(diffText) {
+  const archivos = parsearDiff(diffText);
+  const totalAdiciones  = archivos.reduce((s, f) => s + f.additions, 0);
+  const totalEliminaciones = archivos.reduce((s, f) => s + f.deletions, 0);
+  const totalCambios    = totalAdiciones + totalEliminaciones;
+  const complejidad     = calcularComplejidad(archivos);
+  const riesgos         = identificarRiesgos(archivos);
+  const sugerencias     = generarSugerencias(archivos, complejidad, riesgos);
+  const revisorSugerido = sugerirRevisorSWL(archivos);
+
+  return {
+    totalArchivos:  archivos.length,
+    totalAdiciones,
+    totalEliminaciones,
+    totalCambios,
+    complejidad,
+    categoriaTamano:        categorizarTamano(totalCambios),
+    tiempoRevisionEstimado: estimarTiempoRevision(archivos, complejidad),
+    riesgos,
+    sugerencias,
+    revisorSugerido,
+    archivos,
+  };
+}
+
+/**
+ * Formatea el reporte para output legible en consola.
+ * @param {object} reporte
+ * @param {{detalleArchivos?: boolean}} [opts]
+ * @returns {string}
+ */
+function formatear(reporte, opts = {}) {
+  const out = [];
+  out.push('═══════════════════════════════════════════════════════════');
+  out.push('  REPORTE DE ANÁLISIS DE PR');
+  out.push('═══════════════════════════════════════════════════════════');
+  out.push('');
+  out.push('Resumen:');
+  out.push(`  Archivos cambiados: ${reporte.totalArchivos}`);
+  out.push(`  Adiciones:          +${reporte.totalAdiciones}`);
+  out.push(`  Eliminaciones:      -${reporte.totalEliminaciones}`);
+  out.push(`  Cambios totales:    ${reporte.totalCambios}`);
+  out.push('');
+  out.push(`Tamaño:        ${reporte.categoriaTamano}`);
+  out.push(`Complejidad:   ${reporte.complejidad}/1.0`);
+  out.push(`Tiempo estim.: ~${reporte.tiempoRevisionEstimado} min`);
+  if (reporte.revisorSugerido) {
+    out.push(`Revisor SWL sugerido: ${reporte.revisorSugerido}`);
+  }
+  if (reporte.riesgos.length) {
+    out.push('');
+    out.push('Riesgos:');
+    for (const r of reporte.riesgos) out.push(`  - [${r.tipo}] ${r.mensaje}`);
+  }
+  out.push('');
+  out.push('Sugerencias:');
+  for (const s of reporte.sugerencias) out.push(`  - ${s}`);
+  if (opts.detalleArchivos) {
+    out.push('');
+    out.push('Archivos por lenguaje:');
+    const porLang = {};
+    for (const f of reporte.archivos) {
+      (porLang[f.language] = porLang[f.language] || []).push(f);
+    }
+    for (const [lang, lista] of Object.entries(porLang).sort()) {
+      out.push(`  [${lang}]`);
+      for (const f of lista) {
+        const tag = f.isTest ? 'test' : f.isConfig ? 'conf' : 'src';
+        out.push(`    ${tag}  ${f.filename} (+${f.additions}/-${f.deletions})`);
+      }
+    }
+  }
+  out.push('═══════════════════════════════════════════════════════════');
+  return out.join('\n');
+}
+
+module.exports = {
+  analizar,
+  formatear,
+  parsearDiff,
+  detectarLenguaje,
+  esTest,
+  esConfig,
+  calcularComplejidad,
+  categorizarTamano,
+  estimarTiempoRevision,
+  identificarRiesgos,
+  generarSugerencias,
+  sugerirRevisorSWL,
+};