@saulwade/swl-ses 1.9.0 → 2.1.0

package/scripts/lib/git-metricas.js

@@ -0,0 +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);
+}

package/scripts/lib/gitignore-manifest.js

@@ -79,7 +79,13 @@ const ENTRADAS_BASE = [
   // artefactos del proyecto usuario.
   ".planning/evolution/",
   ".planning/auto-evolution/",
-  ".planning/locks/",
+  // locks/: contenido runtime ignorado (singleton-guard {pid,ts},
+  // fase-activa.json) EXCEPTO los plan-locks de G1 (*PLAN.md.lock), que son
+  // evidencia de aprobación versionable (audit trail SDD — aprobar-plan.md).
+  // Patrón `dir/*` + negación: git no re-incluye archivos si el DIRECTORIO
+  // está ignorado, por eso se ignora el contenido y no el dir.
+  ".planning/locks/*",
+  "!.planning/locks/*PLAN.md.lock",
   ".planning/user-profile/",
 
   // Instintos modificados automáticamente por hooks (degradacion-instintos.js)
@@ -87,6 +93,28 @@ const ENTRADAS_BASE = [
 
   // Base de datos de uso
   "usage.db",
+
+  // ── Runtime adicional: derivados regenerables, caches y telemetría ──
+  // Cobertura completada en Fase 09 tras auditar qué genera SWL en proyectos
+  // destino vs lo que ENTRADAS_BASE propagaba. Todo esto es output de runtime,
+  // regenerable, no editado por el equipo → no se commitea.
+  ".planning/feature-list.json",          // derivar-feature-list.js (derivado de HOJA-RUTA.md)
+  ".planning/loops/",                     // loop-telemetry.js (/swl:verificar, /swl:status loops)
+  ".planning/archive/",                   // rotar-audit-auto.js (audit/logs rotados y comprimidos)
+  ".planning/analysis/",                  // outputs de análisis
+  ".planning/graph.json",                 // code-review-graph (cache del grafo)
+  ".planning/graph-cache.json",           // code-review-graph (cache incremental)
+  ".planning/mcp-snapshot.json",          // /swl:status (smoke test MCP) / mcp-status
+  ".planning/skill-index.json",           // /swl:skill-search (índice FTS de skills)
+  ".planning/inventario-aviso-state.json", // throttle del aviso de inventario
+  ".planning/*.lock",                     // locks sueltos (ej. STATE.md.lock; el dir locks/ ya está arriba)
+
+  // Estado runtime de /swl:verificar --until-converge. Vive DENTRO de
+  // .planning/fases/, que SÍ contiene plantillas commiteadas
+  // (0N-CONTEXTO/PLAN/RESUMEN/VERIFICACION.md). Glob específico para ignorar
+  // SOLO el estado de convergencia, nunca esas plantillas.
+  ".planning/fases/*-converge-state.json",
+  ".planning/fases/*-converge-run-*.json",
 ];
 
 // Entradas adicionales por runtime (se agregan cuando install usa ese target)

package/scripts/lib/metricas-dora.js

@@ -0,0 +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);
+}