openprompt-lang 0.3.0

package/src/utils/ai.js

@@ -0,0 +1,143 @@
+/**
+ * openPrompt-Lang AI module
+ * 
+ * Proporciona integración con servicios de IA (OpenAI, opencode, etc.)
+ * para sugerencias automáticas de stack, estructura y scaffolding.
+ * 
+ * Si no hay API key ni opencode, genera un plan detallado para que
+ * la IA externa lo ejecute.
+ */
+
+import chalk from "chalk";
+
+export async function suggestStack(description) {
+  try {
+    // Intenta usar opencode si está disponible
+    const result = await tryOpencode(description);
+    if (result) return result;
+  } catch {
+    // fallback
+  }
+
+  try {
+    // Intenta usar OpenAI si hay API key
+    const result = await tryOpenAI(description);
+    if (result) return result;
+  } catch {
+    // fallback
+  }
+
+  // Fallback: generar plan para IA externa
+  return generateFallbackPlan(description);
+}
+
+async function tryOpencode(description) {
+  try {
+    const { execSync } = await import("child_process");
+    const prompt = `Eres un arquitecto de software. Analiza esta descripción de proyecto y sugiere:
+1. Stack tecnológico (React/Vue/Angular, base de datos, hosting)
+2. Estructura de carpetas inicial
+3. Módulos principales
+4. Prioridades de desarrollo
+
+Descripción: ${description}
+
+Formato de respuesta: JSON con keys: stack, folders, modules, priorities`;
+
+    const result = execSync(`opencode prompt "${prompt}"`, {
+      encoding: "utf-8",
+      timeout: 30000,
+    }).trim();
+
+    return JSON.parse(result);
+  } catch {
+    return null;
+  }
+}
+
+async function tryOpenAI(description) {
+  const apiKey = process.env.OPENAI_API_KEY || process.env.OPENPROMPT_API_KEY;
+  if (!apiKey) return null;
+
+  try {
+    const response = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model: "gpt-4",
+        messages: [
+          {
+            role: "system",
+            content:
+              "Eres un arquitecto de software. Responde siempre en JSON con keys: stack, folders, modules, priorities",
+          },
+          { role: "user", content: `Sugiere stack y estructura para: ${description}` },
+        ],
+        temperature: 0.3,
+      }),
+    });
+
+    const data = await response.json();
+    const content = data.choices?.[0]?.message?.content;
+    if (content) {
+      return JSON.parse(content.replace(/```json/g, "").replace(/```/g, "").trim());
+    }
+  } catch {
+    // fallback
+  }
+
+  return null;
+}
+
+function generateFallbackPlan(description) {
+  const plan = `# INIT_PLAN.md — Plan de Inicialización para IA
+
+## Proyecto
+${description}
+
+## Instrucciones para la IA
+
+Eres un arquitecto de software. Basado en la descripción anterior, genera:
+
+### 1. Stack Tecnológico Sugerido
+- Frontend: React 18 + TypeScript + Vite + Tailwind CSS
+- Backend/DB: Supabase (recomendado) / Firebase / PostgreSQL
+- Estado: Zustand
+- Ruteo: React Router v6
+- Testing: Vitest + Testing Library
+
+### 2. Estructura de Carpetas Inicial
+Sigue el estándar definido en \`docs/patrones de trabajo.md\`:
+- \`src/components/ui/\` — Componentes atómicos
+- \`src/features/\` — Módulos por dominio
+- \`src/hooks/\` — Custom hooks globales
+- \`src/services/supabase/\` — Clientes de API
+- \`src/store/\` — Estado global
+- \`docs/COMMITS/\` — Logs de commits
+- \`docs/LOGS/\` — Logs de errores/actividad
+- \`docs/BACKLOG/\` — Backlog por fases
+
+### 3. Módulos Principales
+Identifica 3-5 módulos principales basados en la descripción.
+Para cada uno: nombre, funcionalidades core, dependencias.
+
+### 4. Prioridades de Desarrollo (PHASE-1)
+Lista las tareas P0 en orden:
+1. Setup del proyecto
+2. Autenticación
+3. Módulo core #1
+4. Módulo core #2
+5. Despliegue inicial
+
+## Notas
+- Usa anotaciones PromptLang (@kind, @contract, @limit) en cada archivo
+- Sigue los límites: hook ≤80 líneas, componente ≤120, página ≤200, servicio ≤150
+- 100% Tailwind utility classes
+- Cada componente debe manejar estados: loading, empty, error, success
+`;
+
+  return { plan, source: "fallback" };
+}

