@saulwade/swl-ses 1.6.0 → 1.6.3

package/scripts/lib/schema-version.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * scripts/lib/schema-version.js
+ *
+ * Helper de compatibilidad de schemas JSON aplicando reglas backward/forward
+ * del libro "Designing Data-Intensive Applications" de Martin Kleppmann
+ * (Capítulo 4, "Encoding and Evolution", p.112).
+ *
+ * Reglas implementadas (cita textual del libro):
+ *
+ *   "Backward compatibility — Newer code can read data that was written by
+ *    older code.
+ *
+ *    Forward compatibility — Older code can read data that was written by
+ *    newer code."
+ *
+ * Aplicado a SWL: cuando un schema evoluciona, el helper indica si un
+ * documento dado puede leerse con el schema dado y bajo qué modalidad
+ * de compatibilidad.
+ *
+ * Convenciones SemVer asumidas para $schemaVersion:
+ *   - MAJOR (X.0.0): breaking change (renombre, cambio de tipo, eliminación)
+ *   - MINOR (1.X.0): campo nuevo opcional, enum value nuevo
+ *   - PATCH (1.0.X): clarificación de descripción, sin cambio estructural
+ *
+ * Skill relacionado: proceso-ddia-fundamentos § Schema Evolution.
+ * ADR: 0026 — Versionado de schemas JSON con $schemaVersion.
+ */
+
+/**
+ * Parsea un string SemVer "MAJOR.MINOR.PATCH" a tupla numérica.
+ * @param {string} version
+ * @returns {[number, number, number] | null}
+ */
+function parsearVersion(version) {
+  if (typeof version !== 'string') return null;
+  const m = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) return null;
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+}
+
+/**
+ * Verifica si un documento es compatible con un schema según sus $schemaVersion.
+ *
+ * @param {object} documento - Documento JSON con propiedad opcional $schemaVersion
+ * @param {object} schema - JSON Schema con propiedad opcional $schemaVersion
+ * @returns {{
+ *   compatible: boolean,
+ *   modo: "none" | "backward" | "forward" | "incompatible",
+ *   advertencias: string[]
+ * }}
+ *
+ * Casos:
+ *   - Ambos sin $schemaVersion → { compatible: true, modo: "none", advertencias: [warning] }
+ *   - Documento sin, schema con  → { compatible: true, modo: "forward", advertencias: [warning] }
+ *   - Doc 1.0.0 vs Schema 1.0.0  → { compatible: true, modo: "none" }
+ *   - Doc 1.0.0 vs Schema 1.1.0  → { compatible: true, modo: "forward" } (dato viejo + código nuevo)
+ *   - Doc 1.1.0 vs Schema 1.0.0  → { compatible: true, modo: "backward" } (dato nuevo + código viejo)
+ *   - Doc 2.0.0 vs Schema 1.0.0  → { compatible: false, modo: "incompatible" } (MAJOR rompe)
+ *   - Doc 1.0.0 vs Schema 2.0.0  → { compatible: false, modo: "incompatible" }
+ *   - Versión malformada         → { compatible: false, modo: "incompatible", advertencias: [error] }
+ */
+function verificarCompatibilidad(documento, schema) {
+  const advertencias = [];
+
+  const docVerStr = documento && documento.$schemaVersion;
+  const schVerStr = schema && schema.$schemaVersion;
+
+  if (!docVerStr && !schVerStr) {
+    return {
+      compatible: true,
+      modo: 'none',
+      advertencias: [
+        'Ni documento ni schema declaran $schemaVersion. Compatibilidad asumida pero no verificable.',
+      ],
+    };
+  }
+
+  if (!docVerStr && schVerStr) {
+    return {
+      compatible: true,
+      modo: 'forward',
+      advertencias: [
+        `Documento sin $schemaVersion contra schema ${schVerStr}. Asumiendo forward-compat (código nuevo lee dato viejo sin versión).`,
+      ],
+    };
+  }
+
+  if (docVerStr && !schVerStr) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [
+        `Documento declara $schemaVersion ${docVerStr} pero schema no la declara. Schema debe actualizarse a $schemaVersion para validación correcta.`,
+      ],
+    };
+  }
+
+  const docVer = parsearVersion(docVerStr);
+  const schVer = parsearVersion(schVerStr);
+
+  if (!docVer) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [`Documento $schemaVersion malformada: "${docVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
+    };
+  }
+  if (!schVer) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [`Schema $schemaVersion malformada: "${schVerStr}". Debe ser MAJOR.MINOR.PATCH (ej: "1.0.0").`],
+    };
+  }
+
+  const [docMaj, docMin] = docVer;
+  const [schMaj, schMin] = schVer;
+
+  // MAJOR distinto → incompatible (regla DDIA Cap 4: MAJOR es breaking)
+  if (docMaj !== schMaj) {
+    return {
+      compatible: false,
+      modo: 'incompatible',
+      advertencias: [
+        `MAJOR diferente: documento ${docVerStr} vs schema ${schVerStr}. ` +
+        `Cambios MAJOR son breaking por convención SemVer. Migración explícita requerida.`,
+      ],
+    };
+  }
+
+  // Mismo MAJOR.MINOR → compatible total (PATCH no afecta estructura)
+  if (docMin === schMin) {
+    return { compatible: true, modo: 'none', advertencias: [] };
+  }
+
+  // Documento MINOR menor que schema → forward (código nuevo lee dato viejo)
+  if (docMin < schMin) {
+    return {
+      compatible: true,
+      modo: 'forward',
+      advertencias: [
+        `Documento ${docVerStr} más antiguo que schema ${schVerStr}. ` +
+        `Forward-compat: código nuevo debe ignorar campos nuevos ausentes en dato viejo.`,
+      ],
+    };
+  }
+
+  // Documento MINOR mayor que schema → backward (código viejo lee dato nuevo)
+  return {
+    compatible: true,
+    modo: 'backward',
+    advertencias: [
+      `Documento ${docVerStr} más nuevo que schema ${schVerStr}. ` +
+      `Backward-compat: código viejo debe ignorar campos desconocidos en dato nuevo.`,
+    ],
+  };
+}
+
+module.exports = {
+  parsearVersion,
+  verificarCompatibilidad,
+};

package/scripts/validar-manifest.js

@@ -188,7 +188,7 @@ function main() {
   const categorias = [
     { etiqueta: 'comandos/swl/',       archivos: listarArchivos('comandos/swl', '.md') },
     { etiqueta: 'hooks/ (ejecutables)', archivos: hooksEjecutables },
-    { etiqueta: 'agentes/',             archivos: listarArchivos('agentes', '.md') },
+    { etiqueta: 'agentes/',             archivos: listarArchivos('agentes', '.md').filter(a => !path.basename(a).startsWith('_')) },
     { etiqueta: 'habilidades/ (dirs)',  archivos: listarDirectoriosHabilidades() },
     { etiqueta: 'reglas/',              archivos: listarArchivos('reglas', '.md', true) },
   ];

package/scripts/validar.js

@@ -63,8 +63,9 @@ if (fs.existsSync(hooksConfigPath)) {
   }
 }
 
-// 5. Agentes (mínimo 12)
-const agentes = fs.readdirSync(path.join(RAIZ, 'agentes')).filter(f => f.endsWith('.md'));
+// 5. Agentes (mínimo 12) — excluye fragmentos compartidos (`_*.md`, ver `reglas/fragmentos-compartidos.md`)
+const agentes = fs.readdirSync(path.join(RAIZ, 'agentes'))
+  .filter(f => f.endsWith('.md') && !f.startsWith('_'));
 verificar(agentes.length >= 12, `Agentes: ${agentes.length} (mínimo 12)`);
 
 // Verificar frontmatter en agentes