@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/lib/auditar-invocaciones-comandos.js

@@ -1,104 +1,104 @@
-'use strict';
-
-/**
- * auditar-invocaciones-comandos.js
- *
- * Gate anti-regresión de la clase de bug "invocación relativa al proyecto en
- * comandos user-facing" (ver docs/invocacion-cli-cross-scope.md).
- *
- * Un comando que corre en el proyecto del usuario NUNCA debe invocar scripts SWL
- * con ruta relativa al proyecto (`node scripts/lib/...`, `node hooks/...`,
- * `require('./scripts/...')`): esas rutas no existen downstream. Debe usar el
- * subcomando del CLI (`swl-ses <sub>` / `npx ... <sub>` / `node scripts/cli/<sub>.js`).
- *
- * Solo escanea bloques de código (``` ... ```) para no marcar menciones
- * prohibitivas en prosa. Excluye `scripts/cli/` (forma repo-madre sancionada).
- *
- * Función pura + entrypoint CLI con exit 1 si hay violaciones.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-// Comandos que corren SOLO en el repo madre de swl-ses (el CWD ES el repo, así
-// que `node scripts/...` relativo es correcto). NO son user-facing.
-const SELF_DEV = new Set([
-  'release',
-  'contribuir',
-  'evaluar-skill',
-  'reflect-skills',
-]);
-
-// Patrones de invocación relativa al proyecto que se rompen downstream.
-// Se evalúan SOLO dentro de bloques de código.
-const PATRONES = [
-  { re: /\bnode\s+(?:\.\/)?scripts\/(?!cli\/)/, desc: 'node scripts/ (usa swl-ses <sub>)' },
-  { re: /\bnode\s+(?:\.\/)?hooks\//, desc: 'node hooks/ (usa swl-ses <sub>)' },
-  { re: /require\(\s*['"]\.\.?\/scripts\//, desc: "require('./scripts/ inline" },
-  { re: /require\(\s*['"]\.\.?\/hooks\//, desc: "require('./hooks/ inline" },
-];
-
-/**
- * @param {string} [comandosDir] default: comandos/swl relativo al repo de este script.
- * @returns {{ok:boolean, violaciones:Array<{comando:string,linea:number,texto:string,patron:string}>, escaneados:number}}
- */
-function auditarInvocacionesComandos(comandosDir) {
-  const dir = comandosDir || path.join(__dirname, '..', '..', 'comandos', 'swl');
-  const violaciones = [];
-  let escaneados = 0;
-
-  let archivos;
-  try {
-    archivos = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
-  } catch {
-    return { ok: true, violaciones, escaneados: 0 };
-  }
-
-  for (const archivo of archivos) {
-    const comando = archivo.replace(/\.md$/, '');
-    if (SELF_DEV.has(comando)) continue;
-    escaneados++;
-
-    const contenido = fs.readFileSync(path.join(dir, archivo), 'utf8');
-    const lineas = contenido.split('\n');
-    let dentroCodigo = false;
-
-    for (let i = 0; i < lineas.length; i++) {
-      const linea = lineas[i];
-      if (/^\s*```/.test(linea)) {
-        dentroCodigo = !dentroCodigo;
-        continue;
-      }
-      if (!dentroCodigo) continue;
-      for (const { re, desc } of PATRONES) {
-        if (re.test(linea)) {
-          violaciones.push({
-            comando,
-            linea: i + 1,
-            texto: linea.trim(),
-            patron: desc,
-          });
-          break;
-        }
-      }
-    }
-  }
-
-  return { ok: violaciones.length === 0, violaciones, escaneados };
-}
-
-module.exports = { auditarInvocacionesComandos, SELF_DEV };
-
-if (require.main === module) {
-  const r = auditarInvocacionesComandos();
-  if (r.ok) {
-    console.log(`[OK] invocaciones-comandos — ${r.escaneados} comandos user-facing sin rutas relativas al proyecto`);
-    process.exit(0);
-  }
-  console.error(`[FALLA] invocaciones-comandos — ${r.violaciones.length} invocación(es) relativa(s) al proyecto en comandos user-facing:`);
-  for (const v of r.violaciones) {
-    console.error(`  ${v.comando}.md:${v.linea} [${v.patron}] ${v.texto}`);
-  }
-  console.error('\nUsa el patrón cross-scope (docs/invocacion-cli-cross-scope.md): swl-ses <sub> / npx ... <sub> / node scripts/cli/<sub>.js');
-  process.exit(1);
-}
+'use strict';
+
+/**
+ * auditar-invocaciones-comandos.js
+ *
+ * Gate anti-regresión de la clase de bug "invocación relativa al proyecto en
+ * comandos user-facing" (ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Un comando que corre en el proyecto del usuario NUNCA debe invocar scripts SWL
+ * con ruta relativa al proyecto (`node scripts/lib/...`, `node hooks/...`,
+ * `require('./scripts/...')`): esas rutas no existen downstream. Debe usar el
+ * subcomando del CLI (`swl-ses <sub>` / `npx ... <sub>` / `node scripts/cli/<sub>.js`).
+ *
+ * Solo escanea bloques de código (``` ... ```) para no marcar menciones
+ * prohibitivas en prosa. Excluye `scripts/cli/` (forma repo-madre sancionada).
+ *
+ * Función pura + entrypoint CLI con exit 1 si hay violaciones.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Comandos que corren SOLO en el repo madre de swl-ses (el CWD ES el repo, así
+// que `node scripts/...` relativo es correcto). NO son user-facing.
+const SELF_DEV = new Set([
+  'release',
+  'contribuir',
+  'evaluar-skill',
+  'reflect-skills',
+]);
+
+// Patrones de invocación relativa al proyecto que se rompen downstream.
+// Se evalúan SOLO dentro de bloques de código.
+const PATRONES = [
+  { re: /\bnode\s+(?:\.\/)?scripts\/(?!cli\/)/, desc: 'node scripts/ (usa swl-ses <sub>)' },
+  { re: /\bnode\s+(?:\.\/)?hooks\//, desc: 'node hooks/ (usa swl-ses <sub>)' },
+  { re: /require\(\s*['"]\.\.?\/scripts\//, desc: "require('./scripts/ inline" },
+  { re: /require\(\s*['"]\.\.?\/hooks\//, desc: "require('./hooks/ inline" },
+];
+
+/**
+ * @param {string} [comandosDir] default: comandos/swl relativo al repo de este script.
+ * @returns {{ok:boolean, violaciones:Array<{comando:string,linea:number,texto:string,patron:string}>, escaneados:number}}
+ */
+function auditarInvocacionesComandos(comandosDir) {
+  const dir = comandosDir || path.join(__dirname, '..', '..', 'comandos', 'swl');
+  const violaciones = [];
+  let escaneados = 0;
+
+  let archivos;
+  try {
+    archivos = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
+  } catch {
+    return { ok: true, violaciones, escaneados: 0 };
+  }
+
+  for (const archivo of archivos) {
+    const comando = archivo.replace(/\.md$/, '');
+    if (SELF_DEV.has(comando)) continue;
+    escaneados++;
+
+    const contenido = fs.readFileSync(path.join(dir, archivo), 'utf8');
+    const lineas = contenido.split('\n');
+    let dentroCodigo = false;
+
+    for (let i = 0; i < lineas.length; i++) {
+      const linea = lineas[i];
+      if (/^\s*```/.test(linea)) {
+        dentroCodigo = !dentroCodigo;
+        continue;
+      }
+      if (!dentroCodigo) continue;
+      for (const { re, desc } of PATRONES) {
+        if (re.test(linea)) {
+          violaciones.push({
+            comando,
+            linea: i + 1,
+            texto: linea.trim(),
+            patron: desc,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { ok: violaciones.length === 0, violaciones, escaneados };
+}
+
+module.exports = { auditarInvocacionesComandos, SELF_DEV };
+
+if (require.main === module) {
+  const r = auditarInvocacionesComandos();
+  if (r.ok) {
+    console.log(`[OK] invocaciones-comandos — ${r.escaneados} comandos user-facing sin rutas relativas al proyecto`);
+    process.exit(0);
+  }
+  console.error(`[FALLA] invocaciones-comandos — ${r.violaciones.length} invocación(es) relativa(s) al proyecto en comandos user-facing:`);
+  for (const v of r.violaciones) {
+    console.error(`  ${v.comando}.md:${v.linea} [${v.patron}] ${v.texto}`);
+  }
+  console.error('\nUsa el patrón cross-scope (docs/invocacion-cli-cross-scope.md): swl-ses <sub> / npx ... <sub> / node scripts/cli/<sub>.js');
+  process.exit(1);
+}

package/scripts/lib/benchmark-metrics.js

@@ -1,160 +1,160 @@
-'use strict';
-
-/**
- * benchmark-metrics.js — Métricas de retrieval para benchmark de memoria SWL.
- *
- * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
- * Funciones puras zero-deps. Adaptado a IDs SWL (aprendizaje, sesion,
- * instinto) en lugar de session_id de agentmemory.
- *
- * Métricas:
- *   - recallAt(k): 1.0 si al menos un gold ID está en los top-k, sino 0.0
- *   - precisionAt(k): proporción de top-k que son gold
- *   - mrr: Mean Reciprocal Rank (1/rank del primer gold encontrado)
- *   - ndcgAt(k): Normalized Discounted Cumulative Gain
- *
- * @module scripts/lib/benchmark-metrics
- */
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-function asSet(arr) {
-  return new Set(Array.isArray(arr) ? arr : []);
-}
-
-// ── métricas individuales ─────────────────────────────────────────────────────
-
-/**
- * Recall @ k: 1.0 si ALGÚN id gold está en los primeros k retrieved.
- *
- * @param {string[]} retrievedIds - IDs ordenados (mejor primero).
- * @param {string[]} goldIds - IDs correctos esperados.
- * @param {number} k
- * @returns {number} 0 o 1
- */
-function recallAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
-  const topK = new Set(retrievedIds.slice(0, k));
-  return goldIds.some(g => topK.has(g)) ? 1.0 : 0.0;
-}
-
-/**
- * Precision @ k: proporción de los primeros k retrieved que son gold.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @param {number} k
- * @returns {number} en [0, 1]
- */
-function precisionAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
-  const goldSet = asSet(goldIds);
-  const topK = retrievedIds.slice(0, k);
-  if (topK.length === 0) return 0;
-  const hits = topK.filter(id => goldSet.has(id)).length;
-  return hits / topK.length;
-}
-
-/**
- * Mean Reciprocal Rank: 1/rank del primer gold encontrado, o 0 si ninguno.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @returns {number} en [0, 1]
- */
-function mrr(retrievedIds, goldIds) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
-  const goldSet = asSet(goldIds);
-  for (let i = 0; i < retrievedIds.length; i++) {
-    if (goldSet.has(retrievedIds[i])) {
-      return 1 / (i + 1);
-    }
-  }
-  return 0;
-}
-
-function dcg(relevancias, k) {
-  let suma = 0;
-  for (let i = 0; i < Math.min(k, relevancias.length); i++) {
-    suma += (relevancias[i] ? 1 : 0) / Math.log2(i + 2);
-  }
-  return suma;
-}
-
-/**
- * Normalized Discounted Cumulative Gain @ k.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @param {number} k
- * @returns {number} en [0, 1]
- */
-function ndcgAt(retrievedIds, goldIds, k) {
-  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
-  const goldSet = asSet(goldIds);
-  const rels = retrievedIds.slice(0, k).map(id => goldSet.has(id));
-  const idealRels = Array.from({ length: Math.min(k, goldSet.size) }, () => true);
-  const idealDCG = dcg(idealRels, k);
-  if (idealDCG === 0) return 0;
-  return dcg(rels, k) / idealDCG;
-}
-
-// ── agregados ─────────────────────────────────────────────────────────────────
-
-/**
- * Calcula el conjunto completo de métricas para una query.
- *
- * @param {string[]} retrievedIds
- * @param {string[]} goldIds
- * @returns {{ recall_at_5, recall_at_10, recall_at_20, mrr, ndcg_at_10, precision_at_5 }}
- */
-function calcularMetricas(retrievedIds, goldIds) {
-  return {
-    recall_at_5:    recallAt(retrievedIds, goldIds, 5),
-    recall_at_10:   recallAt(retrievedIds, goldIds, 10),
-    recall_at_20:   recallAt(retrievedIds, goldIds, 20),
-    mrr:            mrr(retrievedIds, goldIds),
-    ndcg_at_10:     ndcgAt(retrievedIds, goldIds, 10),
-    precision_at_5: precisionAt(retrievedIds, goldIds, 5),
-  };
-}
-
-/**
- * Promedia métricas sobre múltiples queries.
- *
- * @param {Array<object>} resultados - Array de objetos producidos por calcularMetricas().
- * @returns {object} Promedios con campo `n` (cantidad de queries).
- */
-function promediar(resultados) {
-  if (!Array.isArray(resultados) || resultados.length === 0) {
-    return {
-      n: 0,
-      recall_at_5: 0,
-      recall_at_10: 0,
-      recall_at_20: 0,
-      mrr: 0,
-      ndcg_at_10: 0,
-      precision_at_5: 0,
-    };
-  }
-
-  const claves = ['recall_at_5', 'recall_at_10', 'recall_at_20', 'mrr', 'ndcg_at_10', 'precision_at_5'];
-  const promedio = { n: resultados.length };
-  for (const k of claves) {
-    const sum = resultados.reduce((a, r) => a + (r[k] || 0), 0);
-    promedio[k] = sum / resultados.length;
-  }
-  return promedio;
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  recallAt,
-  precisionAt,
-  mrr,
-  ndcgAt,
-  dcg,
-  calcularMetricas,
-  promediar,
-};
+'use strict';
+
+/**
+ * benchmark-metrics.js — Métricas de retrieval para benchmark de memoria SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Funciones puras zero-deps. Adaptado a IDs SWL (aprendizaje, sesion,
+ * instinto) en lugar de session_id de agentmemory.
+ *
+ * Métricas:
+ *   - recallAt(k): 1.0 si al menos un gold ID está en los top-k, sino 0.0
+ *   - precisionAt(k): proporción de top-k que son gold
+ *   - mrr: Mean Reciprocal Rank (1/rank del primer gold encontrado)
+ *   - ndcgAt(k): Normalized Discounted Cumulative Gain
+ *
+ * @module scripts/lib/benchmark-metrics
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function asSet(arr) {
+  return new Set(Array.isArray(arr) ? arr : []);
+}
+
+// ── métricas individuales ─────────────────────────────────────────────────────
+
+/**
+ * Recall @ k: 1.0 si ALGÚN id gold está en los primeros k retrieved.
+ *
+ * @param {string[]} retrievedIds - IDs ordenados (mejor primero).
+ * @param {string[]} goldIds - IDs correctos esperados.
+ * @param {number} k
+ * @returns {number} 0 o 1
+ */
+function recallAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const topK = new Set(retrievedIds.slice(0, k));
+  return goldIds.some(g => topK.has(g)) ? 1.0 : 0.0;
+}
+
+/**
+ * Precision @ k: proporción de los primeros k retrieved que son gold.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function precisionAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const topK = retrievedIds.slice(0, k);
+  if (topK.length === 0) return 0;
+  const hits = topK.filter(id => goldSet.has(id)).length;
+  return hits / topK.length;
+}
+
+/**
+ * Mean Reciprocal Rank: 1/rank del primer gold encontrado, o 0 si ninguno.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {number} en [0, 1]
+ */
+function mrr(retrievedIds, goldIds) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const goldSet = asSet(goldIds);
+  for (let i = 0; i < retrievedIds.length; i++) {
+    if (goldSet.has(retrievedIds[i])) {
+      return 1 / (i + 1);
+    }
+  }
+  return 0;
+}
+
+function dcg(relevancias, k) {
+  let suma = 0;
+  for (let i = 0; i < Math.min(k, relevancias.length); i++) {
+    suma += (relevancias[i] ? 1 : 0) / Math.log2(i + 2);
+  }
+  return suma;
+}
+
+/**
+ * Normalized Discounted Cumulative Gain @ k.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function ndcgAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const rels = retrievedIds.slice(0, k).map(id => goldSet.has(id));
+  const idealRels = Array.from({ length: Math.min(k, goldSet.size) }, () => true);
+  const idealDCG = dcg(idealRels, k);
+  if (idealDCG === 0) return 0;
+  return dcg(rels, k) / idealDCG;
+}
+
+// ── agregados ─────────────────────────────────────────────────────────────────
+
+/**
+ * Calcula el conjunto completo de métricas para una query.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {{ recall_at_5, recall_at_10, recall_at_20, mrr, ndcg_at_10, precision_at_5 }}
+ */
+function calcularMetricas(retrievedIds, goldIds) {
+  return {
+    recall_at_5:    recallAt(retrievedIds, goldIds, 5),
+    recall_at_10:   recallAt(retrievedIds, goldIds, 10),
+    recall_at_20:   recallAt(retrievedIds, goldIds, 20),
+    mrr:            mrr(retrievedIds, goldIds),
+    ndcg_at_10:     ndcgAt(retrievedIds, goldIds, 10),
+    precision_at_5: precisionAt(retrievedIds, goldIds, 5),
+  };
+}
+
+/**
+ * Promedia métricas sobre múltiples queries.
+ *
+ * @param {Array<object>} resultados - Array de objetos producidos por calcularMetricas().
+ * @returns {object} Promedios con campo `n` (cantidad de queries).
+ */
+function promediar(resultados) {
+  if (!Array.isArray(resultados) || resultados.length === 0) {
+    return {
+      n: 0,
+      recall_at_5: 0,
+      recall_at_10: 0,
+      recall_at_20: 0,
+      mrr: 0,
+      ndcg_at_10: 0,
+      precision_at_5: 0,
+    };
+  }
+
+  const claves = ['recall_at_5', 'recall_at_10', 'recall_at_20', 'mrr', 'ndcg_at_10', 'precision_at_5'];
+  const promedio = { n: resultados.length };
+  for (const k of claves) {
+    const sum = resultados.reduce((a, r) => a + (r[k] || 0), 0);
+    promedio[k] = sum / resultados.length;
+  }
+  return promedio;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  recallAt,
+  precisionAt,
+  mrr,
+  ndcgAt,
+  dcg,
+  calcularMetricas,
+  promediar,
+};