openprompt-lang 1.2.7 → 1.4.0

package/src/boost/fewshot-retriever.js

@@ -0,0 +1,332 @@
+// @use(kind, contract, limit, error)
+// @kind(util)
+// @contract(in: kind, task, profile -> out: retrieveExamples -> example[] @error: NoExamplesFound)
+// @limit(lines: 250)
+
+/**
+ * Few-Shot Example Engine — Módulo OPL Boost
+ *
+ * Busca ejemplos relevantes en el proyecto y knowledge-repo para
+ * inyectarlos como few-shot examples en los prompts de los agentes.
+ *
+ * Los modelos pequeños mejoran dramáticamente cuando tienen ejemplos
+ * concretos del mismo dominio y @kind antes de generar código.
+ *
+ * Uso:
+ *   import { retrieveExamples, buildFewShotPrompt } from './boost/fewshot-retriever.js'
+ *
+ *   const examples = retrieveExamples('hook', 'crea hook useAuth con Supabase')
+ *   const prompt = buildFewShotPrompt(examples, 'Genera un hook useAuth...')
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from "fs"
+import { join, extname } from "path"
+
+// ──────────────────────────────────────────────
+// Configuración
+// ──────────────────────────────────────────────
+
+const MAX_EXAMPLES = 3
+const MAX_EXAMPLE_LINES = 60
+const EXAMPLE_MATCH_THRESHOLD = 0.3
+
+// ──────────────────────────────────────────────
+// Búsqueda en directorios del proyecto
+// ──────────────────────────────────────────────
+
+/**
+ * Busca ejemplos en los directorios del proyecto según el @kind.
+ * Busca archivos con patrones de naming y contenido relevante.
+ */
+const SEARCH_PATTERNS = {
+  hook: [
+    { dir: "src", pattern: ["**/hooks/**/*.ts", "**/hooks/**/*.tsx"], kindAnnotation: "hook" },
+    { dir: "src", pattern: ["**/lib/hooks/**/*.ts"], kindAnnotation: "hook" },
+    { dir: "src", pattern: ["**/features/*/hooks/*.ts"], kindAnnotation: "hook" },
+  ],
+  component: [
+    { dir: "src", pattern: ["**/components/**/*.tsx"], kindAnnotation: "component" },
+    { dir: "src", pattern: ["**/ui/**/*.tsx"], kindAnnotation: "component" },
+    { dir: "src", pattern: ["**/features/*/components/*.tsx"], kindAnnotation: "component" },
+  ],
+  page: [
+    { dir: "src", pattern: ["**/pages/**/*.tsx", "**/app/**/page.tsx"], kindAnnotation: "page" },
+    { dir: "src", pattern: ["**/features/*/pages/*.tsx"], kindAnnotation: "page" },
+  ],
+  service: [
+    { dir: "src", pattern: ["**/lib/api/**/*.ts", "**/services/**/*.ts"], kindAnnotation: "service" },
+    { dir: "src", pattern: ["**/lib/*.ts"], kindAnnotation: "service" },
+  ],
+  store: [
+    { dir: "src", pattern: ["**/stores/**/*.ts", "**/store/**/*.ts"], kindAnnotation: "store" },
+    { dir: "src", pattern: ["**/lib/stores/**/*.ts"], kindAnnotation: "store" },
+  ],
+}
+
+/**
+ * Escanea un directorio buscando archivos que coincidan con un patrón glob simplificado.
+ * Esta es una versión básica sin glob — solo busca por extensión y nombre de directorio.
+ */
+function scanDir(baseDir, searchPath, keyword) {
+  const results = []
+  const fullDir = join(process.cwd(), searchPath.dir)
+
+  if (!existsSync(fullDir)) return results
+
+  try {
+    const files = walkDir(fullDir, [])
+    for (const file of files) {
+      const ext = extname(file)
+      if (!ext.match(/\.(ts|tsx|js|jsx)$/)) continue
+
+      // Verificar si el path coincide con el patrón
+      const relativePath = file.replace(process.cwd(), "")
+      const hasKeywordInPath = !keyword || relativePath.toLowerCase().includes(keyword.toLowerCase())
+
+      // Leer primeras líneas para verificar @kind
+      try {
+        const content = readFileSync(file, "utf-8")
+        const firstLines = content.split("\n").slice(0, 10).join("\n")
+        const hasKindAnnotation = firstLines.includes(`@kind(${searchPath.kindAnnotation})`)
+
+        if (hasKindAnnotation && hasKeywordInPath) {
+          results.push({
+            file: relativePath,
+            content: content.split("\n").slice(0, MAX_EXAMPLE_LINES).join("\n"),
+            kind: searchPath.kindAnnotation,
+            lines: content.split("\n").length,
+            annotation: readAnnotations(firstLines),
+          })
+        }
+      } catch {
+        // Archivo no legible
+      }
+    }
+  } catch {
+    // Directorio no accesible
+  }
+
+  return results
+}
+
+function walkDir(dir, files) {
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory() && !entry.name.startsWith(".") && !entry.name.startsWith("node_modules")) {
+        walkDir(fullPath, files)
+      } else if (entry.isFile()) {
+        files.push(fullPath)
+      }
+    }
+  } catch {
+    // Directorio no accesible
+  }
+  return files
+}
+
+function readAnnotations(firstLines) {
+  const annotations = []
+  const lines = firstLines.split("\n")
+  for (const line of lines.slice(0, 5)) {
+    const match = line.match(/\/\/\s*@(\w+)\((.*)\)/)
+    if (match) {
+      annotations.push({ name: match[1], value: match[2] })
+    }
+  }
+  return annotations
+}
+
+// ──────────────────────────────────────────────
+// Ranking de relevancia
+// ──────────────────────────────────────────────
+
+/**
+ * Calcula un score de relevancia entre un ejemplo y la tarea.
+ *
+ * Factores:
+ *   1. Matching de @kind (peso 0.4)
+ *   2. Palabras clave compartidas (peso 0.3)
+ *   3. Tamaño del archivo (peso 0.2) — preferir archivos pequeños
+ *   4. Cercanía en el filesystem (peso 0.1)
+ */
+function scoreRelevance(example, kind, taskKeywords) {
+  let score = 0
+
+  // Factor 1: @kind matching (0-0.4)
+  if (example.kind === kind) {
+    score += 0.4
+  } else {
+    score += 0.1 // algo de relevancia aunque sea otro tipo
+  }
+
+  // Factor 2: Palabras clave compartidas (0-0.3)
+  if (taskKeywords.length > 0) {
+    const content = example.content.toLowerCase()
+    const matchedKeywords = taskKeywords.filter((kw) => content.includes(kw.toLowerCase()))
+    score += (matchedKeywords.length / taskKeywords.length) * 0.3
+  } else {
+    score += 0.15
+  }
+
+  // Factor 3: Tamaño del archivo (0-0.2) — preferir archivos más pequeños
+  const lineScore = Math.max(0, 1 - example.lines / 100)
+  score += lineScore * 0.2
+
+  // Factor 4: Cercanía de path (0-0.1) — ejemplos en directorios similares tienen más peso
+  const pathDepth = example.file.split("/").length
+  score += (1 / pathDepth) * 0.1
+
+  return Math.min(score, 1.0)
+}
+
+function extractKeywordsFromTask(task) {
+  const stopWords = new Set([
+    "el", "la", "los", "las", "un", "una", "de", "del", "en", "con",
+    "para", "por", "que", "es", "se", "no", "su", "lo", "como", "más",
+    "pero", "sus", "le", "ya", "este", "entre", "porque", "the", "a",
+    "an", "of", "in", "to", "for", "and", "or", "is", "it", "on", "at",
+    "crea", "crear", "hacer", "haz", "genera", "generar", "nuevo", "nueva",
+  ])
+  return task.toLowerCase().split(/\s+/).filter((w) => w.length > 2 && !stopWords.has(w))
+}
+
+// ──────────────────────────────────────────────
+// API: retrieveExamples
+// ──────────────────────────────────────────────
+
+/**
+ * Busca ejemplos relevantes para una tarea de generación.
+ *
+ * @param {string} kind - Tipo de archivo a generar (hook, component, page, service, store)
+ * @param {string} task - Descripción de la tarea
+ * @param {object} [options] - Opciones adicionales
+ * @param {number} [options.maxExamples=3] - Máximo de ejemplos a retornar
+ * @param {number} [options.threshold=0.3] - Umbral mínimo de relevancia
+ * @param {boolean} [options.includeTemplates=true] - Incluir templates de OPL como fallback
+ * @returns {Array<{ file: string, content: string, kind: string, score: number, annotations: Array }>}
+ */
+export function retrieveExamples(kind, task, options = {}) {
+  const maxExamples = options.maxExamples || MAX_EXAMPLES
+  const threshold = options.threshold || EXAMPLE_MATCH_THRESHOLD
+  const includeTemplates = options.includeTemplates !== false
+  const taskKeywords = extractKeywordsFromTask(task)
+
+  // 1. Buscar en el proyecto
+  const patterns = SEARCH_PATTERNS[kind] || SEARCH_PATTERNS.component
+  let candidates = []
+
+  for (const pattern of patterns) {
+    const results = scanDir("", pattern)
+    candidates.push(...results)
+  }
+
+  // 2. Calcular relevancia
+  const scored = candidates.map((c) => ({
+    ...c,
+    score: scoreRelevance(c, kind, taskKeywords),
+  }))
+
+  // 3. Ordenar por score descendente
+  scored.sort((a, b) => b.score - a.score)
+
+  // 4. Filtrar por umbral
+  let filtered = scored.filter((e) => e.score >= threshold)
+
+  // 5. Si no hay suficientes ejemplos, buscar en otras carpetas
+  if (filtered.length < maxExamples && includeTemplates) {
+    // Buscar en todos los patrones (cross-kind) como fallback
+    for (const [otherKind, otherPatterns] of Object.entries(SEARCH_PATTERNS)) {
+      if (otherKind === kind) continue
+      for (const pattern of otherPatterns) {
+        const results = scanDir("", pattern)
+        for (const r of results) {
+          const existing = filtered.find((f) => f.file === r.file)
+          if (!existing) {
+            const sc = scoreRelevance(r, kind, taskKeywords)
+            if (sc >= threshold * 0.5) {
+              filtered.push({ ...r, score: sc })
+            }
+          }
+        }
+      }
+    }
+
+    // Re-ordenar
+    filtered.sort((a, b) => b.score - a.score)
+  }
+
+  return filtered.slice(0, maxExamples)
+}
+
+// ──────────────────────────────────────────────
+// API: buildFewShotPrompt
+// ──────────────────────────────────────────────
+
+/**
+ * Construye un prompt con ejemplos few-shot inyectados.
+ *
+ * @param {Array} examples - Resultados de retrieveExamples()
+ * @param {string} userPrompt - Prompt del usuario para la tarea
+ * @returns {string} Prompt completo con ejemplos
+ */
+export function buildFewShotPrompt(examples, userPrompt) {
+  if (!examples || examples.length === 0) {
+    return userPrompt
+  }
+
+  const parts = [
+    "## Instrucción",
+    "",
+    "Genera código siguiendo el mismo patrón que los ejemplos siguientes.",
+    "Respeta las anotaciones OPL (@kind, @limit, @contract/@props/@compose).",
+    "",
+    "## Ejemplos",
+    "",
+  ]
+
+  for (let i = 0; i < examples.length; i++) {
+    const ex = examples[i]
+    parts.push(`### Ejemplo ${i + 1}: ${ex.file}`)
+    parts.push(`Tipo: ${ex.kind} | Relevancia: ${(ex.score * 100).toFixed(0)}%`)
+    parts.push("")
+    parts.push("```typescript")
+    parts.push(ex.content || "// (contenido no disponible)")
+    parts.push("```")
+    parts.push("")
+  }
+
+  parts.push("## Tarea")
+  parts.push("")
+  parts.push(userPrompt)
+
+  return parts.join("\n")
+}
+
+// ──────────────────────────────────────────────
+// API: exampleStats
+// ──────────────────────────────────────────────
+
+/**
+ * Estadísticas de ejemplos encontrados en el proyecto.
+ * Útil para diagnóstico (opl boost check).
+ *
+ * @returns {object} { total: number, byKind: object, lastUpdated: string }
+ */
+export function exampleStats() {
+  const stats = { total: 0, byKind: {} }
+
+  for (const [kind, patterns] of Object.entries(SEARCH_PATTERNS)) {
+    for (const pattern of patterns) {
+      const results = scanDir("", pattern)
+      stats.total += results.length
+      stats.byKind[kind] = (stats.byKind[kind] || 0) + results.length
+    }
+  }
+
+  return {
+    ...stats,
+    lastUpdated: new Date().toISOString(),
+  }
+}