@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/audit-tools/audit-history.js

@@ -1,330 +1,330 @@
-// Adaptado de temp/ultraship-main/tools/audit-history.mjs bajo MIT License
-// Fuente: Houseofmvps/ultraship (https://github.com/Houseofmvps/ultraship)
-'use strict';
-
-const { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } = require('fs');
-const { join, resolve, dirname } = require('path');
-const { outputJSON, outputError } = require('./lib/output');
-
-/** Número máximo de entradas a conservar por categoría. */
-const MAX_ENTRIES_PER_CATEGORY = 100;
-
-/** Ruta por defecto del historial de auditorías. */
-const DEFAULT_HISTORY_PATH = join(process.cwd(), '.planning', 'audit', 'history.jsonl');
-
-/**
- * Lee todas las entradas del historial JSONL.
- * @param {string} historyPath
- * @returns {object[]}
- */
-function readHistory(historyPath) {
-  if (!existsSync(historyPath)) return [];
-  try {
-    return readFileSync(historyPath, 'utf8')
-      .split('\n')
-      .filter(Boolean)
-      .map(line => JSON.parse(line));
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Reescribe el archivo JSONL completo con las entradas proporcionadas.
- * @param {string} historyPath
- * @param {object[]} entries
- */
-function writeHistory(historyPath, entries) {
-  const dir = dirname(historyPath);
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
-  writeFileSync(historyPath, entries.map(e => JSON.stringify(e)).join('\n') + (entries.length > 0 ? '\n' : ''), 'utf8');
-}
-
-/**
- * Agrega una nueva entrada al historial JSONL, respetando el límite de 100 por categoría.
- * Si se supera el límite, reescribe el archivo con las entradas más recientes de esa categoría.
- *
- * @param {string} historyPath
- * @param {object} entry       - Objeto que DEBE incluir campos `category` y `timestamp`.
- */
-function appendHistory(historyPath, entry) {
-  const dir = dirname(historyPath);
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
-
-  const existing = readHistory(historyPath);
-  const category = entry.category || 'general';
-
-  // Filtrar entradas de la misma categoría
-  const sameCategory = existing.filter(e => (e.category || 'general') === category);
-
-  if (sameCategory.length >= MAX_ENTRIES_PER_CATEGORY) {
-    // Hay que podar: mantener las (MAX-1) más recientes de esta categoría + agregar la nueva
-    const otherCategories = existing.filter(e => (e.category || 'general') !== category);
-    const trimmed = sameCategory.slice(-(MAX_ENTRIES_PER_CATEGORY - 1));
-    writeHistory(historyPath, [...otherCategories, ...trimmed, entry]);
-  } else {
-    // Hay espacio: solo hacer append
-    appendFileSync(historyPath, JSON.stringify(entry) + '\n', 'utf8');
-  }
-}
-
-/**
- * Obtiene la última entrada de una categoría específica.
- * @param {object[]} entries
- * @param {string}   category
- * @returns {object|null}
- */
-function getLastEntryForCategory(entries, category) {
-  const categoryEntries = entries.filter(e => (e.category || 'general') === category);
-  if (categoryEntries.length === 0) return null;
-  return categoryEntries[categoryEntries.length - 1];
-}
-
-/**
- * Calcula la tendencia comparando el score actual con el anterior.
- * @param {number} current
- * @param {number} previous
- * @returns {'improving'|'declining'|'stable'}
- */
-function calculateTrend(current, previous) {
-  if (current > previous + 0.5) return 'improving';
-  if (current < previous - 0.5) return 'declining';
-  return 'stable';
-}
-
-/**
- * Formatea un número como diferencia con signo.
- * @param {number} diff
- * @returns {string}
- */
-function formatDiff(diff) {
-  if (diff > 0)  return `+${diff.toFixed(1)}`;
-  if (diff < 0)  return diff.toFixed(1);
-  return '0.0';
-}
-
-/**
- * Guarda una nueva entrada de auditoría en el historial.
- * @param {object} options
- * @param {string} options.historyPath
- * @param {string} options.category     - Categoría de la auditoría (ej: 'security', 'performance').
- * @param {number} options.score        - Puntuación de 0 a 100.
- * @param {object} [options.metadata]   - Datos adicionales opcionales.
- * @returns {object} Entrada guardada + tendencia detectada.
- */
-function saveEntry(options) {
-  const { historyPath, category, score, metadata = {} } = options;
-
-  const existing = readHistory(historyPath);
-  const previous = getLastEntryForCategory(existing, category);
-
-  const entry = {
-    timestamp: new Date().toISOString(),
-    category,
-    score,
-    metadata,
-  };
-
-  appendHistory(historyPath, entry);
-
-  const trend = previous !== null
-    ? calculateTrend(score, previous.score)
-    : 'first_run';
-
-  return {
-    entry,
-    trend,
-    previous_score: previous ? previous.score : null,
-    diff: previous ? score - previous.score : null,
-  };
-}
-
-/**
- * Muestra el historial de una categoría con tendencias.
- * @param {string} historyPath
- * @param {string} [category]   - Si se omite, muestra todas las categorías.
- * @param {number} [limit]      - Número máximo de entradas a mostrar.
- * @returns {object}
- */
-function showHistory(historyPath, category, limit) {
-  const all = readHistory(historyPath);
-  const filtered = category
-    ? all.filter(e => (e.category || 'general') === category)
-    : all;
-
-  const entries = limit ? filtered.slice(-limit) : filtered;
-
-  // Agrupar por categoría para estadísticas
-  const byCategory = {};
-  for (const entry of all) {
-    const cat = entry.category || 'general';
-    if (!byCategory[cat]) byCategory[cat] = [];
-    byCategory[cat].push(entry.score);
-  }
-
-  const summaries = Object.entries(byCategory).map(([cat, scores]) => {
-    const avg = scores.reduce((s, v) => s + v, 0) / scores.length;
-    const last = scores[scores.length - 1];
-    const prev = scores.length >= 2 ? scores[scores.length - 2] : null;
-    return {
-      category:    cat,
-      entries:     scores.length,
-      avg_score:   Math.round(avg * 10) / 10,
-      last_score:  last,
-      trend:       prev !== null ? calculateTrend(last, prev) : 'first_run',
-    };
-  });
-
-  return {
-    total_entries: filtered.length,
-    shown:         entries.length,
-    category_filter: category || null,
-    summaries,
-    entries,
-  };
-}
-
-/**
- * Calcula el diff entre la última y penúltima entrada de una categoría.
- * @param {string} historyPath
- * @param {string} category
- * @returns {object}
- */
-function diffHistory(historyPath, category) {
-  const all = readHistory(historyPath);
-  const categoryEntries = category
-    ? all.filter(e => (e.category || 'general') === category)
-    : all;
-
-  if (categoryEntries.length === 0) {
-    return { success: false, message: `Sin entradas en el historial para categoría: ${category || 'todas'}` };
-  }
-
-  if (categoryEntries.length === 1) {
-    return {
-      success:        true,
-      message:        'Solo existe una entrada — no hay diff disponible',
-      current:        categoryEntries[0],
-      previous:       null,
-      diff:           null,
-      trend:          'first_run',
-    };
-  }
-
-  const current  = categoryEntries[categoryEntries.length - 1];
-  const previous = categoryEntries[categoryEntries.length - 2];
-  const diff     = current.score - previous.score;
-  const trend    = calculateTrend(current.score, previous.score);
-
-  // Comparar metadata keys si existen
-  const metaDiff = [];
-  const currMeta = current.metadata  || {};
-  const prevMeta = previous.metadata || {};
-
-  const allKeys = new Set([...Object.keys(currMeta), ...Object.keys(prevMeta)]);
-  for (const key of allKeys) {
-    const curr = currMeta[key];
-    const prev = prevMeta[key];
-    if (curr !== prev) {
-      metaDiff.push({ key, current: curr, previous: prev });
-    }
-  }
-
-  return {
-    success:        true,
-    category:       category || 'todas',
-    current,
-    previous,
-    diff:           parseFloat(formatDiff(diff)),
-    diff_formatted: formatDiff(diff),
-    trend,
-    metadata_changes: metaDiff,
-  };
-}
-
-function main() {
-  const args        = process.argv.slice(2);
-  const command     = args[0];
-  const historyPath = (() => {
-    const hp = args.find(a => a.startsWith('--history='));
-    return hp ? resolve(hp.split('=')[1]) : DEFAULT_HISTORY_PATH;
-  })();
-
-  if (command === 'save') {
-    // save --category=X --score=N [--meta-key=value ...]
-    const categoryArg = args.find(a => a.startsWith('--category='));
-    const scoreArg    = args.find(a => a.startsWith('--score='));
-
-    if (!categoryArg || !scoreArg) {
-      outputError('Uso: audit-history.js save --category=X --score=N [--history=ruta] [--meta-KEY=VALOR ...]');
-      process.exit(0);
-    }
-
-    const category = categoryArg.split('=')[1];
-    const score    = parseFloat(scoreArg.split('=')[1]);
-
-    if (isNaN(score)) {
-      outputError(`Puntuación inválida: ${scoreArg.split('=')[1]}`);
-      process.exit(0);
-    }
-
-    // Extraer metadata extra (--meta-KEY=VALOR)
-    const metadata = {};
-    for (const arg of args) {
-      if (arg.startsWith('--meta-')) {
-        const rest     = arg.slice(7); // quitar "--meta-"
-        const eqIndex  = rest.indexOf('=');
-        if (eqIndex > 0) {
-          const key    = rest.slice(0, eqIndex);
-          const value  = rest.slice(eqIndex + 1);
-          metadata[key] = value;
-        }
-      }
-    }
-
-    const result = saveEntry({ historyPath, category, score, metadata });
-    outputJSON({
-      success:        true,
-      saved:          result.entry,
-      trend:          result.trend,
-      previous_score: result.previous_score,
-      diff:           result.diff,
-    });
-
-  } else if (command === 'show') {
-    const categoryArg = args.find(a => a.startsWith('--category='));
-    const limitArg    = args.find(a => a.startsWith('--limit='));
-    const category    = categoryArg ? categoryArg.split('=')[1] : undefined;
-    const limit       = limitArg    ? parseInt(limitArg.split('=')[1], 10) : 20;
-
-    const result = showHistory(historyPath, category, limit);
-    outputJSON({ success: true, ...result });
-
-  } else if (command === 'diff') {
-    const categoryArg = args.find(a => a.startsWith('--category='));
-    const category    = categoryArg ? categoryArg.split('=')[1] : undefined;
-
-    const result = diffHistory(historyPath, category);
-    outputJSON(result);
-
-  } else {
-    outputError(`Comando desconocido: "${command || '(ninguno)'}". Comandos válidos: save, show, diff`);
-    process.exit(0);
-  }
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = {
-  readHistory,
-  writeHistory,
-  appendHistory,
-  saveEntry,
-  showHistory,
-  diffHistory,
-  calculateTrend,
-  getLastEntryForCategory,
-  MAX_ENTRIES_PER_CATEGORY,
-};
+// Adaptado de temp/ultraship-main/tools/audit-history.mjs bajo MIT License
+// Fuente: Houseofmvps/ultraship (https://github.com/Houseofmvps/ultraship)
+'use strict';
+
+const { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } = require('fs');
+const { join, resolve, dirname } = require('path');
+const { outputJSON, outputError } = require('./lib/output');
+
+/** Número máximo de entradas a conservar por categoría. */
+const MAX_ENTRIES_PER_CATEGORY = 100;
+
+/** Ruta por defecto del historial de auditorías. */
+const DEFAULT_HISTORY_PATH = join(process.cwd(), '.planning', 'audit', 'history.jsonl');
+
+/**
+ * Lee todas las entradas del historial JSONL.
+ * @param {string} historyPath
+ * @returns {object[]}
+ */
+function readHistory(historyPath) {
+  if (!existsSync(historyPath)) return [];
+  try {
+    return readFileSync(historyPath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(line => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Reescribe el archivo JSONL completo con las entradas proporcionadas.
+ * @param {string} historyPath
+ * @param {object[]} entries
+ */
+function writeHistory(historyPath, entries) {
+  const dir = dirname(historyPath);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(historyPath, entries.map(e => JSON.stringify(e)).join('\n') + (entries.length > 0 ? '\n' : ''), 'utf8');
+}
+
+/**
+ * Agrega una nueva entrada al historial JSONL, respetando el límite de 100 por categoría.
+ * Si se supera el límite, reescribe el archivo con las entradas más recientes de esa categoría.
+ *
+ * @param {string} historyPath
+ * @param {object} entry       - Objeto que DEBE incluir campos `category` y `timestamp`.
+ */
+function appendHistory(historyPath, entry) {
+  const dir = dirname(historyPath);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const existing = readHistory(historyPath);
+  const category = entry.category || 'general';
+
+  // Filtrar entradas de la misma categoría
+  const sameCategory = existing.filter(e => (e.category || 'general') === category);
+
+  if (sameCategory.length >= MAX_ENTRIES_PER_CATEGORY) {
+    // Hay que podar: mantener las (MAX-1) más recientes de esta categoría + agregar la nueva
+    const otherCategories = existing.filter(e => (e.category || 'general') !== category);
+    const trimmed = sameCategory.slice(-(MAX_ENTRIES_PER_CATEGORY - 1));
+    writeHistory(historyPath, [...otherCategories, ...trimmed, entry]);
+  } else {
+    // Hay espacio: solo hacer append
+    appendFileSync(historyPath, JSON.stringify(entry) + '\n', 'utf8');
+  }
+}
+
+/**
+ * Obtiene la última entrada de una categoría específica.
+ * @param {object[]} entries
+ * @param {string}   category
+ * @returns {object|null}
+ */
+function getLastEntryForCategory(entries, category) {
+  const categoryEntries = entries.filter(e => (e.category || 'general') === category);
+  if (categoryEntries.length === 0) return null;
+  return categoryEntries[categoryEntries.length - 1];
+}
+
+/**
+ * Calcula la tendencia comparando el score actual con el anterior.
+ * @param {number} current
+ * @param {number} previous
+ * @returns {'improving'|'declining'|'stable'}
+ */
+function calculateTrend(current, previous) {
+  if (current > previous + 0.5) return 'improving';
+  if (current < previous - 0.5) return 'declining';
+  return 'stable';
+}
+
+/**
+ * Formatea un número como diferencia con signo.
+ * @param {number} diff
+ * @returns {string}
+ */
+function formatDiff(diff) {
+  if (diff > 0)  return `+${diff.toFixed(1)}`;
+  if (diff < 0)  return diff.toFixed(1);
+  return '0.0';
+}
+
+/**
+ * Guarda una nueva entrada de auditoría en el historial.
+ * @param {object} options
+ * @param {string} options.historyPath
+ * @param {string} options.category     - Categoría de la auditoría (ej: 'security', 'performance').
+ * @param {number} options.score        - Puntuación de 0 a 100.
+ * @param {object} [options.metadata]   - Datos adicionales opcionales.
+ * @returns {object} Entrada guardada + tendencia detectada.
+ */
+function saveEntry(options) {
+  const { historyPath, category, score, metadata = {} } = options;
+
+  const existing = readHistory(historyPath);
+  const previous = getLastEntryForCategory(existing, category);
+
+  const entry = {
+    timestamp: new Date().toISOString(),
+    category,
+    score,
+    metadata,
+  };
+
+  appendHistory(historyPath, entry);
+
+  const trend = previous !== null
+    ? calculateTrend(score, previous.score)
+    : 'first_run';
+
+  return {
+    entry,
+    trend,
+    previous_score: previous ? previous.score : null,
+    diff: previous ? score - previous.score : null,
+  };
+}
+
+/**
+ * Muestra el historial de una categoría con tendencias.
+ * @param {string} historyPath
+ * @param {string} [category]   - Si se omite, muestra todas las categorías.
+ * @param {number} [limit]      - Número máximo de entradas a mostrar.
+ * @returns {object}
+ */
+function showHistory(historyPath, category, limit) {
+  const all = readHistory(historyPath);
+  const filtered = category
+    ? all.filter(e => (e.category || 'general') === category)
+    : all;
+
+  const entries = limit ? filtered.slice(-limit) : filtered;
+
+  // Agrupar por categoría para estadísticas
+  const byCategory = {};
+  for (const entry of all) {
+    const cat = entry.category || 'general';
+    if (!byCategory[cat]) byCategory[cat] = [];
+    byCategory[cat].push(entry.score);
+  }
+
+  const summaries = Object.entries(byCategory).map(([cat, scores]) => {
+    const avg = scores.reduce((s, v) => s + v, 0) / scores.length;
+    const last = scores[scores.length - 1];
+    const prev = scores.length >= 2 ? scores[scores.length - 2] : null;
+    return {
+      category:    cat,
+      entries:     scores.length,
+      avg_score:   Math.round(avg * 10) / 10,
+      last_score:  last,
+      trend:       prev !== null ? calculateTrend(last, prev) : 'first_run',
+    };
+  });
+
+  return {
+    total_entries: filtered.length,
+    shown:         entries.length,
+    category_filter: category || null,
+    summaries,
+    entries,
+  };
+}
+
+/**
+ * Calcula el diff entre la última y penúltima entrada de una categoría.
+ * @param {string} historyPath
+ * @param {string} category
+ * @returns {object}
+ */
+function diffHistory(historyPath, category) {
+  const all = readHistory(historyPath);
+  const categoryEntries = category
+    ? all.filter(e => (e.category || 'general') === category)
+    : all;
+
+  if (categoryEntries.length === 0) {
+    return { success: false, message: `Sin entradas en el historial para categoría: ${category || 'todas'}` };
+  }
+
+  if (categoryEntries.length === 1) {
+    return {
+      success:        true,
+      message:        'Solo existe una entrada — no hay diff disponible',
+      current:        categoryEntries[0],
+      previous:       null,
+      diff:           null,
+      trend:          'first_run',
+    };
+  }
+
+  const current  = categoryEntries[categoryEntries.length - 1];
+  const previous = categoryEntries[categoryEntries.length - 2];
+  const diff     = current.score - previous.score;
+  const trend    = calculateTrend(current.score, previous.score);
+
+  // Comparar metadata keys si existen
+  const metaDiff = [];
+  const currMeta = current.metadata  || {};
+  const prevMeta = previous.metadata || {};
+
+  const allKeys = new Set([...Object.keys(currMeta), ...Object.keys(prevMeta)]);
+  for (const key of allKeys) {
+    const curr = currMeta[key];
+    const prev = prevMeta[key];
+    if (curr !== prev) {
+      metaDiff.push({ key, current: curr, previous: prev });
+    }
+  }
+
+  return {
+    success:        true,
+    category:       category || 'todas',
+    current,
+    previous,
+    diff:           parseFloat(formatDiff(diff)),
+    diff_formatted: formatDiff(diff),
+    trend,
+    metadata_changes: metaDiff,
+  };
+}
+
+function main() {
+  const args        = process.argv.slice(2);
+  const command     = args[0];
+  const historyPath = (() => {
+    const hp = args.find(a => a.startsWith('--history='));
+    return hp ? resolve(hp.split('=')[1]) : DEFAULT_HISTORY_PATH;
+  })();
+
+  if (command === 'save') {
+    // save --category=X --score=N [--meta-key=value ...]
+    const categoryArg = args.find(a => a.startsWith('--category='));
+    const scoreArg    = args.find(a => a.startsWith('--score='));
+
+    if (!categoryArg || !scoreArg) {
+      outputError('Uso: audit-history.js save --category=X --score=N [--history=ruta] [--meta-KEY=VALOR ...]');
+      process.exit(0);
+    }
+
+    const category = categoryArg.split('=')[1];
+    const score    = parseFloat(scoreArg.split('=')[1]);
+
+    if (isNaN(score)) {
+      outputError(`Puntuación inválida: ${scoreArg.split('=')[1]}`);
+      process.exit(0);
+    }
+
+    // Extraer metadata extra (--meta-KEY=VALOR)
+    const metadata = {};
+    for (const arg of args) {
+      if (arg.startsWith('--meta-')) {
+        const rest     = arg.slice(7); // quitar "--meta-"
+        const eqIndex  = rest.indexOf('=');
+        if (eqIndex > 0) {
+          const key    = rest.slice(0, eqIndex);
+          const value  = rest.slice(eqIndex + 1);
+          metadata[key] = value;
+        }
+      }
+    }
+
+    const result = saveEntry({ historyPath, category, score, metadata });
+    outputJSON({
+      success:        true,
+      saved:          result.entry,
+      trend:          result.trend,
+      previous_score: result.previous_score,
+      diff:           result.diff,
+    });
+
+  } else if (command === 'show') {
+    const categoryArg = args.find(a => a.startsWith('--category='));
+    const limitArg    = args.find(a => a.startsWith('--limit='));
+    const category    = categoryArg ? categoryArg.split('=')[1] : undefined;
+    const limit       = limitArg    ? parseInt(limitArg.split('=')[1], 10) : 20;
+
+    const result = showHistory(historyPath, category, limit);
+    outputJSON({ success: true, ...result });
+
+  } else if (command === 'diff') {
+    const categoryArg = args.find(a => a.startsWith('--category='));
+    const category    = categoryArg ? categoryArg.split('=')[1] : undefined;
+
+    const result = diffHistory(historyPath, category);
+    outputJSON(result);
+
+  } else {
+    outputError(`Comando desconocido: "${command || '(ninguno)'}". Comandos válidos: save, show, diff`);
+    process.exit(0);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  readHistory,
+  writeHistory,
+  appendHistory,
+  saveEntry,
+  showHistory,
+  diffHistory,
+  calculateTrend,
+  getLastEntryForCategory,
+  MAX_ENTRIES_PER_CATEGORY,
+};