openprompt-lang 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openprompt-lang",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "PromptLang CLI — Context Engine de anotaciones para desarrollo asistido por IA",
   "type": "module",
   "main": "./bin/cli.js",

package/src/boost/validation-loop.js

@@ -1,4 +1,4 @@
-// @use(kind, contract, limit, error)
+// @use(kind, contract, limit, error, learn-error)
 // @kind(util)
 // @contract(in: code, kind, profile -> out: feedbackLoop -> { code, history, report } @error: ValidationFailedError, EscalationFailedError)
 // @limit(lines: 300)
@@ -78,12 +78,19 @@ export function validateCode(code, kind) {
     writeFileSync(tempFile, code, "utf-8")
 
     // Ejecutar validación
+    // @learn-error id=BOOST-VALIDATE-001
+    //   input='validation-loop.js llamaba npx openprompt-lang validate sin guarda de recursión'
+    //   expected='Si el pipeline ejecuta validate indirectamente, no debe crear fork bomb'
+    //   actual='validate podía llamarse a sí mismo recursivamente si Boost estaba activo y el pipeline contenía scripts que llevaran a validate'
+    //   fix='Agregar OPL_VALIDATE_RECURSION_GUARD al entorno del proceso hijo para que validate.js sepa que ya está en contexto anidado'
+    //   category=recursion
     let output
     try {
       output = execSync(`${VALIDATION_CMD} ${tempFile} 2>&1`, {
         encoding: "utf-8",
         timeout: 10000,
         cwd: process.cwd(),
+        env: { ...process.env, OPL_VALIDATE_RECURSION_GUARD: "1" },
       })
     } catch (execErr) {
       // validate devuelve código de error si hay problemas

package/src/commands/validate.js

@@ -224,18 +224,32 @@ export async function validate(options) {
               annotationErrors++
               console.log(chalk.red(`  ❌ ${relPath}: ${err}`))
             }
-            // En modo friendly: @limit es "deuda documentada" (info), no error
-            // En modo strict: warnings ya se mostraron como [strict] errors — evitamos duplicado
-            if (!strictMode) {
-              for (const warn of warnings) {
-                if (warn.includes("@limit(lines)")) {
-                  annotationDebt++
-                  console.log(chalk.dim(`  📋 ${relPath}: ${warn}`))
-                } else {
-                  annotationWarnings++
-                  console.log(chalk.yellow(`  ⚠️  ${relPath}: ${warn}`))
-                }
+            // Clasificar warnings según tipo:
+            // - [DEBT-reason: ...] → deuda documentada con justificación (info, incluso en strict)
+            // - @limit(lines) sin reason → deuda genérica (info, no error en modo friendly)
+            // - otros warnings → advertencia normal
+            for (const warn of warnings) {
+              const debtReasonMatch = warn.match(/^\[DEBT-reason:\s*(.+?)\]\s*(.*)/)
+              if (debtReasonMatch) {
+                // Deuda documentada CON justificación explícita
+                // Siempre se muestra como info, incluso en strict mode
+                const reason = debtReasonMatch[1]
+                const detail = debtReasonMatch[2]
+                annotationDebt++
+                console.log(chalk.dim(`  📋 ${relPath}: ${detail}`))
+                console.log(chalk.dim(`       🔍 Razón: ${reason}`))
+              } else if (warn.includes("@limit(lines)") && !strictMode) {
+                // Deuda genérica sin razón (solo en modo friendly)
+                annotationDebt++
+                console.log(chalk.dim(`  📋 ${relPath}: ${warn}`))
+              } else if (!strictMode) {
+                // Advertencia normal (solo en modo friendly)
+                annotationWarnings++
+                console.log(chalk.yellow(`  ⚠️  ${relPath}: ${warn}`))
               }
+              // En strict mode: los warnings sin [DEBT-reason] ya se mostraron como [strict] errors
+              // gracias al lintFile(strictMode) que los promociona — evitamos duplicado.
+              // Los [DEBT-reason] siempre pasan porque son deuda documentada.
             }
           }
         } catch {
@@ -282,7 +296,21 @@ export async function validate(options) {
   // ── Execute Phase ───────────────────────────────────────────────────────
 
   // [4/5] Pipeline scripts with auto-healing
+  // @learn-error id=VALIDATE-001
+  //   input='El pipeline pre-commit incluía validate:strict que ejecuta npx openprompt-lang validate --strict'
+  //   expected='Los pasos del pipeline deben ser herramientas externas, no el mismo validate'
+  //   actual='validate.js se llamaba a sí mismo recursivamente vía execSync, creando un fork bomb'
+  //   fix='Eliminar validate:strict de los pasos del pipeline y agregar guarda de recursión OPL_VALIDATE_RECURSION_GUARD'
+  //   category=recursion
   pipeline.use(async (ctx) => {
+    // ── RECURSION GUARD: evitar que validate se llame a sí mismo ──
+    // Si este proceso ya es hijo de otro validate (detectado por env var),
+    // saltamos el paso [4/5] para romper la cadena de recursión.
+    if (process.env.OPL_VALIDATE_RECURSION_GUARD) {
+      console.log(chalk.dim("     ↪ Guard recursivo activo: saltando pipeline interno para evitar fork bomb"))
+      return
+    }
+
     console.log(chalk.yellow("\n[4/5] Ejecutando pipeline..."))
     const scripts = config.pipeline?.scripts || {}
     const pipelineSteps = config.pipeline?.["pre-commit"] || []
@@ -301,6 +329,15 @@ export async function validate(options) {
         continue
       }
 
+      // ── SELF-REFERENCE GUARD: evitar que validate se llame a sí mismo ──
+      // Detecta si el script contiene "openprompt-lang validate" (con cualquier flag)
+      // y previene la ejecución recursiva.
+      if (/openprompt-lang\s+validate/.test(scriptCmd)) {
+        console.log(chalk.yellow(`  ⚠️  "${step}" → "${scriptCmd}" es auto-referencia. Saltando para evitar recursión.`))
+        console.log(chalk.dim("     ℹ️  El validate externo ya ejecutó la validación. No necesita re-validarse."))
+        continue
+      }
+
       let success = false
       let lastError = ""
 
@@ -325,7 +362,12 @@ export async function validate(options) {
 
         try {
           process.stdout.write(`  ▶️  ${step}... `)
-          execSync(scriptCmd, { cwd: baseDir, stdio: "pipe", timeout: 60000 })
+          execSync(scriptCmd, {
+            cwd: baseDir,
+            stdio: "pipe",
+            timeout: 60000,
+            env: { ...process.env, OPL_VALIDATE_RECURSION_GUARD: "1" },
+          })
           console.log(chalk.green("✅"))
           success = true
           break

package/src/utils/annotations.js

@@ -78,7 +78,14 @@ export function validateAnnotations(annotations, validTags, options = {}) {
           const expected = maxLines[kindValue]
           const numVal = parseInt(linesArg.value)
           if (expected && !isNaN(numVal) && numVal > expected) {
-            warnings.push(`@kind(${kindValue}) @limit(lines) debería ser ≤ ${expected} (actual: ${linesArg.value})`)
+            // @limit(lines: N, reason: "...") permite documentar deuda técnica
+            // Cuando hay `reason`, se marca como [DEBT] en vez de warning/error
+            const reasonArg = limitTag.args.find((a) => a.key === 'reason')
+            if (reasonArg && reasonArg.value) {
+              warnings.push(`[DEBT-reason: ${reasonArg.value}] @kind(${kindValue}) @limit(lines) excede el límite recomendado (${expected}). Nuevo límite: ${linesArg.value}.`)
+            } else {
+              warnings.push(`@kind(${kindValue}) @limit(lines) debería ser ≤ ${expected} (actual: ${linesArg.value})`)
+            }
           }
           if (!isNaN(numVal) && numVal <= 0) {
             errors.push(`@limit(lines: ${numVal}) debe ser mayor a 0`)
@@ -264,12 +271,17 @@ export function lintFile(code, strict = false, options = {}) {
 
   const { errors, warnings } = validateAnnotations(annotations, validTags)
   const allErrors = [...parseErrors, ...errors]
-  const allWarnings = [...warnings]
 
-  if (strict && allWarnings.length > 0) {
-    allErrors.push(...allWarnings.map((w) => `[strict] ${w}`))
-    return { annotations, errors: allErrors, warnings: allWarnings }
+  // Separar deuda documentada con razón explícita del resto de warnings
+  // [DEBT-reason] es deuda técnica formalmente justificada — NO debe bloquear commits
+  // incluso en strict mode. El desarrollador documentó por qué el límite se excede.
+  const debtWarnings = warnings.filter((w) => w.startsWith('[DEBT-reason'))
+  const regularWarnings = warnings.filter((w) => !w.startsWith('[DEBT-reason'))
+
+  if (strict && regularWarnings.length > 0) {
+    allErrors.push(...regularWarnings.map((w) => `[strict] ${w}`))
+    return { annotations, errors: allErrors, warnings: [...debtWarnings, ...regularWarnings] }
   }
 
-  return { annotations, errors: allErrors, warnings: allWarnings }
+  return { annotations, errors: allErrors, warnings: [...debtWarnings, ...regularWarnings] }
 }