package/src/utils/annotations.js

@@ -0,0 +1,510 @@
+import chalk from "chalk";
+
+// ─── Parser ────────────────────────────────────────────────────────────────
+
+export function parseAnnotations(code) {
+  const annotations = [];
+  const lines = code.split("\n");
+  const errors = [];
+
+  let currentBlock = null;
+  let inBlock = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Detecta bloque de anotaciones /* ... */
+    if (trimmed.startsWith("/*")) {
+      inBlock = true;
+      currentBlock = "";
+      const cleaned = trimmed.replace(/^\/\*+\s*/, "").replace(/\s*\*+\/$/, "").trim();
+      // Solo procesamos si hay contenido (si la línea era solo /*, esperamos a la siguiente)
+      if (cleaned) {
+        currentBlock += cleaned + " ";
+      }
+      if (trimmed.includes("*/")) {
+        inBlock = false;
+        if (currentBlock.trim()) {
+          annotations.push(...parseTags(currentBlock));
+        }
+        currentBlock = null;
+      }
+      continue;
+    }
+
+    if (inBlock) {
+      if (trimmed.includes("*/")) {
+        const content = trimmed.replace(/\s*\*+\/$/, "").trim();
+        currentBlock += content + " ";
+        inBlock = false;
+        annotations.push(...parseTags(currentBlock));
+        currentBlock = null;
+      } else {
+        const content = trimmed.replace(/^\s*\*\s*/, "").trim();
+        currentBlock += content + " ";
+      }
+      continue;
+    }
+
+    // Detecta línea de comentario con @
+    if (trimmed.startsWith("//") && trimmed.includes("@")) {
+      const tagLine = trimmed.replace(/^\/\/\s*/, "");
+      annotations.push(...parseTags(tagLine));
+    }
+  }
+
+  // Si quedó un bloque abierto sin cerrar, lo forzamos
+  if (inBlock && currentBlock) {
+    annotations.push(...parseTags(currentBlock));
+    errors.push("Comentario multinea sin cerrar. Las anotaciones se procesaron igual.");
+  }
+
+  // Extraer @use primero (determina qué tags son válidos)
+  const useTag = annotations.find((a) => a.name === "use");
+
+  // Edge case: @use(*) → todos los tags son válidos
+  let validTags = [];
+  if (useTag) {
+    const starArg = useTag.args.find((a) => a.value === "*");
+    if (starArg) {
+      validTags = []; // empty = todos permitidos
+    } else {
+      validTags = useTag.args.map((a) => a.value);
+    }
+  }
+
+  // Edge case: @use presente pero sin tags reales
+  if (useTag && useTag.args.length === 0) {
+    errors.push("@use() está vacío — no se importaron tags");
+  }
+
+  // Edge case: @use sin anotaciones de tags abajo
+  if (useTag && annotations.filter((a) => a.name !== "use").length === 0) {
+    errors.push("@use presente pero no hay anotaciones de tags en el archivo");
+  }
+
+  return { annotations, validTags, parseErrors: errors };
+}
+
+function parseTags(text) {
+  const tags = [];
+
+  if (!text || text.trim().length === 0) return tags;
+
+  // Parseador manual con conteo de profundidad de paréntesis
+  let i = 0;
+  while (i < text.length) {
+    // Buscar @ seguido de nombre de tag
+    const atIndex = text.indexOf("@", i);
+    if (atIndex === -1) break;
+
+    // Extraer nombre del tag (letras, números, guiones)
+    const nameMatch = text.slice(atIndex + 1).match(/^\w+/);
+    if (!nameMatch) { i = atIndex + 1; continue; }
+
+    const name = nameMatch[0];
+    let argsRaw = "";
+    let parenDepth = 0;
+    let pos = atIndex + 1 + name.length;
+
+    // Si hay paréntesis, extraemos con depth tracking
+    if (pos < text.length && text[pos] === "(") {
+      parenDepth = 1;
+      pos++;
+      const start = pos;
+      while (pos < text.length && parenDepth > 0) {
+        if (text[pos] === "(") parenDepth++;
+        else if (text[pos] === ")") parenDepth--;
+        pos++;
+      }
+      argsRaw = text.slice(start, pos - 1).trim();
+    }
+
+    tags.push({ name, args: parseArgs(argsRaw), raw: `@${name}(${argsRaw})` });
+    i = pos;
+  }
+
+  return tags;
+}
+
+function parseArgs(raw) {
+  const args = [];
+
+  if (!raw || raw.trim().length === 0) return args;
+
+  const trimmed = raw.trim();
+  const lenient = trimmed.replace(/\)$/, "");
+
+  // Intenta parsear como JSON object primero: { key: value, ... }
+  if (trimmed.startsWith("{")) {
+    try {
+      const obj = JSON.parse(trimmed);
+      for (const [key, value] of Object.entries(obj)) {
+        args.push({ key, value: String(value), type: "kv" });
+      }
+      return args;
+    } catch {
+      // Fallback: parsear como TypeScript object { key: type, key?: type }
+      const tsProps = parseTsObject(trimmed);
+      if (tsProps.length > 0) {
+        args.push(...tsProps);
+        return args;
+      }
+      // Edge case: JSON inválido → error reportado en validación
+      args.push({ key: null, value: trimmed, type: "invalid-json" });
+      return args;
+    }
+  }
+
+  // Detectar mezcla de subtags, flags y key:values
+  // Dividir por coma respetando corchetes
+  const parts = splitRespectingBrackets(lenient);
+
+  for (const part of parts) {
+    const p = part.trim();
+    if (!p) continue;
+
+    // Subtag: @algo: [lista]
+    const subMatch = p.match(/^@(\w+)\s*:\s*\[([^\]]*)\]/);
+    if (subMatch) {
+      args.push({
+        key: subMatch[1],
+        value: subMatch[2].split(",").map((s) => s.trim().replace(/["']/g, "")),
+        type: "subtag",
+      });
+      continue;
+    }
+
+    // Flag: @algo
+    const flagMatch = p.match(/^@(\w+)/);
+    if (flagMatch) {
+      args.push({ key: flagMatch[1], value: true, type: "flag" });
+      continue;
+    }
+
+    // Key: value
+    const kvMatch = p.match(/^(\w+)\s*:\s*(.+)/);
+    if (kvMatch) {
+      args.push({ key: kvMatch[1].trim(), value: kvMatch[2].trim().replace(/["']/g, ""), type: "kv" });
+      continue;
+    }
+
+    // Valor plano
+    args.push({ key: null, value: p.replace(/["']/g, ""), type: "plain" });
+  }
+
+  return args;
+}
+
+function parseTsObject(raw) {
+  // Parsear { key: type, key?: type, "key": "type" }
+  const inner = raw.trim().replace(/^{/, "").replace(/}$/, "").trim();
+  if (!inner) return [];
+  const parts = splitRespectingBrackets(inner);
+  const result = [];
+  for (const part of parts) {
+    const p = part.trim();
+    if (!p) continue;
+    // key: type  o  key?: type  o  "key": "type"
+    const m = p.match(/^"([^"]+)"\s*:\s*(.+)/) || p.match(/^(\w+\??)\s*:\s*(.+)/);
+    if (m) {
+      const key = m[1].replace(/\?$/, "?");
+      let value = m[2].trim().replace(/["']/g, "");
+      // Quitar default values: = "Default" → ignorar
+      value = value.replace(/\s*=\s*.+$/, "").trim();
+      result.push({ key, value, type: "kv" });
+    }
+  }
+  return result;
+}
+
+function splitRespectingBrackets(str) {
+  const result = [];
+  let current = "";
+  let depth = 0;
+
+  for (const ch of str) {
+    if (ch === "[" || ch === "{" || ch === "(") {
+      depth++;
+      current += ch;
+    } else if (ch === "]" || ch === "}" || ch === ")") {
+      depth--;
+      current += ch;
+    } else if (ch === "," && depth === 0) {
+      result.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) result.push(current.trim());
+  return result;
+}
+
+// ─── Validador ──────────────────────────────────────────────────────────────
+
+export function validateAnnotations(annotations, validTags, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const tags = annotations.filter((a) => a.name !== "use");
+
+  // Validar tags contra @use
+  const useAll = validTags.length === 0 && annotations.some(
+    (a) => a.name === "use" && a.args.some((x) => x.value === "*")
+  );
+
+  if (validTags.length > 0 && !useAll) {
+    for (const tag of tags) {
+      if (!validTags.includes(tag.name)) {
+        errors.push(`Tag @${tag.name} no está importado. Agrega @use(${tag.name})`);
+      }
+    }
+  }
+
+  // Validar @kind
+  const kindTag = tags.find((t) => t.name === "kind");
+  const validKinds = [
+    "hook", "component", "page", "service", "store",
+    "util", "type", "layout", "feature",
+  ];
+
+  if (kindTag) {
+    const kindValue = kindTag.args[0]?.value;
+
+    // Edge case: @kind sin valor
+    if (!kindValue || kindValue.trim() === "") {
+      errors.push("@kind() necesita un valor. Válidos: " + validKinds.join(", "));
+    } else if (!validKinds.includes(kindValue)) {
+      errors.push(
+        `@kind("${kindValue}") inválido. Valores válidos: ${validKinds.join(", ")}`
+      );
+    }
+
+    if (kindValue && validKinds.includes(kindValue)) {
+      const hasContract = tags.some((t) => t.name === "contract");
+      const hasProps = tags.some((t) => t.name === "props");
+      const hasLimit = tags.some((t) => t.name === "limit");
+      const hasCompose = tags.some((t) => t.name === "compose");
+
+      if (kindValue === "hook" && !hasContract) {
+        warnings.push("@kind(hook) debería tener @contract");
+      }
+      if (kindValue === "component" && hasContract) {
+        errors.push("@kind(component) no puede tener @contract. Usa @props en su lugar.");
+      }
+      if (kindValue === "component" && !hasProps) {
+        warnings.push("@kind(component) debería tener @props");
+      }
+      if (kindValue === "page" && !hasCompose) {
+        warnings.push("@kind(page) debería tener @compose (debe componer subcomponentes)");
+      }
+      if (kindValue === "service" && !hasContract) {
+        errors.push("@kind(service) requiere @contract");
+      }
+      if (kindValue === "hook" && hasProps) {
+        errors.push("@kind(hook) no puede tener @props");
+      }
+      if (kindValue === "type" && hasLimit) {
+        warnings.push("@kind(type) no necesita @limit");
+      }
+      if (kindValue === "store") {
+        const hasDeps = tags.some((t) => t.name === "deps");
+        if (!hasDeps) {
+          warnings.push("@kind(store) debería tener @deps (zustand, context, etc.)");
+        }
+      }
+
+      // Límites por defecto según kind
+      const limitTag = tags.find((t) => t.name === "limit");
+      if (limitTag) {
+        const linesArg = limitTag.args.find((a) => a.key === "lines");
+        if (linesArg) {
+          const maxLines = {
+            hook: 80, component: 120, page: 200,
+            service: 150, store: 100, layout: 150,
+          };
+          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})`
+            );
+          }
+          // Edge case: límite 0 o negativo
+          if (!isNaN(numVal) && numVal <= 0) {
+            errors.push(`@limit(lines: ${numVal}) debe ser mayor a 0`);
+          }
+        }
+      }
+    }
+  }
+
+  // Validar @contract — edge cases
+  const contractTag = tags.find((t) => t.name === "contract");
+  if (contractTag) {
+    const args = contractTag.args;
+    const hasInput = args.some((a) => a.key === "in" || a.type === "plain");
+    const hasOutput = args.find((a) => a.key === "out" || a.value === "->");
+    const contractText = contractTag.raw;
+
+    // Edge case: contrato vacío
+    if (args.length === 0 && contractTag.raw === "@contract()") {
+      errors.push("@contract() está vacío. Formato: @contract(in: tipo -> out: tipo @error: tipo)");
+    }
+
+    // Edge case: sin input claro
+    if (args.length > 0 && !hasInput && !contractText.includes("in:")) {
+      // Puede ser formato @contract(in: -> out:) sin inputs
+      if (contractText.includes("->")) {
+        // tiene flecha pero sin "in:" → intentamos extraer
+        const parts = contractText.split("->");
+        const inputPart = parts[0].replace("@contract(", "").replace("@contract", "").trim();
+        if (!inputPart || inputPart === "in: " || inputPart === "in:") {
+          errors.push("@contract: falta definir tipos de entrada (in:)");
+        }
+      }
+    }
+
+    // Edge case: @contract(in: any -> out: any)
+    if (contractTag.raw.includes("any")) {
+      warnings.push("@contract usa 'any' — especifica tipos concretos");
+    }
+  }
+
+  // Validar @props — edge case JSON inválido
+  const propsTag = tags.find((t) => t.name === "props");
+  if (propsTag) {
+    const hasInvalidJson = propsTag.args.some((a) => a.type === "invalid-json");
+    if (hasInvalidJson) {
+      errors.push(`@props(${propsTag.args[0]?.value}) no es un JSON válido. Formato: @props({ key: type })`);
+    }
+  }
+
+  // Validar @platform — edge case web + capacitor
+  const platformTag = tags.find((t) => t.name === "platform");
+  const depsTag = tags.find((t) => t.name === "deps");
+  if (platformTag && depsTag) {
+    const platforms = platformTag.args.map((a) => a.value);
+    const deps = depsTag.args;
+
+    if (platforms.includes("web")) {
+      const hasCapacitor = deps.some(
+        (d) => d.value && (String(d.value).includes("@capacitor"))
+      );
+      if (hasCapacitor) {
+        errors.push("@platform(web) no es compatible con @capacitor/*");
+      }
+      const hasTauri = deps.some(
+        (d) => d.value && String(d.value).includes("@tauri-apps")
+      );
+      if (hasTauri) {
+        errors.push("@platform(web) no es compatible con @tauri-apps/*");
+      }
+    }
+
+    if (platforms.includes("mobile")) {
+      const hasTauri = deps.some(
+        (d) => d.value && String(d.value).includes("@tauri-apps")
+      );
+      if (hasTauri) {
+        errors.push("@platform(mobile) no es compatible con @tauri-apps/*");
+      }
+    }
+    if (platforms.includes("desktop")) {
+      const hasCapacitor = deps.some(
+        (d) => d.value && String(d.value).includes("@capacitor")
+      );
+      if (hasCapacitor) {
+        errors.push("@platform(desktop) no es compatible con @capacitor/*");
+      }
+    }
+  }
+
+  // Validar @limit — edge cases de valores
+  const limitTag = tags.find((t) => t.name === "limit");
+  if (limitTag) {
+    for (const arg of limitTag.args) {
+      if (arg.type === "kv" && arg.value !== undefined) {
+        const num = parseInt(arg.value);
+        if (isNaN(num) || (arg.value.includes(".") && isNaN(parseFloat(arg.value)))) {
+          errors.push(`@limit(${arg.key}: "${arg.value}") esperaba un número, recibió texto`);
+        }
+      }
+    }
+    // Edge case: @limit() vacío
+    if (limitTag.args.length === 0) {
+      errors.push("@limit() está vacío. Especifica al menos un límite: @limit(lines: 120)");
+    }
+  }
+
+  // Validar @forbidden
+  const forbiddenTag = tags.find((t) => t.name === "forbidden");
+  if (forbiddenTag) {
+    if (forbiddenTag.args.length === 0) {
+      warnings.push("@forbidden() está vacío — no prohíbe nada");
+    }
+  }
+
+  // Validar @scope breaking
+  const scopeTag = tags.find((t) => t.name === "scope");
+  if (scopeTag) {
+    const breaking = scopeTag.args.find((a) => a.key === "breaking");
+    if (breaking && breaking.value === "true") {
+      warnings.push("@scope(breaking: true) — el commit debe indicar breaking change (!)");
+    }
+  }
+
+  // Validar @test
+  const testTag = tags.find((t) => t.name === "test");
+  if (testTag) {
+    const coverage = testTag.args.find((a) => a.key === "coverage");
+    if (coverage) {
+      const val = parseInt(coverage.value);
+      if (!isNaN(val) && val > 100) {
+        errors.push(`@test(@coverage: ${val}) no puede exceder 100`);
+      }
+    }
+  }
+
+  // Validar @state error → debe tener @contract (solo en kinds que requieren contract)
+  const stateTag = tags.find((t) => t.name === "state");
+  if (stateTag) {
+    const hasError = stateTag.args.some((a) => a.value === "error");
+    const hasContract = tags.some((t) => t.name === "contract");
+    const kindValue = kindTag?.args[0]?.value;
+    const contractKinds = ["hook", "service"];
+    if (hasError && !hasContract && contractKinds.includes(kindValue)) {
+      warnings.push("@state(error) presente pero no hay @contract — define el tipo de error");
+    }
+  }
+
+  return { errors, warnings };
+}
+
+// ─── API pública ────────────────────────────────────────────────────────────
+
+export function lintFile(code, strict = false) {
+  const { annotations, validTags, parseErrors } = parseAnnotations(code);
+
+  if (annotations.length === 0) {
+    return { annotations: [], errors: parseErrors, warnings: [] };
+  }
+
+  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: [] };
+  }
+
+  return {
+    annotations,
+    errors: allErrors,
+    warnings: allWarnings,
+  };
+}
+
+export { parseArgs };