openprompt-lang 1.2.7 → 1.3.0

package/src/core/workflow/selector.js

@@ -0,0 +1,707 @@
+// @kind(module)
+// @contract(in: taskDescription:string, options:object -> out: {workflowId:string, label:string, steps:array, confidence:number})
+// @limit(lines: 610)
+// @pattern(provider)
+// @deps(@external: [path, fs])
+
+/**
+ * Selector inteligente de workflows.
+ *
+ * Analiza la descripción de una tarea y selecciona el workflow más adecuado
+ * basado en matching de keywords contra los triggers definidos en workflows.json.
+ *
+ * Soporta:
+ * - Matching por keywords exactas y parciales
+ * - Puntaje de confianza (0-1) basado en cobertura de triggers
+ * - Detección de tipo de tarea (feature, bugfix, refactor, docs, research)
+ * - Fallback inteligente cuando no hay match perfecto
+ * - Detección de conflictos con planes existentes
+ * - Detección de tickets existentes que se solapan
+ *
+ * Uso:
+ *   import { selectWorkflow } from './selector.js';
+ *   const match = selectWorkflow("Implementar tabla de reportes con filtros");
+ *   console.log(match.label); // "Nueva Feature"
+ *   match.steps.forEach(s => console.log(`${s.step}. ${s.action}`));
+ */
+
+import { readFileSync, existsSync, readdirSync } from "fs"
+import { join } from "path"
+
+/**
+ * @typedef {object} WorkflowMatch
+ * @property {string} workflowId - ID del workflow seleccionado
+ * @property {string} label - Nombre legible del workflow
+ * @property {string} icon - Icono del workflow
+ * @property {Array} steps - Pasos a seguir (renumerados)
+ * @property {number} confidence - Confianza del match (0-1)
+ * @property {string[]} [knowledge_refs] - Referencias de conocimiento recomendadas
+ * @property {string[]} [tips] - Tips del workflow
+ * @property {string} taskType - Tipo detectado de tarea
+ * @property {boolean} requiresTicket - Si requiere ticket antes de implementar
+ * @property {boolean} requiresDocs - Si requiere actualizar docs al cerrar
+ * @property {boolean} requiresPlan - Si requiere plan antes de implementar
+ * @property {Array} [pendingAdjustments] - Ajustes pendientes de planes existentes
+ * @property {Array} [existingTickets] - Tickets existentes que se solapan
+ */
+
+/**
+ * @typedef {object} Workflow
+ * @property {string} label
+ * @property {string} icon
+ * @property {string[]} trigger
+ * @property {Array} steps
+ * @property {string[]} [knowledge_refs]
+ * @property {string[]} [tips]
+ */
+
+/** Tipos de tarea detectables con sus requerimientos */
+const TASK_TYPES = Object.freeze({
+  bugfix: { requiresTicket: true, requiresDocs: true, requiresPlan: false },
+  feature: { requiresTicket: true, requiresDocs: true, requiresPlan: true },
+  refactor: { requiresTicket: true, requiresDocs: false, requiresPlan: true },
+  docs: { requiresTicket: false, requiresDocs: true, requiresPlan: false },
+  research: { requiresTicket: false, requiresDocs: false, requiresPlan: false },
+  enhancement: { requiresTicket: true, requiresDocs: true, requiresPlan: true },
+  config: { requiresTicket: false, requiresDocs: true, requiresPlan: false },
+  unknown: { requiresTicket: true, requiresDocs: true, requiresPlan: true },
+})
+
+/** Keywords para detectar tipo de tarea */
+const TYPE_PATTERNS = Object.freeze({
+  bugfix: [
+    "bug",
+    "error",
+    "fallo",
+    "crash",
+    "exception",
+    "no funciona",
+    "fix",
+    "arreglar",
+    "bugfix",
+    "hotfix",
+    "issue",
+    "problema",
+    "incorrecto",
+    "mal",
+    "roto",
+    "stack trace",
+    "traceback",
+    "unexpected",
+    "fails",
+    "falla",
+  ],
+  feature: [
+    "implementar",
+    "agregar",
+    "nuev",
+    "feature",
+    "crear",
+    "añadir",
+    "soporte para",
+    "función",
+    "funcionalidad",
+    "modulo",
+    "módulo",
+    "componente",
+    "página",
+    "vista",
+    "integrar",
+    "desarrollar",
+    "construir",
+    "hacer",
+  ],
+  refactor: [
+    "refactor",
+    "reorganizar",
+    "limpiar",
+    "optimizar",
+    "mejorar rendimiento",
+    "reestructurar",
+    "simplificar",
+    "modularizar",
+    "extraer",
+    "separar",
+    "reordenar",
+    "renombrar",
+    "dividir",
+    "consolidar",
+    "unificar",
+  ],
+  docs: [
+    "documentar",
+    "readme",
+    "documentación",
+    "doc",
+    "mermaid",
+    "diagrama",
+    "wiki",
+    "api doc",
+    "swagger",
+    "manual",
+    "guía",
+    "tutorial",
+    "ejemplo",
+    "comment",
+    "comentario",
+    "explicación",
+  ],
+  research: [
+    "investigar",
+    "explorar",
+    "analizar",
+    "evaluar",
+    "comparar",
+    "research",
+    "spike",
+    "proof of concept",
+    "poc",
+    "viabilidad",
+    "factibilidad",
+    "estudio",
+    "diagnóstico",
+  ],
+  enhancement: [
+    "mejorar",
+    "enhance",
+    "optimizar",
+    "actualizar",
+    "upgrade",
+    "migrar",
+    "modernizar",
+    "adaptar",
+    "ampliar",
+    "extender",
+    "añadir funcionalidad",
+    "nueva capacidad",
+    "más rápido",
+  ],
+  config: [
+    "configurar",
+    "setup",
+    "instalar",
+    "desplegar",
+    "deploy",
+    "config",
+    "environ",
+    "variable de entorno",
+    "ci/cd",
+    "docker",
+    "compilar",
+    "build",
+    "empaquetar",
+    "distribuir",
+  ],
+})
+
+/**
+ * Carga los workflows desde workflows.json.
+ *
+ * @returns {object} Diccionario de workflows
+ */
+function loadWorkflows() {
+  const paths = [
+    join(process.cwd(), ".opencode", "workflows.json"),
+    join(process.cwd(), "..", ".opencode", "workflows.json"),
+    join(import.meta.dirname, "..", "..", "..", ".opencode", "workflows.json"),
+  ]
+
+  for (const p of paths) {
+    if (existsSync(p)) {
+      try {
+        const raw = readFileSync(p, "utf-8")
+        const parsed = JSON.parse(raw)
+        return parsed.workflows || parsed
+      } catch (err) {
+        console.error(`[selector] Error cargando workflows desde ${p}:`, err.message)
+        return getDefaultWorkflows()
+      }
+    }
+  }
+
+  return getDefaultWorkflows()
+}
+
+/**
+ * Workflows por defecto cuando no existe workflows.json.
+ *
+ * @returns {object}
+ */
+function getDefaultWorkflows() {
+  return {
+    feature: {
+      label: "Nueva Feature",
+      icon: "🚀",
+      trigger: ["implementar", "feature", "nuevo", "crear", "agregar", "soporte"],
+      steps: [
+        { step: 1, action: "analyze_project", purpose: "Analizar estructura actual" },
+        {
+          step: 2,
+          action: "context_unified",
+          query: "{task}",
+          purpose: "Buscar contexto relevante",
+        },
+        { step: 3, action: "work_context_plan", purpose: "Planificar implementación" },
+        {
+          step: 4,
+          action: "implement",
+          rules: ["Anotaciones OPL primero", "Named exports", "Máx 300 líneas"],
+        },
+        { step: 5, action: "validate", purpose: "Verificar anotaciones" },
+        { step: 6, action: "generate_tests", purpose: "Tests de regresión" },
+        { step: 7, action: "docs_updated", purpose: "Actualizar documentación" },
+      ],
+      knowledge_refs: [],
+      tips: ["Siempre comenzar con anotaciones OPL antes de implementar lógica"],
+    },
+    bugfix: {
+      label: "Corrección de Bug",
+      icon: "🐛",
+      trigger: ["bug", "error", "fix", "fallo", "no funciona"],
+      steps: [
+        { step: 1, action: "recall", query: "error {task}", purpose: "Buscar errores previos" },
+        { step: 2, action: "lint_file", purpose: "Verificar anotaciones del archivo" },
+        { step: 3, action: "fix", rules: ["@learn-error", "Nunca as para silenciar errores"] },
+        { step: 4, action: "generate_tests", purpose: "Tests de regresión" },
+        { step: 5, action: "validate", purpose: "Verificar fix" },
+      ],
+      knowledge_refs: [],
+      tips: ["Documentar con @learn-error para que la IA aprenda del error"],
+    },
+    refactor: {
+      label: "Refactorización",
+      icon: "🔧",
+      trigger: ["refactor", "reorganizar", "limpiar", "optimizar"],
+      steps: [
+        { step: 1, action: "extract", purpose: "Analizar patrones reutilizables" },
+        { step: 2, action: "validate", purpose: "Verificar anotaciones actuales" },
+        { step: 3, action: "work_context_plan", purpose: "Planificar refactor" },
+        {
+          step: 4,
+          action: "implement",
+          rules: ["Máx 300 líneas", "Named exports", "@limit actualizado"],
+        },
+        { step: 5, action: "validate", purpose: "Verificar post-refactor" },
+      ],
+      knowledge_refs: [],
+      tips: ["Extraer sub-componentes si se excede el límite de líneas"],
+    },
+  }
+}
+
+/**
+ * Detecta el tipo de tarea según las keywords en la descripción.
+ *
+ * @param {string} description - Descripción de la tarea
+ * @returns {string} ID del tipo de tarea
+ */
+function detectTaskType(description) {
+  const lower = description.toLowerCase()
+  let bestType = "unknown"
+  let bestScore = 0
+
+  for (const [type, patterns] of Object.entries(TYPE_PATTERNS)) {
+    let score = 0
+    for (const pattern of patterns) {
+      if (lower.includes(pattern)) {
+        // Más peso para matches al inicio
+        score += lower.startsWith(pattern) ? 2 : 1
+      }
+    }
+    if (score > bestScore) {
+      bestScore = score
+      bestType = type
+    }
+  }
+
+  return bestType
+}
+
+/**
+ * Calcula el puntaje de confianza para un workflow contra la descripción.
+ *
+ * @param {Workflow} workflow - Workflow a evaluar
+ * @param {string} description - Descripción de la tarea en minúsculas
+ * @returns {number} Puntaje 0-1
+ */
+function scoreWorkflow(workflow, description) {
+  const triggers = workflow.trigger || []
+  if (triggers.length === 0) return 0
+
+  let totalScore = 0
+  const maxPossible = triggers.length * 2
+
+  for (const trigger of triggers) {
+    const lowerTrigger = trigger.toLowerCase()
+    if (description.includes(lowerTrigger)) {
+      // Match exacto pesa más
+      totalScore += 2
+    } else {
+      // Match parcial (palabras contenidas)
+      const words = lowerTrigger.split(/\s+/)
+      const matchCount = words.filter((w) => w.length > 2 && description.includes(w)).length
+      totalScore += matchCount / Math.max(words.length, 1)
+    }
+  }
+
+  // Bonus por tipo de tarea alineado
+  for (const [, patterns] of Object.entries(TYPE_PATTERNS)) {
+    for (const pattern of patterns) {
+      if (description.includes(pattern)) {
+        totalScore += 1
+        break
+      }
+    }
+  }
+
+  return Math.min(totalScore / Math.max(maxPossible, 1), 1)
+}
+
+/**
+ * Encuentra planes de trabajo existentes que puedan necesitar ajustes
+ * por la nueva tarea.
+ *
+ * @param {string} description - Descripción de la nueva tarea
+ * @returns {Array} Planes existentes que podrían verse afectados
+ */
+function findPlanConflicts(description) {
+  const plansDir = join(process.cwd(), ".opencode", "work-context", "PLANS")
+  if (!existsSync(plansDir)) return []
+
+  let files = []
+  try {
+    files = readdirSync(plansDir).filter((f) => f.endsWith(".md"))
+  } catch {
+    return []
+  }
+
+  if (files.length === 0) return []
+
+  const conflicts = []
+  const lowerDesc = description.toLowerCase()
+  const words = lowerDesc.split(/\s+/).filter((w) => w.length > 4)
+
+  if (words.length === 0) return []
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(plansDir, file), "utf-8")
+      const lower = content.toLowerCase()
+
+      const overlapCount = words.filter((w) => lower.includes(w)).length
+
+      if (overlapCount >= 2) {
+        conflicts.push({
+          file,
+          overlapCount,
+          existingTask: extractPlanTitle(content),
+        })
+      }
+    } catch {
+      // Saltar archivos que no se puedan leer
+    }
+  }
+
+  return conflicts.sort((a, b) => b.overlapCount - a.overlapCount)
+}
+
+/**
+ * Extrae el título de un plan markdown.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function extractPlanTitle(content) {
+  const match = content.match(/^#\s+(.+)/m)
+  return match ? match[1].trim() : "Plan sin título"
+}
+
+/**
+ * Busca si hay tickets abiertos que ya cubren parte de la tarea.
+ *
+ * @param {string} description
+ * @returns {Array} Tickets existentes que se solapan
+ */
+function findExistingTickets(description) {
+  const bugsDir = join(process.cwd(), ".opencode", "bugs")
+  if (!existsSync(bugsDir)) return []
+
+  try {
+    const files = readdirSync(bugsDir).filter((f) => f.endsWith(".md"))
+    if (files.length === 0) return []
+
+    const lowerDesc = description.toLowerCase()
+    const words = lowerDesc.split(/\s+/).filter((w) => w.length > 4)
+    if (words.length === 0) return []
+
+    const overlapping = []
+
+    for (const file of files) {
+      try {
+        const content = readFileSync(join(bugsDir, file), "utf-8")
+        const statusMatch = content.match(/\*\*Estado\*\*\s+\|\s+(\w+)/)
+        if (statusMatch && ["open", "wip"].includes(statusMatch[1])) {
+          const lower = content.toLowerCase()
+          const overlapCount = words.filter((w) => lower.includes(w)).length
+          if (overlapCount >= 2) {
+            overlapping.push({
+              file,
+              id: file.split("-")[0],
+              overlapCount,
+            })
+          }
+        }
+      } catch {
+        // Saltar archivos que no se puedan leer
+      }
+    }
+
+    return overlapping.sort((a, b) => b.overlapCount - a.overlapCount)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Renumera los pasos secuencialmente.
+ *
+ * @param {Array} steps
+ * @returns {Array}
+ */
+function renumberSteps(steps) {
+  return steps.map((s, i) => ({ ...s, step: i + 1 }))
+}
+
+/**
+ * Selecciona el workflow más adecuado para una descripción de tarea.
+ *
+ * @param {string} taskDescription - Descripción de la tarea a realizar
+ * @param {object} [options] - Opciones adicionales
+ * @param {boolean} [options.checkConflicts=true] - Buscar conflictos con planes existentes
+ * @returns {WorkflowMatch} Resultado del matching
+ */
+export function selectWorkflow(taskDescription, options = {}) {
+  const { checkConflicts = true } = options
+  const desc = taskDescription.trim()
+
+  if (!desc) {
+    return {
+      workflowId: "unknown",
+      label: "Workflow Genérico",
+      icon: "❓",
+      steps: [
+        { step: 1, action: "analyze_project", purpose: "Analizar proyecto" },
+        { step: 2, action: "work_context_plan", purpose: "Planificar" },
+        { step: 3, action: "implement", purpose: "Implementar" },
+        { step: 4, action: "validate", purpose: "Verificar" },
+      ],
+      confidence: 0,
+      taskType: "unknown",
+      requiresTicket: true,
+      requiresDocs: true,
+      requiresPlan: true,
+      pendingAdjustments: [],
+      existingTickets: [],
+    }
+  }
+
+  const workflows = loadWorkflows()
+  const lowerDesc = desc.toLowerCase()
+  const taskType = detectTaskType(desc)
+
+  // Puntuar cada workflow
+  const scored = Object.entries(workflows).map(([id, wf]) => ({
+    workflowId: id,
+    label: wf.label,
+    icon: wf.icon || "📋",
+    steps: wf.steps,
+    knowledge_refs: wf.knowledge_refs || [],
+    tips: wf.tips || [],
+    score: scoreWorkflow(wf, lowerDesc),
+  }))
+
+  // Ordenar por score descendente
+  scored.sort((a, b) => b.score - a.score)
+
+  // Seleccionar el mejor
+  const best = scored[0]
+  const confidence = best.score
+
+  let selected
+  if (confidence < 0.1) {
+    // Baja confianza: buscar por tipo de tarea
+    const typeWorkflowId = Object.keys(workflows).find(
+      (id) => id === taskType || (workflows[id].label || "").toLowerCase().includes(taskType)
+    )
+    if (typeWorkflowId && workflows[typeWorkflowId]) {
+      const wf = workflows[typeWorkflowId]
+      selected = {
+        workflowId: typeWorkflowId,
+        label: wf.label,
+        icon: wf.icon || "📋",
+        steps: wf.steps,
+        knowledge_refs: wf.knowledge_refs || [],
+        tips: wf.tips || [],
+      }
+    } else {
+      selected = {
+        workflowId: "generic",
+        label: "Workflow Genérico",
+        icon: "📋",
+        steps: [
+          { step: 1, action: "analyze_project", purpose: "Analizar proyecto" },
+          { step: 2, action: "context_unified", query: desc, purpose: "Buscar contexto" },
+          { step: 3, action: "work_context_plan", purpose: "Planificar implementación" },
+          { step: 4, action: "implement", purpose: "Implementar" },
+          { step: 5, action: "validate", purpose: "Verificar" },
+          { step: 6, action: "docs_updated", purpose: "Actualizar documentación" },
+        ],
+        knowledge_refs: [],
+        tips: ["Siempre validar con validate antes de cerrar"],
+      }
+    }
+  } else {
+    selected = best
+  }
+
+  // Obtener requerimientos según tipo de tarea
+  const typeInfo = TASK_TYPES[taskType] || TASK_TYPES.unknown
+
+  // Preparar pasos con inyecciones de contexto
+  const steps = [...selected.steps]
+
+  // Buscar conflictos con planes existentes
+  const pendingAdjustments = checkConflicts ? findPlanConflicts(desc) : []
+
+  // Buscar tickets existentes solapados
+  const existingTickets = findExistingTickets(desc)
+
+  // Inyectar pasos contextuales (en orden inverso para no romper índices)
+  if (checkConflicts && pendingAdjustments.length > 0) {
+    steps.unshift({
+      step: 0,
+      action: "adjust_existing_plans",
+      purpose: `Ajustar ${pendingAdjustments.length} plan(es) existente(s) que se solapan con esta tarea`,
+      plans: pendingAdjustments,
+    })
+  }
+
+  if (existingTickets.length > 0) {
+    steps.unshift({
+      step: 0,
+      action: "review_existing_tickets",
+      purpose: `Revisar ${existingTickets.length} ticket(s) existente(s) que cubren parte de esta tarea`,
+      tickets: existingTickets,
+    })
+  }
+
+  // Siempre inyectar paso de ticket si es requerido
+  if (typeInfo.requiresTicket) {
+    const hasTicketStep = steps.some(
+      (s) => s.action === "create_ticket" || s.action === "ticket_create"
+    )
+    if (!hasTicketStep) {
+      steps.unshift({
+        step: 0,
+        action: "create_ticket",
+        purpose: "Crear ticket para trackear esta tarea (requerido antes de implementar)",
+      })
+    }
+  }
+
+  return {
+    workflowId: selected.workflowId,
+    label: selected.label,
+    icon: selected.icon,
+    steps: renumberSteps(steps),
+    confidence,
+    knowledge_refs: selected.knowledge_refs,
+    tips: selected.tips,
+    taskType,
+    requiresTicket: typeInfo.requiresTicket,
+    requiresDocs: typeInfo.requiresDocs,
+    requiresPlan: typeInfo.requiresPlan,
+    pendingAdjustments,
+    existingTickets,
+  }
+}
+
+/**
+ * Lista todos los workflows disponibles.
+ *
+ * @returns {Array<{id:string, label:string, icon:string, triggerCount:number, stepCount:number}>}
+ */
+export function listWorkflows() {
+  const workflows = loadWorkflows()
+  return Object.entries(workflows).map(([id, wf]) => ({
+    id,
+    label: wf.label,
+    icon: wf.icon || "📋",
+    triggerCount: (wf.trigger || []).length,
+    stepCount: (wf.steps || []).length,
+  }))
+}
+
+/**
+ * Genera un resumen legible del workflow seleccionado para mostrar en consola.
+ *
+ * @param {WorkflowMatch} match - Resultado de selectWorkflow()
+ * @returns {string} Texto formateado
+ */
+export function formatWorkflowSummary(match) {
+  const lines = []
+  lines.push(`\n${match.icon}  Workflow: ${match.label}`)
+  lines.push(`   Tipo:      ${match.taskType}`)
+  lines.push(`   Confianza: ${(match.confidence * 100).toFixed(0)}%`)
+  lines.push("")
+
+  if (match.pendingAdjustments && match.pendingAdjustments.length > 0) {
+    lines.push("   ⚠️  Planes existentes que requieren ajuste:")
+    for (const p of match.pendingAdjustments) {
+      lines.push(`       • ${p.file}: "${p.existingTask}"`)
+    }
+    lines.push("")
+  }
+
+  if (match.existingTickets && match.existingTickets.length > 0) {
+    lines.push("   📌 Tickets existentes que se solapan:")
+    for (const t of match.existingTickets) {
+      lines.push(`       • ${t.id} (${t.file})`)
+    }
+    lines.push("")
+  }
+
+  lines.push("   Pasos:")
+  for (const step of match.steps) {
+    const desc = step.purpose ? `— ${step.purpose}` : ""
+    const ticketInfo = step.tickets ? ` (${step.tickets.length} tickets)` : ""
+    const planInfo = step.plans ? ` (${step.plans.length} planes)` : ""
+    lines.push(`     ${step.step}. ${step.action} ${desc}${ticketInfo}${planInfo}`)
+  }
+
+  if (match.knowledge_refs && match.knowledge_refs.length > 0) {
+    lines.push("")
+    lines.push("   📚 Referencias de conocimiento:")
+    for (const ref of match.knowledge_refs) {
+      lines.push(`       • ${ref}`)
+    }
+  }
+
+  if (match.tips && match.tips.length > 0) {
+    lines.push("")
+    lines.push("   💡 Tips:")
+    for (const tip of match.tips) {
+      lines.push(`       • ${tip}`)
+    }
+  }
+
+  lines.push("")
+  const ticketStatus = match.requiresTicket ? "✅ Requiere ticket" : "⏭️  No requiere ticket"
+  const docsStatus = match.requiresDocs ? "✅ Requiere docs" : "⏭️  No requiere docs"
+  const planStatus = match.requiresPlan ? "✅ Requiere plan" : "⏭️  No requiere plan"
+  lines.push(`   ${ticketStatus}`)
+  lines.push(`   ${docsStatus}`)
+  lines.push(`   ${planStatus}`)
+
+  return lines.join("\n")
+}