@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/lib/git-metricas.js

@@ -1,257 +1,257 @@
-'use strict';
-
-/**
- * git-metricas.js
- *
- * Métricas DORA derivables SOLO de git (sin CI), para el proyecto destino donde
- * SWL está instalado:
- *   - deployment frequency: tags de release en una ventana -> deploys/semana.
- *   - lead time for changes: commit más antiguo desde el release previo -> tag
- *     actual (p50/p95).
- *   - detección de degradación de entrega: compara ventana actual vs previa
- *     (consumido por el recolector del briefing — git-only, <200ms, NUNCA gh).
- *
- * "deployment" = tag de release que matchea `patronTag` (default /^v?\d+\.\d+\.\d+/).
- *
- * Funciones puras zero-deps. git vía execFileSync sin shell, con try/catch que
- * degrada a `{disponible:false}` (no es repo) o a 0/sinDatos (repo sin tags).
- * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
- */
-
-const { execFileSync } = require('node:child_process');
-
-const PATRON_TAG_DEFAULT = /^v?\d+\.\d+\.\d+/;
-// Rango git válido: prohíbe `-` inicial en cada extremo (defensa en profundidad
-// contra un refname que git interpretaría como flag de `git log`). Los nombres
-// vienen de `git for-each-ref` —git ya rechaza refs con `-` inicial—, pero la
-// validación local cierra el hueco si el origen del rango cambiara (H-02).
-const RE_RANGO_VALIDO =
-  /^(?!-)[A-Za-z0-9_./@~^][A-Za-z0-9_./@~^-]*(\.\.\.?(?!-)[A-Za-z0-9_./@~^][A-Za-z0-9_./@~^-]*)?$/;
-const MS_DIA = 24 * 60 * 60 * 1000;
-const MS_HORA = 60 * 60 * 1000;
-const GIT_MAX_BUFFER = 8 * 1024 * 1024; // 8 MiB
-const GIT_TIMEOUT_MS = 5000; // evita hangs (H-04); el recolector del briefing degrada si git cuelga
-
-function _git(baseDir, args) {
-  return execFileSync('git', args, {
-    cwd: baseDir,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'ignore'],
-    maxBuffer: GIT_MAX_BUFFER,
-    timeout: GIT_TIMEOUT_MS,
-  });
-}
-
-/**
- * Lista tags que matchean patronTag con su fecha de creación.
- * @returns {Array<{name:string, date:Date}>|null} null si no es repo git.
- */
-function _gitTagsConFecha(baseDir, patronTag = PATRON_TAG_DEFAULT) {
-  let salida;
-  try {
-    salida = _git(baseDir, [
-      'for-each-ref',
-      '--sort=creatordate',
-      '--format=%(refname:short)|%(creatordate:iso-strict)',
-      'refs/tags',
-    ]);
-  } catch {
-    return null; // no es repo git / git no disponible
-  }
-  const tags = [];
-  for (const linea of salida.split('\n')) {
-    const l = linea.trim();
-    if (!l) continue;
-    const sep = l.lastIndexOf('|');
-    if (sep === -1) continue;
-    const name = l.slice(0, sep);
-    const iso = l.slice(sep + 1);
-    if (!patronTag.test(name)) continue;
-    const t = Date.parse(iso);
-    if (!Number.isFinite(t)) continue;
-    tags.push({ name, date: new Date(t) });
-  }
-  tags.sort((a, b) => a.date - b.date);
-  return tags;
-}
-
-/** ISO del commit más antiguo (primero) de un rango git, o null. */
-function _primerCommitISO(baseDir, rango) {
-  if (!RE_RANGO_VALIDO.test(rango)) return null;
-  let salida;
-  try {
-    salida = _git(baseDir, ['log', rango, '--reverse', '--format=%cI', '--']);
-  } catch {
-    return null;
-  }
-  const primera = salida.split('\n').map((s) => s.trim()).filter(Boolean)[0];
-  return primera || null;
-}
-
-// Nearest-rank (ceil), no interpolación. Con 2 muestras [a,b] y p=50 → a.
-function _percentil(valoresOrdenados, p) {
-  if (valoresOrdenados.length === 0) return null;
-  const idx = Math.ceil((p / 100) * valoresOrdenados.length) - 1;
-  return valoresOrdenados[Math.max(0, Math.min(idx, valoresOrdenados.length - 1))];
-}
-
-function _enVentana(date, desde, hasta) {
-  return date >= desde && date <= hasta;
-}
-
-/**
- * Deployment frequency en la ventana.
- * @returns {{disponible:boolean, totalDeploys?:number, deploysPorSemana?:number,
- *            sinDatos?:boolean, razon?:string}}
- */
-function deploymentFrequency(baseDir, opts = {}) {
-  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
-  const tags = _gitTagsConFecha(baseDir, patronTag);
-  if (tags === null) return { disponible: false, razon: 'no es un repositorio git' };
-
-  const desde = new Date(hoy.getTime() - ventanaDias * MS_DIA);
-  const enVentana = tags.filter((t) => _enVentana(t.date, desde, hoy));
-  const semanas = ventanaDias / 7;
-  return {
-    disponible: true,
-    totalDeploys: enVentana.length,
-    deploysPorSemana: semanas > 0 ? enVentana.length / semanas : 0,
-    sinDatos: tags.length === 0,
-  };
-}
-
-/** Lead times (horas) commit->tag para tags en [desde,hasta]. */
-function _leadTimesEnVentana(baseDir, tags, desde, hasta) {
-  const horas = [];
-  for (let i = 0; i < tags.length; i++) {
-    const tag = tags[i];
-    if (!_enVentana(tag.date, desde, hasta)) continue;
-    const prev = tags[i - 1];
-    const rango = prev ? `${prev.name}..${tag.name}` : tag.name;
-    const primeroISO = _primerCommitISO(baseDir, rango);
-    if (!primeroISO) continue;
-    const t = Date.parse(primeroISO);
-    if (!Number.isFinite(t)) continue;
-    const h = (tag.date.getTime() - t) / MS_HORA;
-    if (h >= 0) horas.push(h);
-  }
-  return horas.sort((a, b) => a - b);
-}
-
-/**
- * Lead time for changes (commit->tag) en la ventana.
- * @returns {{disponible:boolean, p50Horas?:number, p95Horas?:number,
- *            muestras?:number, sinDatos?:boolean, razon?:string}}
- */
-function leadTimeForChanges(baseDir, opts = {}) {
-  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
-  const tags = _gitTagsConFecha(baseDir, patronTag);
-  if (tags === null) return { disponible: false, razon: 'no es un repositorio git' };
-
-  const desde = new Date(hoy.getTime() - ventanaDias * MS_DIA);
-  const horas = _leadTimesEnVentana(baseDir, tags, desde, hoy);
-  if (horas.length === 0) {
-    return { disponible: true, sinDatos: true, muestras: 0, p50Horas: null, p95Horas: null };
-  }
-  return {
-    disponible: true,
-    sinDatos: false,
-    muestras: horas.length,
-    p50Horas: _percentil(horas, 50),
-    p95Horas: _percentil(horas, 95),
-  };
-}
-
-/**
- * Detecta degradación de entrega comparando la ventana actual vs la previa de
- * igual duración. Git-only y rápido — apto para el recolector del briefing.
- * Degradación = deploy freq cae >50% O lead time mediano sube >50%.
- * @returns {{disponible:boolean, degradado:boolean, motivo:(string|null),
- *            deployFreqActual:number, deployFreqPrevia:number,
- *            leadTimeP50Actual:(number|null), leadTimeP50Previo:(number|null)}}
- */
-function detectarDegradacionEntrega(baseDir, opts = {}) {
-  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
-  const tags = _gitTagsConFecha(baseDir, patronTag);
-  if (tags === null) {
-    return {
-      disponible: false,
-      degradado: false,
-      motivo: null,
-      deployFreqActual: 0,
-      deployFreqPrevia: 0,
-      leadTimeP50Actual: null,
-      leadTimeP50Previo: null,
-    };
-  }
-
-  const finActual = hoy;
-  const inicioActual = new Date(hoy.getTime() - ventanaDias * MS_DIA);
-  const inicioPrevio = new Date(hoy.getTime() - 2 * ventanaDias * MS_DIA);
-  const semanas = ventanaDias / 7;
-
-  const deploysActual = tags.filter((t) => _enVentana(t.date, inicioActual, finActual)).length;
-  const deploysPrevio = tags.filter((t) => _enVentana(t.date, inicioPrevio, inicioActual)).length;
-  const deployFreqActual = semanas > 0 ? deploysActual / semanas : 0;
-  const deployFreqPrevia = semanas > 0 ? deploysPrevio / semanas : 0;
-
-  const ltActual = _percentil(_leadTimesEnVentana(baseDir, tags, inicioActual, finActual), 50);
-  const ltPrevio = _percentil(_leadTimesEnVentana(baseDir, tags, inicioPrevio, inicioActual), 50);
-
-  const motivos = [];
-  if (deployFreqPrevia > 0 && deployFreqActual < deployFreqPrevia * 0.5) {
-    motivos.push(
-      `deployment frequency cayó >50% (${deployFreqPrevia.toFixed(2)} → ${deployFreqActual.toFixed(2)} deploys/semana)`
-    );
-  }
-  if (ltPrevio !== null && ltActual !== null && ltActual > ltPrevio * 1.5) {
-    motivos.push(
-      `lead time mediano subió >50% (${ltPrevio.toFixed(1)}h → ${ltActual.toFixed(1)}h)`
-    );
-  }
-
-  return {
-    disponible: true,
-    degradado: motivos.length > 0,
-    motivo: motivos.length > 0 ? motivos.join('; ') : null,
-    deployFreqActual,
-    deployFreqPrevia,
-    leadTimeP50Actual: ltActual,
-    leadTimeP50Previo: ltPrevio,
-  };
-}
-
-module.exports = {
-  deploymentFrequency,
-  leadTimeForChanges,
-  detectarDegradacionEntrega,
-  PATRON_TAG_DEFAULT,
-  _gitTagsConFecha,
-};
-
-// Entrypoint CLI: node scripts/lib/git-metricas.js [--json] [--dias=N] [baseDir]
-if (!require.main || require.main === module) {
-  const args = process.argv.slice(2);
-  const json = args.includes('--json');
-  const diasArg = args.find((a) => a.startsWith('--dias='));
-  const ventanaDias = Math.max(1, Math.min(365, (diasArg ? parseInt(diasArg.slice('--dias='.length), 10) : 30) || 30));
-  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
-
-  const out = {
-    ventana_dias: ventanaDias,
-    deploymentFrequency: deploymentFrequency(baseDir, { ventanaDias }),
-    leadTime: leadTimeForChanges(baseDir, { ventanaDias }),
-    degradacion: detectarDegradacionEntrega(baseDir, { ventanaDias }),
-  };
-
-  if (json) {
-    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
-  } else {
-    const df = out.deploymentFrequency;
-    const lt = out.leadTime;
-    process.stdout.write(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : df.deploysPorSemana.toFixed(2) + ' deploys/semana') : 'no disponible'}\n`);
-    process.stdout.write(`Lead time (p50/p95): ${lt.disponible && !lt.sinDatos ? `${lt.p50Horas.toFixed(1)}h / ${lt.p95Horas.toFixed(1)}h` : 'sin datos'}\n`);
-    process.stdout.write(`Degradación: ${out.degradacion.degradado ? out.degradacion.motivo : 'no'}\n`);
-  }
-  process.exit(0);
-}
+'use strict';
+
+/**
+ * git-metricas.js
+ *
+ * Métricas DORA derivables SOLO de git (sin CI), para el proyecto destino donde
+ * SWL está instalado:
+ *   - deployment frequency: tags de release en una ventana -> deploys/semana.
+ *   - lead time for changes: commit más antiguo desde el release previo -> tag
+ *     actual (p50/p95).
+ *   - detección de degradación de entrega: compara ventana actual vs previa
+ *     (consumido por el recolector del briefing — git-only, <200ms, NUNCA gh).
+ *
+ * "deployment" = tag de release que matchea `patronTag` (default /^v?\d+\.\d+\.\d+/).
+ *
+ * Funciones puras zero-deps. git vía execFileSync sin shell, con try/catch que
+ * degrada a `{disponible:false}` (no es repo) o a 0/sinDatos (repo sin tags).
+ * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
+ */
+
+const { execFileSync } = require('node:child_process');
+
+const PATRON_TAG_DEFAULT = /^v?\d+\.\d+\.\d+/;
+// Rango git válido: prohíbe `-` inicial en cada extremo (defensa en profundidad
+// contra un refname que git interpretaría como flag de `git log`). Los nombres
+// vienen de `git for-each-ref` —git ya rechaza refs con `-` inicial—, pero la
+// validación local cierra el hueco si el origen del rango cambiara (H-02).
+const RE_RANGO_VALIDO =
+  /^(?!-)[A-Za-z0-9_./@~^][A-Za-z0-9_./@~^-]*(\.\.\.?(?!-)[A-Za-z0-9_./@~^][A-Za-z0-9_./@~^-]*)?$/;
+const MS_DIA = 24 * 60 * 60 * 1000;
+const MS_HORA = 60 * 60 * 1000;
+const GIT_MAX_BUFFER = 8 * 1024 * 1024; // 8 MiB
+const GIT_TIMEOUT_MS = 5000; // evita hangs (H-04); el recolector del briefing degrada si git cuelga
+
+function _git(baseDir, args) {
+  return execFileSync('git', args, {
+    cwd: baseDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: GIT_MAX_BUFFER,
+    timeout: GIT_TIMEOUT_MS,
+  });
+}
+
+/**
+ * Lista tags que matchean patronTag con su fecha de creación.
+ * @returns {Array<{name:string, date:Date}>|null} null si no es repo git.
+ */
+function _gitTagsConFecha(baseDir, patronTag = PATRON_TAG_DEFAULT) {
+  let salida;
+  try {
+    salida = _git(baseDir, [
+      'for-each-ref',
+      '--sort=creatordate',
+      '--format=%(refname:short)|%(creatordate:iso-strict)',
+      'refs/tags',
+    ]);
+  } catch {
+    return null; // no es repo git / git no disponible
+  }
+  const tags = [];
+  for (const linea of salida.split('\n')) {
+    const l = linea.trim();
+    if (!l) continue;
+    const sep = l.lastIndexOf('|');
+    if (sep === -1) continue;
+    const name = l.slice(0, sep);
+    const iso = l.slice(sep + 1);
+    if (!patronTag.test(name)) continue;
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t)) continue;
+    tags.push({ name, date: new Date(t) });
+  }
+  tags.sort((a, b) => a.date - b.date);
+  return tags;
+}
+
+/** ISO del commit más antiguo (primero) de un rango git, o null. */
+function _primerCommitISO(baseDir, rango) {
+  if (!RE_RANGO_VALIDO.test(rango)) return null;
+  let salida;
+  try {
+    salida = _git(baseDir, ['log', rango, '--reverse', '--format=%cI', '--']);
+  } catch {
+    return null;
+  }
+  const primera = salida.split('\n').map((s) => s.trim()).filter(Boolean)[0];
+  return primera || null;
+}
+
+// Nearest-rank (ceil), no interpolación. Con 2 muestras [a,b] y p=50 → a.
+function _percentil(valoresOrdenados, p) {
+  if (valoresOrdenados.length === 0) return null;
+  const idx = Math.ceil((p / 100) * valoresOrdenados.length) - 1;
+  return valoresOrdenados[Math.max(0, Math.min(idx, valoresOrdenados.length - 1))];
+}
+
+function _enVentana(date, desde, hasta) {
+  return date >= desde && date <= hasta;
+}
+
+/**
+ * Deployment frequency en la ventana.
+ * @returns {{disponible:boolean, totalDeploys?:number, deploysPorSemana?:number,
+ *            sinDatos?:boolean, razon?:string}}
+ */
+function deploymentFrequency(baseDir, opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
+  const tags = _gitTagsConFecha(baseDir, patronTag);
+  if (tags === null) return { disponible: false, razon: 'no es un repositorio git' };
+
+  const desde = new Date(hoy.getTime() - ventanaDias * MS_DIA);
+  const enVentana = tags.filter((t) => _enVentana(t.date, desde, hoy));
+  const semanas = ventanaDias / 7;
+  return {
+    disponible: true,
+    totalDeploys: enVentana.length,
+    deploysPorSemana: semanas > 0 ? enVentana.length / semanas : 0,
+    sinDatos: tags.length === 0,
+  };
+}
+
+/** Lead times (horas) commit->tag para tags en [desde,hasta]. */
+function _leadTimesEnVentana(baseDir, tags, desde, hasta) {
+  const horas = [];
+  for (let i = 0; i < tags.length; i++) {
+    const tag = tags[i];
+    if (!_enVentana(tag.date, desde, hasta)) continue;
+    const prev = tags[i - 1];
+    const rango = prev ? `${prev.name}..${tag.name}` : tag.name;
+    const primeroISO = _primerCommitISO(baseDir, rango);
+    if (!primeroISO) continue;
+    const t = Date.parse(primeroISO);
+    if (!Number.isFinite(t)) continue;
+    const h = (tag.date.getTime() - t) / MS_HORA;
+    if (h >= 0) horas.push(h);
+  }
+  return horas.sort((a, b) => a - b);
+}
+
+/**
+ * Lead time for changes (commit->tag) en la ventana.
+ * @returns {{disponible:boolean, p50Horas?:number, p95Horas?:number,
+ *            muestras?:number, sinDatos?:boolean, razon?:string}}
+ */
+function leadTimeForChanges(baseDir, opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
+  const tags = _gitTagsConFecha(baseDir, patronTag);
+  if (tags === null) return { disponible: false, razon: 'no es un repositorio git' };
+
+  const desde = new Date(hoy.getTime() - ventanaDias * MS_DIA);
+  const horas = _leadTimesEnVentana(baseDir, tags, desde, hoy);
+  if (horas.length === 0) {
+    return { disponible: true, sinDatos: true, muestras: 0, p50Horas: null, p95Horas: null };
+  }
+  return {
+    disponible: true,
+    sinDatos: false,
+    muestras: horas.length,
+    p50Horas: _percentil(horas, 50),
+    p95Horas: _percentil(horas, 95),
+  };
+}
+
+/**
+ * Detecta degradación de entrega comparando la ventana actual vs la previa de
+ * igual duración. Git-only y rápido — apto para el recolector del briefing.
+ * Degradación = deploy freq cae >50% O lead time mediano sube >50%.
+ * @returns {{disponible:boolean, degradado:boolean, motivo:(string|null),
+ *            deployFreqActual:number, deployFreqPrevia:number,
+ *            leadTimeP50Actual:(number|null), leadTimeP50Previo:(number|null)}}
+ */
+function detectarDegradacionEntrega(baseDir, opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), patronTag = PATRON_TAG_DEFAULT } = opts;
+  const tags = _gitTagsConFecha(baseDir, patronTag);
+  if (tags === null) {
+    return {
+      disponible: false,
+      degradado: false,
+      motivo: null,
+      deployFreqActual: 0,
+      deployFreqPrevia: 0,
+      leadTimeP50Actual: null,
+      leadTimeP50Previo: null,
+    };
+  }
+
+  const finActual = hoy;
+  const inicioActual = new Date(hoy.getTime() - ventanaDias * MS_DIA);
+  const inicioPrevio = new Date(hoy.getTime() - 2 * ventanaDias * MS_DIA);
+  const semanas = ventanaDias / 7;
+
+  const deploysActual = tags.filter((t) => _enVentana(t.date, inicioActual, finActual)).length;
+  const deploysPrevio = tags.filter((t) => _enVentana(t.date, inicioPrevio, inicioActual)).length;
+  const deployFreqActual = semanas > 0 ? deploysActual / semanas : 0;
+  const deployFreqPrevia = semanas > 0 ? deploysPrevio / semanas : 0;
+
+  const ltActual = _percentil(_leadTimesEnVentana(baseDir, tags, inicioActual, finActual), 50);
+  const ltPrevio = _percentil(_leadTimesEnVentana(baseDir, tags, inicioPrevio, inicioActual), 50);
+
+  const motivos = [];
+  if (deployFreqPrevia > 0 && deployFreqActual < deployFreqPrevia * 0.5) {
+    motivos.push(
+      `deployment frequency cayó >50% (${deployFreqPrevia.toFixed(2)} → ${deployFreqActual.toFixed(2)} deploys/semana)`
+    );
+  }
+  if (ltPrevio !== null && ltActual !== null && ltActual > ltPrevio * 1.5) {
+    motivos.push(
+      `lead time mediano subió >50% (${ltPrevio.toFixed(1)}h → ${ltActual.toFixed(1)}h)`
+    );
+  }
+
+  return {
+    disponible: true,
+    degradado: motivos.length > 0,
+    motivo: motivos.length > 0 ? motivos.join('; ') : null,
+    deployFreqActual,
+    deployFreqPrevia,
+    leadTimeP50Actual: ltActual,
+    leadTimeP50Previo: ltPrevio,
+  };
+}
+
+module.exports = {
+  deploymentFrequency,
+  leadTimeForChanges,
+  detectarDegradacionEntrega,
+  PATRON_TAG_DEFAULT,
+  _gitTagsConFecha,
+};
+
+// Entrypoint CLI: node scripts/lib/git-metricas.js [--json] [--dias=N] [baseDir]
+if (!require.main || require.main === module) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const diasArg = args.find((a) => a.startsWith('--dias='));
+  const ventanaDias = Math.max(1, Math.min(365, (diasArg ? parseInt(diasArg.slice('--dias='.length), 10) : 30) || 30));
+  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
+
+  const out = {
+    ventana_dias: ventanaDias,
+    deploymentFrequency: deploymentFrequency(baseDir, { ventanaDias }),
+    leadTime: leadTimeForChanges(baseDir, { ventanaDias }),
+    degradacion: detectarDegradacionEntrega(baseDir, { ventanaDias }),
+  };
+
+  if (json) {
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  } else {
+    const df = out.deploymentFrequency;
+    const lt = out.leadTime;
+    process.stdout.write(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : df.deploysPorSemana.toFixed(2) + ' deploys/semana') : 'no disponible'}\n`);
+    process.stdout.write(`Lead time (p50/p95): ${lt.disponible && !lt.sinDatos ? `${lt.p50Horas.toFixed(1)}h / ${lt.p95Horas.toFixed(1)}h` : 'sin datos'}\n`);
+    process.stdout.write(`Degradación: ${out.degradacion.degradado ? out.degradacion.motivo : 'no'}\n`);
+  }
+  process.exit(0);
+}