@saulwade/swl-ses 2.3.0 → 2.4.1

package/habilidades/changelog-generator/scripts/parse-commits.js

@@ -1,367 +1,367 @@
-'use strict';
-
-/**
- * parse-commits.js — Parser determinista de Conventional Commits para
- * generación automática de CHANGELOG en /swl:release.
- *
- * Lee commits desde `git log` (entre dos refs o desde la última tag) y los
- * clasifica según el spec de Conventional Commits 1.0.0:
- *   https://www.conventionalcommits.org/en/v1.0.0/
- *
- * Categorías generadas (formato Keep a Changelog):
- *   - feat                  -> "Nuevas funcionalidades"
- *   - fix                   -> "Correcciones"
- *   - perf                  -> "Mejoras de rendimiento"
- *   - refactor              -> "Cambios internos"
- *   - docs / style / test / ci / build / chore -> "Mantenimiento" (opcional)
- *   - BREAKING CHANGE / !   -> "Breaking changes" (siempre top de cada release)
- *   - Sin prefijo CC válido -> "Otros" (con bandera de baja conformidad)
- *
- * Fallback: si la conformidad de commits es <80%, el script retorna
- * `conformidad: <ratio>` para que el caller decida si abortar o seguir.
- *
- * Uso desde CLI:
- *   node parse-commits.js [--from <ref>] [--to <ref>] [--format json|markdown]
- *
- * Uso programático:
- *   const { parsearCommits, generarChangelog } = require('./parse-commits');
- *   const { categorias, conformidad } = parsearCommits(commits);
- *   const md = generarChangelog(categorias, { version: '1.6.5', fecha: '...' });
- *
- * Zero-deps. Cargado por skill `changelog-generator` y por
- * `/swl:release` paso 7.
- *
- * @module habilidades/changelog-generator/scripts/parse-commits
- */
-
-const { execSync } = require('node:child_process');
-
-// -----------------------------------------------------------------------------
-// Spec Conventional Commits
-// -----------------------------------------------------------------------------
-
-/**
- * Regex que matchea una línea de commit Conventional Commits.
- * Grupos: [1]=tipo, [2]=scope?, [3]=!?, [4]=descripcion
- *
- * Ejemplos válidos:
- *   feat(auth): agregar validación PKCE
- *   fix: corregir cálculo IEPS
- *   feat!: breaking change inline
- *   refactor(hooks/lib): split evolution-tracker
- *   chore(release): bump version
- *   [T-01] feat(hooks): prefijo de trazabilidad de tarea (ejecutar-fase)
- *   [T-07][T-08] refactor(hooks): varios prefijos consecutivos
- *   [REQ-08] feat(scripts): prefijo de requisito
- *   [F12·T-01] feat(hooks): prefijo namespaceado por fase (DT-IDS-NAMESPACE)
- *
- * El prefijo opcional `[T-NN]` / `[REQ-NN]` / `[F<fase>·T-NN]` (uno o más,
- * consecutivos) proviene de la convención de commits de
- * `habilidades/ejecutar-fase/SKILL.md` (trazabilidad de tarea/requisito; desde
- * la Fase 12 los IDs se namespacean por fase). No altera la semántica CC: el
- * tipo+scope+descripción siguen presentes después del/los prefijo(s), por lo
- * que el commit cuenta como conforme. Grupo non-capturing para no desplazar
- * los índices [1]=tipo [2]=scope [3]=! [4]=descripcion.
- */
-const RE_CONVENTIONAL = /^(?:\[(?:F\d+·)?(?:T|REQ)-\d+(?:-\d+)?\]\s*)*(feat|fix|perf|refactor|docs|style|test|ci|build|chore|revert|evolucion|evolve)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
-
-/** Mapa tipo CC → categoría Keep a Changelog en es-MX. */
-const CATEGORIAS = Object.freeze({
-  feat:      'Nuevas funcionalidades',
-  fix:       'Correcciones',
-  perf:      'Mejoras de rendimiento',
-  refactor:  'Cambios internos',
-  revert:    'Reversiones',
-  evolucion: 'Evoluciones de skills/agentes',
-  evolve:    'Evoluciones de skills/agentes',
-  docs:      'Mantenimiento',
-  style:     'Mantenimiento',
-  test:      'Mantenimiento',
-  ci:        'Mantenimiento',
-  build:     'Mantenimiento',
-  chore:     'Mantenimiento',
-});
-
-/** Orden de salida en CHANGELOG (Breaking siempre primero). */
-const ORDEN_CATEGORIAS = Object.freeze([
-  'Breaking changes',
-  'Nuevas funcionalidades',
-  'Correcciones',
-  'Mejoras de rendimiento',
-  'Cambios internos',
-  'Reversiones',
-  'Evoluciones de skills/agentes',
-  'Mantenimiento',
-  'Otros',
-]);
-
-// -----------------------------------------------------------------------------
-// Transformación técnica → user-facing
-// -----------------------------------------------------------------------------
-
-/**
- * Aplica heurísticas de transformación para hacer la línea más legible al
- * usuario final sin contradecir lo que dice el commit.
- *
- * Reglas conservadoras: solo elimina prefijos técnicos y normaliza la primera
- * letra. NO inventa contenido; si la descripción es críptica, queda críptica.
- *
- * @param {string} descripcion - Descripción cruda del commit.
- * @returns {string} Versión legible.
- */
-function transformarLegible(descripcion) {
-  let texto = descripcion.trim();
-
-  // Eliminar referencias a issues al final si son ruido (#123, refs #...).
-  texto = texto.replace(/\s*\(#\d+\)\s*$/, '');
-  texto = texto.replace(/\s*[Rr]efs?:?\s*#\d+\s*$/, '');
-
-  // Capitalizar primera letra.
-  if (texto.length > 0) {
-    texto = texto[0].toUpperCase() + texto.slice(1);
-  }
-
-  // Eliminar punto final si existe (Keep a Changelog usa bullets sin punto).
-  texto = texto.replace(/\.$/, '');
-
-  return texto;
-}
-
-// -----------------------------------------------------------------------------
-// Parser principal
-// -----------------------------------------------------------------------------
-
-/**
- * Detecta si el commit tiene marca de breaking change según el spec
- * Conventional Commits 1.0.0:
- *   - `!` después del tipo/scope en el subject, o
- *   - Trailer `BREAKING CHANGE:` o `BREAKING-CHANGE:` al INICIO de una línea
- *     del body (no en medio de prosa). El spec requiere este formato literal
- *     como trailer; una mención de la palabra dentro de la descripción NO
- *     dispara breaking change.
- *
- * Bug histórico (fix v1.6.5): la regex previa `/BREAKING\s+CHANGE/i` generaba
- * falsos positivos cuando el commit describía features que mencionaban
- * "breaking changes" en su prosa sin ser un breaking change ellos mismos.
- *
- * @param {string} mensajeCompleto - Mensaje completo del commit (subject + body).
- * @param {string} marcaExclamacion - Match del grupo `!` del regex.
- * @returns {boolean}
- */
-function esBreakingChange(mensajeCompleto, marcaExclamacion) {
-  if (marcaExclamacion === '!') return true;
-  // Trailer al inicio de línea, mayúsculas obligatorias, dos puntos al final.
-  return /^BREAKING[-\s]CHANGE:/m.test(mensajeCompleto);
-}
-
-/**
- * Parsea una lista de commits y los clasifica.
- *
- * @param {Array<{hash: string, subject: string, body?: string}>} commits
- * @returns {{
- *   categorias: Map<string, Array<{hash: string, descripcion: string, scope?: string}>>,
- *   conformidad: number,
- *   totalCommits: number,
- *   conformes: number,
- * }}
- */
-function parsearCommits(commits) {
-  const categorias = new Map();
-  for (const cat of ORDEN_CATEGORIAS) categorias.set(cat, []);
-
-  let conformes = 0;
-
-  for (const commit of commits) {
-    const { hash, subject = '', body = '' } = commit;
-    const completo = `${subject}\n${body}`;
-    const match = subject.match(RE_CONVENTIONAL);
-
-    if (!match) {
-      categorias.get('Otros').push({
-        hash,
-        descripcion: transformarLegible(subject),
-      });
-      continue;
-    }
-
-    conformes += 1;
-    const [, tipo, scope, marca, descripcion] = match;
-    const entrada = {
-      hash,
-      descripcion: transformarLegible(descripcion),
-      scope: scope || null,
-    };
-
-    // Breaking change tiene precedencia sobre la categoría natural.
-    if (esBreakingChange(completo, marca)) {
-      categorias.get('Breaking changes').push(entrada);
-      continue;
-    }
-
-    const categoria = CATEGORIAS[tipo] || 'Otros';
-    categorias.get(categoria).push(entrada);
-  }
-
-  return {
-    categorias,
-    conformidad: commits.length === 0 ? 1 : conformes / commits.length,
-    totalCommits: commits.length,
-    conformes,
-  };
-}
-
-// -----------------------------------------------------------------------------
-// Lectura desde git
-// -----------------------------------------------------------------------------
-
-/**
- * Obtiene commits desde git en formato estructurado.
- *
- * @param {object} opts
- * @param {string} [opts.from] - Ref inicial (default: última tag).
- * @param {string} [opts.to='HEAD'] - Ref final.
- * @param {string} [opts.cwd] - Directorio del repo.
- * @returns {Array<{hash: string, subject: string, body: string}>}
- */
-function leerCommitsGit(opts = {}) {
-  const { from, to = 'HEAD', cwd = process.cwd() } = opts;
-
-  let rango;
-  if (from) {
-    rango = `${from}..${to}`;
-  } else {
-    // Default: desde la última tag (si existe) o desde el initial commit.
-    try {
-      const ultimaTag = execSync('git describe --tags --abbrev=0', {
-        cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'],
-      }).trim();
-      rango = `${ultimaTag}..${to}`;
-    } catch {
-      rango = to;
-    }
-  }
-
-  // Separador único para parsear subject + body (que puede ser multi-línea).
-  const SEP = '<<<COMMIT-SWL-SEP>>>';
-  const FIELD = '<<<FIELD-SEP>>>';
-  const formato = `%H${FIELD}%s${FIELD}%b${SEP}`;
-
-  let salida;
-  try {
-    salida = execSync(`git log ${rango} --format=${JSON.stringify(formato)}`, {
-      cwd, encoding: 'utf8',
-    });
-  } catch {
-    return [];
-  }
-
-  return salida
-    .split(SEP)
-    .map(s => s.trim())
-    .filter(Boolean)
-    .map(linea => {
-      const [hash, subject, body] = linea.split(FIELD);
-      return {
-        hash: (hash || '').trim(),
-        subject: (subject || '').trim(),
-        body: (body || '').trim(),
-      };
-    })
-    .filter(c => c.hash);
-}
-
-// -----------------------------------------------------------------------------
-// Generación de markdown
-// -----------------------------------------------------------------------------
-
-/**
- * Genera la entrada de CHANGELOG en formato Keep a Changelog.
- *
- * @param {Map<string, Array>} categorias
- * @param {object} opts
- * @param {string} opts.version - Ej: '1.6.5'
- * @param {string} [opts.fecha] - Default: hoy en formato YYYY-MM-DD
- * @param {boolean} [opts.incluirHash=true] - Mostrar hash corto al inicio de cada bullet.
- * @returns {string}
- */
-function generarChangelog(categorias, opts) {
-  const { version, fecha, incluirHash = true } = opts || {};
-  if (!version) throw new Error('generarChangelog: version es obligatoria');
-
-  const fechaUsada = fecha || new Date().toISOString().slice(0, 10);
-  const lineas = [`## [${version}] - ${fechaUsada}`, ''];
-
-  for (const categoria of ORDEN_CATEGORIAS) {
-    const entradas = categorias.get(categoria) || [];
-    if (entradas.length === 0) continue;
-
-    lineas.push(`### ${categoria}`);
-    lineas.push('');
-    for (const entrada of entradas) {
-      const hashCorto = incluirHash && entrada.hash
-        ? `${entrada.hash.slice(0, 7)} `
-        : '';
-      const scope = entrada.scope ? `**${entrada.scope}**: ` : '';
-      lineas.push(`- ${hashCorto}${scope}${entrada.descripcion}`);
-    }
-    lineas.push('');
-  }
-
-  return lineas.join('\n');
-}
-
-// -----------------------------------------------------------------------------
-// CLI
-// -----------------------------------------------------------------------------
-
-function _parseFlags(argv) {
-  const flags = { format: 'markdown' };
-  for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === '--from' && argv[i + 1]) { flags.from = argv[++i]; continue; }
-    if (argv[i] === '--to' && argv[i + 1])   { flags.to   = argv[++i]; continue; }
-    if (argv[i] === '--format' && argv[i + 1]) { flags.format = argv[++i]; continue; }
-    if (argv[i] === '--version' && argv[i + 1]) { flags.version = argv[++i]; continue; }
-  }
-  return flags;
-}
-
-if (require.main === module) {
-  const flags = _parseFlags(process.argv);
-  const commits = leerCommitsGit({ from: flags.from, to: flags.to });
-  const resultado = parsearCommits(commits);
-
-  if (flags.format === 'json') {
-    process.stdout.write(JSON.stringify({
-      ...resultado,
-      categorias: Object.fromEntries(resultado.categorias),
-    }, null, 2));
-  } else {
-    if (!flags.version) {
-      process.stderr.write('ERROR: --version requerido para format=markdown\n');
-      process.exit(1);
-    }
-    process.stdout.write(generarChangelog(resultado.categorias, {
-      version: flags.version,
-    }));
-  }
-  process.stdout.write('\n');
-
-  if (resultado.conformidad < 0.8) {
-    process.stderr.write(
-      `\nADVERTENCIA: conformidad Conventional Commits = ${(resultado.conformidad * 100).toFixed(1)}% ` +
-      `(${resultado.conformes}/${resultado.totalCommits}). ` +
-      `Revisar bloque "Otros" antes de publicar.\n`,
-    );
-  }
-}
-
-module.exports = {
-  parsearCommits,
-  leerCommitsGit,
-  generarChangelog,
-  transformarLegible,
-  esBreakingChange,
-  RE_CONVENTIONAL,
-  CATEGORIAS,
-  ORDEN_CATEGORIAS,
-};
+'use strict';
+
+/**
+ * parse-commits.js — Parser determinista de Conventional Commits para
+ * generación automática de CHANGELOG en /swl:release.
+ *
+ * Lee commits desde `git log` (entre dos refs o desde la última tag) y los
+ * clasifica según el spec de Conventional Commits 1.0.0:
+ *   https://www.conventionalcommits.org/en/v1.0.0/
+ *
+ * Categorías generadas (formato Keep a Changelog):
+ *   - feat                  -> "Nuevas funcionalidades"
+ *   - fix                   -> "Correcciones"
+ *   - perf                  -> "Mejoras de rendimiento"
+ *   - refactor              -> "Cambios internos"
+ *   - docs / style / test / ci / build / chore -> "Mantenimiento" (opcional)
+ *   - BREAKING CHANGE / !   -> "Breaking changes" (siempre top de cada release)
+ *   - Sin prefijo CC válido -> "Otros" (con bandera de baja conformidad)
+ *
+ * Fallback: si la conformidad de commits es <80%, el script retorna
+ * `conformidad: <ratio>` para que el caller decida si abortar o seguir.
+ *
+ * Uso desde CLI:
+ *   node parse-commits.js [--from <ref>] [--to <ref>] [--format json|markdown]
+ *
+ * Uso programático:
+ *   const { parsearCommits, generarChangelog } = require('./parse-commits');
+ *   const { categorias, conformidad } = parsearCommits(commits);
+ *   const md = generarChangelog(categorias, { version: '1.6.5', fecha: '...' });
+ *
+ * Zero-deps. Cargado por skill `changelog-generator` y por
+ * `/swl:release` paso 7.
+ *
+ * @module habilidades/changelog-generator/scripts/parse-commits
+ */
+
+const { execSync } = require('node:child_process');
+
+// -----------------------------------------------------------------------------
+// Spec Conventional Commits
+// -----------------------------------------------------------------------------
+
+/**
+ * Regex que matchea una línea de commit Conventional Commits.
+ * Grupos: [1]=tipo, [2]=scope?, [3]=!?, [4]=descripcion
+ *
+ * Ejemplos válidos:
+ *   feat(auth): agregar validación PKCE
+ *   fix: corregir cálculo IEPS
+ *   feat!: breaking change inline
+ *   refactor(hooks/lib): split evolution-tracker
+ *   chore(release): bump version
+ *   [T-01] feat(hooks): prefijo de trazabilidad de tarea (ejecutar-fase)
+ *   [T-07][T-08] refactor(hooks): varios prefijos consecutivos
+ *   [REQ-08] feat(scripts): prefijo de requisito
+ *   [F12·T-01] feat(hooks): prefijo namespaceado por fase (DT-IDS-NAMESPACE)
+ *
+ * El prefijo opcional `[T-NN]` / `[REQ-NN]` / `[F<fase>·T-NN]` (uno o más,
+ * consecutivos) proviene de la convención de commits de
+ * `habilidades/ejecutar-fase/SKILL.md` (trazabilidad de tarea/requisito; desde
+ * la Fase 12 los IDs se namespacean por fase). No altera la semántica CC: el
+ * tipo+scope+descripción siguen presentes después del/los prefijo(s), por lo
+ * que el commit cuenta como conforme. Grupo non-capturing para no desplazar
+ * los índices [1]=tipo [2]=scope [3]=! [4]=descripcion.
+ */
+const RE_CONVENTIONAL = /^(?:\[(?:F\d+·)?(?:T|REQ)-\d+(?:-\d+)?\]\s*)*(feat|fix|perf|refactor|docs|style|test|ci|build|chore|revert|evolucion|evolve)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
+
+/** Mapa tipo CC → categoría Keep a Changelog en es-MX. */
+const CATEGORIAS = Object.freeze({
+  feat:      'Nuevas funcionalidades',
+  fix:       'Correcciones',
+  perf:      'Mejoras de rendimiento',
+  refactor:  'Cambios internos',
+  revert:    'Reversiones',
+  evolucion: 'Evoluciones de skills/agentes',
+  evolve:    'Evoluciones de skills/agentes',
+  docs:      'Mantenimiento',
+  style:     'Mantenimiento',
+  test:      'Mantenimiento',
+  ci:        'Mantenimiento',
+  build:     'Mantenimiento',
+  chore:     'Mantenimiento',
+});
+
+/** Orden de salida en CHANGELOG (Breaking siempre primero). */
+const ORDEN_CATEGORIAS = Object.freeze([
+  'Breaking changes',
+  'Nuevas funcionalidades',
+  'Correcciones',
+  'Mejoras de rendimiento',
+  'Cambios internos',
+  'Reversiones',
+  'Evoluciones de skills/agentes',
+  'Mantenimiento',
+  'Otros',
+]);
+
+// -----------------------------------------------------------------------------
+// Transformación técnica → user-facing
+// -----------------------------------------------------------------------------
+
+/**
+ * Aplica heurísticas de transformación para hacer la línea más legible al
+ * usuario final sin contradecir lo que dice el commit.
+ *
+ * Reglas conservadoras: solo elimina prefijos técnicos y normaliza la primera
+ * letra. NO inventa contenido; si la descripción es críptica, queda críptica.
+ *
+ * @param {string} descripcion - Descripción cruda del commit.
+ * @returns {string} Versión legible.
+ */
+function transformarLegible(descripcion) {
+  let texto = descripcion.trim();
+
+  // Eliminar referencias a issues al final si son ruido (#123, refs #...).
+  texto = texto.replace(/\s*\(#\d+\)\s*$/, '');
+  texto = texto.replace(/\s*[Rr]efs?:?\s*#\d+\s*$/, '');
+
+  // Capitalizar primera letra.
+  if (texto.length > 0) {
+    texto = texto[0].toUpperCase() + texto.slice(1);
+  }
+
+  // Eliminar punto final si existe (Keep a Changelog usa bullets sin punto).
+  texto = texto.replace(/\.$/, '');
+
+  return texto;
+}
+
+// -----------------------------------------------------------------------------
+// Parser principal
+// -----------------------------------------------------------------------------
+
+/**
+ * Detecta si el commit tiene marca de breaking change según el spec
+ * Conventional Commits 1.0.0:
+ *   - `!` después del tipo/scope en el subject, o
+ *   - Trailer `BREAKING CHANGE:` o `BREAKING-CHANGE:` al INICIO de una línea
+ *     del body (no en medio de prosa). El spec requiere este formato literal
+ *     como trailer; una mención de la palabra dentro de la descripción NO
+ *     dispara breaking change.
+ *
+ * Bug histórico (fix v1.6.5): la regex previa `/BREAKING\s+CHANGE/i` generaba
+ * falsos positivos cuando el commit describía features que mencionaban
+ * "breaking changes" en su prosa sin ser un breaking change ellos mismos.
+ *
+ * @param {string} mensajeCompleto - Mensaje completo del commit (subject + body).
+ * @param {string} marcaExclamacion - Match del grupo `!` del regex.
+ * @returns {boolean}
+ */
+function esBreakingChange(mensajeCompleto, marcaExclamacion) {
+  if (marcaExclamacion === '!') return true;
+  // Trailer al inicio de línea, mayúsculas obligatorias, dos puntos al final.
+  return /^BREAKING[-\s]CHANGE:/m.test(mensajeCompleto);
+}
+
+/**
+ * Parsea una lista de commits y los clasifica.
+ *
+ * @param {Array<{hash: string, subject: string, body?: string}>} commits
+ * @returns {{
+ *   categorias: Map<string, Array<{hash: string, descripcion: string, scope?: string}>>,
+ *   conformidad: number,
+ *   totalCommits: number,
+ *   conformes: number,
+ * }}
+ */
+function parsearCommits(commits) {
+  const categorias = new Map();
+  for (const cat of ORDEN_CATEGORIAS) categorias.set(cat, []);
+
+  let conformes = 0;
+
+  for (const commit of commits) {
+    const { hash, subject = '', body = '' } = commit;
+    const completo = `${subject}\n${body}`;
+    const match = subject.match(RE_CONVENTIONAL);
+
+    if (!match) {
+      categorias.get('Otros').push({
+        hash,
+        descripcion: transformarLegible(subject),
+      });
+      continue;
+    }
+
+    conformes += 1;
+    const [, tipo, scope, marca, descripcion] = match;
+    const entrada = {
+      hash,
+      descripcion: transformarLegible(descripcion),
+      scope: scope || null,
+    };
+
+    // Breaking change tiene precedencia sobre la categoría natural.
+    if (esBreakingChange(completo, marca)) {
+      categorias.get('Breaking changes').push(entrada);
+      continue;
+    }
+
+    const categoria = CATEGORIAS[tipo] || 'Otros';
+    categorias.get(categoria).push(entrada);
+  }
+
+  return {
+    categorias,
+    conformidad: commits.length === 0 ? 1 : conformes / commits.length,
+    totalCommits: commits.length,
+    conformes,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Lectura desde git
+// -----------------------------------------------------------------------------
+
+/**
+ * Obtiene commits desde git en formato estructurado.
+ *
+ * @param {object} opts
+ * @param {string} [opts.from] - Ref inicial (default: última tag).
+ * @param {string} [opts.to='HEAD'] - Ref final.
+ * @param {string} [opts.cwd] - Directorio del repo.
+ * @returns {Array<{hash: string, subject: string, body: string}>}
+ */
+function leerCommitsGit(opts = {}) {
+  const { from, to = 'HEAD', cwd = process.cwd() } = opts;
+
+  let rango;
+  if (from) {
+    rango = `${from}..${to}`;
+  } else {
+    // Default: desde la última tag (si existe) o desde el initial commit.
+    try {
+      const ultimaTag = execSync('git describe --tags --abbrev=0', {
+        cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'],
+      }).trim();
+      rango = `${ultimaTag}..${to}`;
+    } catch {
+      rango = to;
+    }
+  }
+
+  // Separador único para parsear subject + body (que puede ser multi-línea).
+  const SEP = '<<<COMMIT-SWL-SEP>>>';
+  const FIELD = '<<<FIELD-SEP>>>';
+  const formato = `%H${FIELD}%s${FIELD}%b${SEP}`;
+
+  let salida;
+  try {
+    salida = execSync(`git log ${rango} --format=${JSON.stringify(formato)}`, {
+      cwd, encoding: 'utf8',
+    });
+  } catch {
+    return [];
+  }
+
+  return salida
+    .split(SEP)
+    .map(s => s.trim())
+    .filter(Boolean)
+    .map(linea => {
+      const [hash, subject, body] = linea.split(FIELD);
+      return {
+        hash: (hash || '').trim(),
+        subject: (subject || '').trim(),
+        body: (body || '').trim(),
+      };
+    })
+    .filter(c => c.hash);
+}
+
+// -----------------------------------------------------------------------------
+// Generación de markdown
+// -----------------------------------------------------------------------------
+
+/**
+ * Genera la entrada de CHANGELOG en formato Keep a Changelog.
+ *
+ * @param {Map<string, Array>} categorias
+ * @param {object} opts
+ * @param {string} opts.version - Ej: '1.6.5'
+ * @param {string} [opts.fecha] - Default: hoy en formato YYYY-MM-DD
+ * @param {boolean} [opts.incluirHash=true] - Mostrar hash corto al inicio de cada bullet.
+ * @returns {string}
+ */
+function generarChangelog(categorias, opts) {
+  const { version, fecha, incluirHash = true } = opts || {};
+  if (!version) throw new Error('generarChangelog: version es obligatoria');
+
+  const fechaUsada = fecha || new Date().toISOString().slice(0, 10);
+  const lineas = [`## [${version}] - ${fechaUsada}`, ''];
+
+  for (const categoria of ORDEN_CATEGORIAS) {
+    const entradas = categorias.get(categoria) || [];
+    if (entradas.length === 0) continue;
+
+    lineas.push(`### ${categoria}`);
+    lineas.push('');
+    for (const entrada of entradas) {
+      const hashCorto = incluirHash && entrada.hash
+        ? `${entrada.hash.slice(0, 7)} `
+        : '';
+      const scope = entrada.scope ? `**${entrada.scope}**: ` : '';
+      lineas.push(`- ${hashCorto}${scope}${entrada.descripcion}`);
+    }
+    lineas.push('');
+  }
+
+  return lineas.join('\n');
+}
+
+// -----------------------------------------------------------------------------
+// CLI
+// -----------------------------------------------------------------------------
+
+function _parseFlags(argv) {
+  const flags = { format: 'markdown' };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--from' && argv[i + 1]) { flags.from = argv[++i]; continue; }
+    if (argv[i] === '--to' && argv[i + 1])   { flags.to   = argv[++i]; continue; }
+    if (argv[i] === '--format' && argv[i + 1]) { flags.format = argv[++i]; continue; }
+    if (argv[i] === '--version' && argv[i + 1]) { flags.version = argv[++i]; continue; }
+  }
+  return flags;
+}
+
+if (require.main === module) {
+  const flags = _parseFlags(process.argv);
+  const commits = leerCommitsGit({ from: flags.from, to: flags.to });
+  const resultado = parsearCommits(commits);
+
+  if (flags.format === 'json') {
+    process.stdout.write(JSON.stringify({
+      ...resultado,
+      categorias: Object.fromEntries(resultado.categorias),
+    }, null, 2));
+  } else {
+    if (!flags.version) {
+      process.stderr.write('ERROR: --version requerido para format=markdown\n');
+      process.exit(1);
+    }
+    process.stdout.write(generarChangelog(resultado.categorias, {
+      version: flags.version,
+    }));
+  }
+  process.stdout.write('\n');
+
+  if (resultado.conformidad < 0.8) {
+    process.stderr.write(
+      `\nADVERTENCIA: conformidad Conventional Commits = ${(resultado.conformidad * 100).toFixed(1)}% ` +
+      `(${resultado.conformes}/${resultado.totalCommits}). ` +
+      `Revisar bloque "Otros" antes de publicar.\n`,
+    );
+  }
+}
+
+module.exports = {
+  parsearCommits,
+  leerCommitsGit,
+  generarChangelog,
+  transformarLegible,
+  esBreakingChange,
+  RE_CONVENTIONAL,
+  CATEGORIAS,
+  ORDEN_CATEGORIAS,
+};