@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/lib/metricas-dora.js

@@ -1,204 +1,204 @@
-'use strict';
-
-/**
- * metricas-dora.js
- *
- * Compone las 4 métricas DORA del proyecto destino y las clasifica en
- * elite/high/medium/low según los umbrales del DORA Report 2023:
- *   - deployment frequency + lead time desde git (siempre, git-metricas.js).
- *   - change failure rate + MTTR desde gh (degrada si ausente, ci-reader.js).
- *
- * Persiste el informe en `.planning/evolution/metricas-dora.json` (runtime).
- * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const gitMetricas = require('./git-metricas');
-const ciReader = require('./ci-reader');
-
-let atomicWriteJSON;
-try {
-  ({ atomicWriteJSON } = require('../../hooks/lib/atomic-write'));
-} catch (err) {
-  if (err.code !== 'MODULE_NOT_FOUND') throw err;
-  atomicWriteJSON = (p, obj) => {
-    const dir = path.dirname(p);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
-  };
-}
-
-const STORAGE_REL = path.join('.planning', 'evolution', 'metricas-dora.json');
-
-/**
- * Umbrales DORA Report 2023 (Accelerate State of DevOps). Boundaries expresados
- * en las unidades internas de cada métrica. Ajustar aquí si el reporte cambia.
- *
- * - deploymentFrequency (deploys/semana, mayor es mejor):
- *   elite ≥1/día (7/sem) · high ≥1/mes (0.23/sem) · medium ≥1/semestre (0.038/sem) · low <semestral.
- * - leadTimeHoras (commit→tag, menor es mejor): elite <1día · high <1sem · medium <1mes · low ≥1mes.
- * - changeFailureRate (0..1, menor es mejor): elite ≤0.15 · high ≤0.30 · medium ≤0.45 · low >0.45.
- * - mttrHoras (menor es mejor): elite <1h · high <1día · medium <1sem · low ≥1sem.
- */
-const UMBRALES_DORA_2023 = {
-  deploymentFrequency: { elite: 7, high: 0.23, medium: 0.038 }, // deploys/semana, mayor mejor
-  leadTimeHoras: { elite: 24, high: 168, medium: 730 }, // menor mejor
-  changeFailureRate: { elite: 0.15, high: 0.3, medium: 0.45 }, // menor mejor
-  mttrHoras: { elite: 1, high: 24, medium: 168 }, // menor mejor
-};
-
-const NIVELES = ['elite', 'high', 'medium', 'low'];
-
-/**
- * Clasifica un valor de una métrica en elite/high/medium/low.
- * @param {string} metrica - clave de UMBRALES_DORA_2023.
- * @param {number|null|undefined} valor
- * @returns {'elite'|'high'|'medium'|'low'|'sin-datos'}
- */
-function clasificar(metrica, valor) {
-  const u = UMBRALES_DORA_2023[metrica];
-  if (!u || valor === null || valor === undefined || !Number.isFinite(valor)) return 'sin-datos';
-
-  if (metrica === 'deploymentFrequency') {
-    // mayor es mejor
-    if (valor >= u.elite) return 'elite';
-    if (valor >= u.high) return 'high';
-    if (valor >= u.medium) return 'medium';
-    return 'low';
-  }
-  // menor es mejor (leadTime, cfr, mttr)
-  if (valor < u.elite) return 'elite';
-  if (valor < u.high) return 'high';
-  if (valor < u.medium) return 'medium';
-  return 'low';
-}
-
-/**
- * Calcula las 4 métricas DORA del proyecto en baseDir.
- * @returns objeto serializable con generado, ventana_dias y las 4 métricas.
- */
-function calcularDora(baseDir = process.cwd(), opts = {}) {
-  const { ventanaDias = 30, hoy = new Date(), ejecutorGh } = opts;
-
-  // Git (siempre)
-  const df = gitMetricas.deploymentFrequency(baseDir, { ventanaDias, hoy });
-  const lt = gitMetricas.leadTimeForChanges(baseDir, { ventanaDias, hoy });
-
-  // CI (degrada): una sola llamada a gh. Si no está disponible, NO se re-intenta
-  // — se propaga la razón directamente (evita 3 invocaciones del mismo fallo).
-  const runsBase = ciReader.obtenerRuns({ ejecutorGh, rama: 'main' });
-  const cfr = runsBase.disponible
-    ? ciReader.changeFailureRate({ ventanaDias, hoy, runs: runsBase.runs })
-    : { disponible: false, razon: runsBase.razon };
-  const mttr = runsBase.disponible
-    ? ciReader.meanTimeToRestore({ ventanaDias, hoy, runs: runsBase.runs })
-    : { disponible: false, razon: runsBase.razon };
-
-  const deploymentFrequency = df.disponible
-    ? {
-        disponible: true,
-        valor: df.sinDatos ? null : df.deploysPorSemana,
-        unidad: 'deploys/semana',
-        clasificacion: df.sinDatos ? 'sin-datos' : clasificar('deploymentFrequency', df.deploysPorSemana),
-        sinDatos: !!df.sinDatos,
-      }
-    : { disponible: false, razon: df.razon };
-
-  const leadTime = lt.disponible
-    ? {
-        disponible: true,
-        p50Horas: lt.sinDatos ? null : lt.p50Horas,
-        p95Horas: lt.sinDatos ? null : lt.p95Horas,
-        clasificacion: lt.sinDatos ? 'sin-datos' : clasificar('leadTimeHoras', lt.p50Horas),
-        sinDatos: !!lt.sinDatos,
-      }
-    : { disponible: false, razon: lt.razon };
-
-  const changeFailureRate = cfr.disponible
-    ? {
-        disponible: true,
-        valor: cfr.sinDatos ? null : cfr.cfr,
-        clasificacion: cfr.sinDatos ? 'sin-datos' : clasificar('changeFailureRate', cfr.cfr),
-        sinDatos: !!cfr.sinDatos,
-        totalRuns: cfr.totalRuns,
-        fallidos: cfr.fallidos,
-      }
-    : { disponible: false, razon: cfr.razon };
-
-  const mttrOut = mttr.disponible
-    ? {
-        disponible: true,
-        mttrHoras: mttr.sinDatos ? null : mttr.mttrHoras,
-        clasificacion: mttr.sinDatos ? 'sin-datos' : clasificar('mttrHoras', mttr.mttrHoras),
-        sinDatos: !!mttr.sinDatos,
-        recuperaciones: mttr.recuperaciones,
-      }
-    : { disponible: false, razon: mttr.razon };
-
-  return {
-    generado: hoy.toISOString(),
-    ventana_dias: ventanaDias,
-    deploymentFrequency,
-    leadTime,
-    changeFailureRate,
-    mttr: mttrOut,
-  };
-}
-
-/**
- * Persiste el informe DORA en `<baseDir>/.planning/evolution/metricas-dora.json`.
- * `baseDir` se trata como ruta CONFIABLE del invocador (CLI local / cwd); NUNCA
- * debe propagarse desde input web/HTTP/PR. Aun así se valida contención bajo
- * baseDir para evitar write-anywhere si el path subiera de nivel (H-01).
- */
-function persistir(baseDir, dora) {
-  const base = path.resolve(baseDir);
-  const destino = path.resolve(base, STORAGE_REL);
-  if (destino !== base && !destino.startsWith(base + path.sep)) {
-    throw new Error('destino de métricas DORA fuera de baseDir');
-  }
-  atomicWriteJSON(destino, dora);
-  return destino;
-}
-
-module.exports = {
-  clasificar,
-  calcularDora,
-  persistir,
-  UMBRALES_DORA_2023,
-  NIVELES,
-  STORAGE_REL,
-};
-
-// Entrypoint CLI: node scripts/lib/metricas-dora.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 dora = calcularDora(baseDir, { ventanaDias });
-  try {
-    persistir(baseDir, dora);
-  } catch {
-    /* persistencia best-effort: no romper el informe si el disco falla */
-  }
-
-  if (json) {
-    process.stdout.write(JSON.stringify(dora, null, 2) + '\n');
-  } else {
-    const fmt = (txt) => process.stdout.write(`${txt}\n`);
-    const df = dora.deploymentFrequency;
-    const lt = dora.leadTime;
-    const cfr = dora.changeFailureRate;
-    const mt = dora.mttr;
-    fmt(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : `${df.valor.toFixed(2)}/sem [${df.clasificacion}]`) : 'no disponible'}`);
-    fmt(`Lead time (p50): ${lt.disponible ? (lt.sinDatos ? 'sin datos' : `${lt.p50Horas.toFixed(1)}h [${lt.clasificacion}]`) : 'no disponible'}`);
-    fmt(`Change failure rate: ${cfr.disponible ? (cfr.sinDatos ? 'sin datos' : `${(cfr.valor * 100).toFixed(1)}% [${cfr.clasificacion}]`) : 'no disponible (gh ausente)'}`);
-    fmt(`MTTR: ${mt.disponible ? (mt.sinDatos ? 'sin datos' : `${mt.mttrHoras.toFixed(1)}h [${mt.clasificacion}]`) : 'no disponible (gh ausente)'}`);
-  }
-  process.exit(0);
-}
+'use strict';
+
+/**
+ * metricas-dora.js
+ *
+ * Compone las 4 métricas DORA del proyecto destino y las clasifica en
+ * elite/high/medium/low según los umbrales del DORA Report 2023:
+ *   - deployment frequency + lead time desde git (siempre, git-metricas.js).
+ *   - change failure rate + MTTR desde gh (degrada si ausente, ci-reader.js).
+ *
+ * Persiste el informe en `.planning/evolution/metricas-dora.json` (runtime).
+ * Entrypoint CLI `--json`. Parte de la Fase 15 (ADR-0039).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const gitMetricas = require('./git-metricas');
+const ciReader = require('./ci-reader');
+
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('../../hooks/lib/atomic-write'));
+} catch (err) {
+  if (err.code !== 'MODULE_NOT_FOUND') throw err;
+  atomicWriteJSON = (p, obj) => {
+    const dir = path.dirname(p);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj, null, 2), 'utf8');
+  };
+}
+
+const STORAGE_REL = path.join('.planning', 'evolution', 'metricas-dora.json');
+
+/**
+ * Umbrales DORA Report 2023 (Accelerate State of DevOps). Boundaries expresados
+ * en las unidades internas de cada métrica. Ajustar aquí si el reporte cambia.
+ *
+ * - deploymentFrequency (deploys/semana, mayor es mejor):
+ *   elite ≥1/día (7/sem) · high ≥1/mes (0.23/sem) · medium ≥1/semestre (0.038/sem) · low <semestral.
+ * - leadTimeHoras (commit→tag, menor es mejor): elite <1día · high <1sem · medium <1mes · low ≥1mes.
+ * - changeFailureRate (0..1, menor es mejor): elite ≤0.15 · high ≤0.30 · medium ≤0.45 · low >0.45.
+ * - mttrHoras (menor es mejor): elite <1h · high <1día · medium <1sem · low ≥1sem.
+ */
+const UMBRALES_DORA_2023 = {
+  deploymentFrequency: { elite: 7, high: 0.23, medium: 0.038 }, // deploys/semana, mayor mejor
+  leadTimeHoras: { elite: 24, high: 168, medium: 730 }, // menor mejor
+  changeFailureRate: { elite: 0.15, high: 0.3, medium: 0.45 }, // menor mejor
+  mttrHoras: { elite: 1, high: 24, medium: 168 }, // menor mejor
+};
+
+const NIVELES = ['elite', 'high', 'medium', 'low'];
+
+/**
+ * Clasifica un valor de una métrica en elite/high/medium/low.
+ * @param {string} metrica - clave de UMBRALES_DORA_2023.
+ * @param {number|null|undefined} valor
+ * @returns {'elite'|'high'|'medium'|'low'|'sin-datos'}
+ */
+function clasificar(metrica, valor) {
+  const u = UMBRALES_DORA_2023[metrica];
+  if (!u || valor === null || valor === undefined || !Number.isFinite(valor)) return 'sin-datos';
+
+  if (metrica === 'deploymentFrequency') {
+    // mayor es mejor
+    if (valor >= u.elite) return 'elite';
+    if (valor >= u.high) return 'high';
+    if (valor >= u.medium) return 'medium';
+    return 'low';
+  }
+  // menor es mejor (leadTime, cfr, mttr)
+  if (valor < u.elite) return 'elite';
+  if (valor < u.high) return 'high';
+  if (valor < u.medium) return 'medium';
+  return 'low';
+}
+
+/**
+ * Calcula las 4 métricas DORA del proyecto en baseDir.
+ * @returns objeto serializable con generado, ventana_dias y las 4 métricas.
+ */
+function calcularDora(baseDir = process.cwd(), opts = {}) {
+  const { ventanaDias = 30, hoy = new Date(), ejecutorGh } = opts;
+
+  // Git (siempre)
+  const df = gitMetricas.deploymentFrequency(baseDir, { ventanaDias, hoy });
+  const lt = gitMetricas.leadTimeForChanges(baseDir, { ventanaDias, hoy });
+
+  // CI (degrada): una sola llamada a gh. Si no está disponible, NO se re-intenta
+  // — se propaga la razón directamente (evita 3 invocaciones del mismo fallo).
+  const runsBase = ciReader.obtenerRuns({ ejecutorGh, rama: 'main' });
+  const cfr = runsBase.disponible
+    ? ciReader.changeFailureRate({ ventanaDias, hoy, runs: runsBase.runs })
+    : { disponible: false, razon: runsBase.razon };
+  const mttr = runsBase.disponible
+    ? ciReader.meanTimeToRestore({ ventanaDias, hoy, runs: runsBase.runs })
+    : { disponible: false, razon: runsBase.razon };
+
+  const deploymentFrequency = df.disponible
+    ? {
+        disponible: true,
+        valor: df.sinDatos ? null : df.deploysPorSemana,
+        unidad: 'deploys/semana',
+        clasificacion: df.sinDatos ? 'sin-datos' : clasificar('deploymentFrequency', df.deploysPorSemana),
+        sinDatos: !!df.sinDatos,
+      }
+    : { disponible: false, razon: df.razon };
+
+  const leadTime = lt.disponible
+    ? {
+        disponible: true,
+        p50Horas: lt.sinDatos ? null : lt.p50Horas,
+        p95Horas: lt.sinDatos ? null : lt.p95Horas,
+        clasificacion: lt.sinDatos ? 'sin-datos' : clasificar('leadTimeHoras', lt.p50Horas),
+        sinDatos: !!lt.sinDatos,
+      }
+    : { disponible: false, razon: lt.razon };
+
+  const changeFailureRate = cfr.disponible
+    ? {
+        disponible: true,
+        valor: cfr.sinDatos ? null : cfr.cfr,
+        clasificacion: cfr.sinDatos ? 'sin-datos' : clasificar('changeFailureRate', cfr.cfr),
+        sinDatos: !!cfr.sinDatos,
+        totalRuns: cfr.totalRuns,
+        fallidos: cfr.fallidos,
+      }
+    : { disponible: false, razon: cfr.razon };
+
+  const mttrOut = mttr.disponible
+    ? {
+        disponible: true,
+        mttrHoras: mttr.sinDatos ? null : mttr.mttrHoras,
+        clasificacion: mttr.sinDatos ? 'sin-datos' : clasificar('mttrHoras', mttr.mttrHoras),
+        sinDatos: !!mttr.sinDatos,
+        recuperaciones: mttr.recuperaciones,
+      }
+    : { disponible: false, razon: mttr.razon };
+
+  return {
+    generado: hoy.toISOString(),
+    ventana_dias: ventanaDias,
+    deploymentFrequency,
+    leadTime,
+    changeFailureRate,
+    mttr: mttrOut,
+  };
+}
+
+/**
+ * Persiste el informe DORA en `<baseDir>/.planning/evolution/metricas-dora.json`.
+ * `baseDir` se trata como ruta CONFIABLE del invocador (CLI local / cwd); NUNCA
+ * debe propagarse desde input web/HTTP/PR. Aun así se valida contención bajo
+ * baseDir para evitar write-anywhere si el path subiera de nivel (H-01).
+ */
+function persistir(baseDir, dora) {
+  const base = path.resolve(baseDir);
+  const destino = path.resolve(base, STORAGE_REL);
+  if (destino !== base && !destino.startsWith(base + path.sep)) {
+    throw new Error('destino de métricas DORA fuera de baseDir');
+  }
+  atomicWriteJSON(destino, dora);
+  return destino;
+}
+
+module.exports = {
+  clasificar,
+  calcularDora,
+  persistir,
+  UMBRALES_DORA_2023,
+  NIVELES,
+  STORAGE_REL,
+};
+
+// Entrypoint CLI: node scripts/lib/metricas-dora.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 dora = calcularDora(baseDir, { ventanaDias });
+  try {
+    persistir(baseDir, dora);
+  } catch {
+    /* persistencia best-effort: no romper el informe si el disco falla */
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify(dora, null, 2) + '\n');
+  } else {
+    const fmt = (txt) => process.stdout.write(`${txt}\n`);
+    const df = dora.deploymentFrequency;
+    const lt = dora.leadTime;
+    const cfr = dora.changeFailureRate;
+    const mt = dora.mttr;
+    fmt(`Deployment frequency: ${df.disponible ? (df.sinDatos ? 'sin datos' : `${df.valor.toFixed(2)}/sem [${df.clasificacion}]`) : 'no disponible'}`);
+    fmt(`Lead time (p50): ${lt.disponible ? (lt.sinDatos ? 'sin datos' : `${lt.p50Horas.toFixed(1)}h [${lt.clasificacion}]`) : 'no disponible'}`);
+    fmt(`Change failure rate: ${cfr.disponible ? (cfr.sinDatos ? 'sin datos' : `${(cfr.valor * 100).toFixed(1)}% [${cfr.clasificacion}]`) : 'no disponible (gh ausente)'}`);
+    fmt(`MTTR: ${mt.disponible ? (mt.sinDatos ? 'sin datos' : `${mt.mttrHoras.toFixed(1)}h [${mt.clasificacion}]`) : 'no disponible (gh ausente)'}`);
+  }
+  process.exit(0);
+}