@ronaldjdevfs/forge 1.0.2 → 1.1.0

package/skills/forge/scripts/forge-api.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+
+/**
+ * forge-api.mjs — API Contract Validation (D3).
+ *
+ * Detecta OpenAPI specs y GraphQL schemas, y verifica:
+ *   - Endpoints documentados pero no implementados
+ *   - Endpoints implementados pero no documentados
+ *   - DTOs/controllers consistentes con la spec
+ *
+ * Uso:
+ *   node forge-api.mjs                    → validación completa
+ *   node forge-api.mjs --json             → salida JSON
+ *   node forge-api.mjs --openapi          → solo OpenAPI
+ *   node forge-api.mjs --graphql          → solo GraphQL
+ *   node forge-api.mjs --find-specs       → solo buscar specs
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import { join, relative, basename, extname, dirname } from "path";
+
+const ROOT = process.cwd();
+const SRC = join(ROOT, "src");
+
+const SEVERITY = { ERROR: "ERROR", WARNING: "WARNING", INFO: "INFO", SUGGESTION: "SUGGESTION" };
+
+function read(path) {
+  try { return readFileSync(path, "utf-8"); } catch { return null; }
+}
+
+function isDir(path) {
+  try { return statSync(path).isDirectory(); } catch { return false; }
+}
+
+function listDir(path, recursive = false) {
+  try {
+    const entries = readdirSync(path, { withFileTypes: true });
+    const files = [];
+    for (const e of entries) {
+      const full = join(path, e.name);
+      if (e.isDirectory()) {
+        if (recursive) files.push(...listDir(full, true));
+      } else {
+        files.push(full);
+      }
+    }
+    return files;
+  } catch { return []; }
+}
+
+// ── Spec detection ──
+
+function findOpenAPISpecs() {
+  const specs = [];
+  const candidates = [
+    join(ROOT, "openapi.yaml"), join(ROOT, "openapi.yml"), join(ROOT, "openapi.json"),
+    join(ROOT, "spec.yaml"), join(ROOT, "spec.yml"), join(ROOT, "spec.json"),
+    join(ROOT, "swagger.yaml"), join(ROOT, "swagger.yml"), join(ROOT, "swagger.json"),
+    join(SRC, "openapi.yaml"), join(SRC, "openapi.yml"), join(SRC, "openapi.json"),
+  ];
+
+  for (const c of candidates) {
+    if (existsSync(c)) specs.push(c);
+  }
+
+  // Search recursively for openapi.* or swagger.*
+  if (isDir(SRC)) {
+    const all = listDir(SRC, true);
+    for (const f of all) {
+      const name = basename(f);
+      if (/^openapi\.(yaml|yml|json)$/.test(name) || /^swagger\.(yaml|yml|json)$/.test(name)) {
+        if (!specs.includes(f)) specs.push(f);
+      }
+    }
+  }
+
+  return specs;
+}
+
+function findGraphQLSchemas() {
+  const schemas = [];
+  const candidates = [
+    join(ROOT, "schema.graphql"), join(ROOT, "schema.gql"),
+    join(ROOT, "graphql"), join(ROOT, "graphql"),
+    join(SRC, "schema.graphql"), join(SRC, "schema.gql"),
+  ];
+
+  for (const c of candidates) {
+    if (existsSync(c)) {
+      if (isDir(c)) {
+        schemas.push(...listDir(c, true).filter(f => /\.(graphql|gql)$/.test(f)));
+      } else {
+        schemas.push(c);
+      }
+    }
+  }
+
+  if (isDir(SRC)) {
+    const all = listDir(SRC, true);
+    for (const f of all) {
+      if (/\.(graphql|gql)$/.test(f) && !schemas.includes(f)) schemas.push(f);
+    }
+  }
+
+  return schemas;
+}
+
+// ── Route extraction from code ──
+
+function extractControllerRoutes(files) {
+  const routes = [];
+  const patterns = [
+    /@(Get|Post|Put|Patch|Delete|Head|Options)\s*\(\s*['"]([^'"]*)['"]\s*\)/g,        // NestJS
+    /(?:router|app)\.(get|post|put|patch|delete|head|options)\s*\(\s*['"]([^'"]*)['"]/gi, // Express/Fastify
+    /\.(get|post|put|patch|delete|head|options)\s*\(\s*['"]([^'"]*)['"]\s*,/gi,
+    /['"]method['"]\s*:\s*['"](GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)['"].*['"]path['"]\s*:\s*['"]([^'"]+)['"]/gis, // config-based
+  ];
+
+  for (const f of files) {
+    const content = read(f);
+    if (!content) continue;
+    for (const re of patterns) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(content)) !== null) {
+        const method = m[1].toUpperCase();
+        let path = m[2] || "/";
+        if (path && !path.startsWith("/")) path = "/" + path;
+        routes.push({ method, path: path.replace(/\/\//g, "/"), file: relative(ROOT, f) });
+      }
+    }
+  }
+  return routes;
+}
+
+// ── OpenAPI route extraction ──
+
+function parseOpenAPIPaths(content) {
+  const paths = [];
+  try {
+    const spec = JSON.parse(content);
+    const p = spec.paths || {};
+    for (const [path, methods] of Object.entries(p)) {
+      for (const [method, def] of Object.entries(methods)) {
+        if (["get", "post", "put", "patch", "delete", "head", "options"].includes(method)) {
+          paths.push({ method: method.toUpperCase(), path, summary: def.summary || def.operationId || "" });
+        }
+      }
+    }
+  } catch {
+    // Try YAML-like parsing (simple key extraction)
+    const methodRe = /^\s{4}(get|post|put|patch|delete|head|options):/gmi;
+    const pathRe = /^\s{2}\/([^:]+):/gm;
+    let m;
+    let lastPath = "";
+    while ((m = pathRe.exec(content)) !== null) {
+      lastPath = "/" + m[1];
+    }
+    while ((m = methodRe.exec(content)) !== null) {
+      if (lastPath) paths.push({ method: m[1].toUpperCase(), path: lastPath, summary: "" });
+    }
+  }
+  return paths;
+}
+
+// ── GraphQL extraction ──
+
+function parseGraphQLSchema(content) {
+  const types = [];
+  const queryRe = /type\s+Query\s*\{([^}]+)\}/g;
+  const mutationRe = /type\s+Mutation\s*\{([^}]+)\}/g;
+
+  let m;
+  while ((m = queryRe.exec(content)) !== null) {
+    for (const line of m[1].split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#") && !trimmed.startsWith("//")) {
+        const name = trimmed.split(/[(:]/)[0].trim();
+        if (name) types.push({ type: "Query", name });
+      }
+    }
+  }
+  while ((m = mutationRe.exec(content)) !== null) {
+    for (const line of m[1].split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#") && !trimmed.startsWith("//")) {
+        const name = trimmed.split(/[(:]/)[0].trim();
+        if (name) types.push({ type: "Mutation", name });
+      }
+    }
+  }
+  return types;
+}
+
+function extractGraphQLResolvers(files) {
+  const resolvers = [];
+  const patterns = [
+    /['"]?(Query|Mutation)['"]?\s*:\s*\{([^}]+)\}/gs,
+    /@Resolver\s*\(/g,
+    /@(Query|Mutation)\s*\(\s*['"]([^'"]*)['"]\s*\)/g,
+  ];
+
+  for (const f of files) {
+    const content = read(f);
+    if (!content) continue;
+
+    // Resolver map pattern
+    let m;
+    while ((m = patterns[0].exec(content)) !== null) {
+      const type = m[1];
+      const body = m[2];
+      for (const line of body.split(",")) {
+        const name = line.trim().split(":")[0]?.trim().replace(/['"]/g, "");
+        if (name && !name.includes(" ")) resolvers.push({ type, name, file: relative(ROOT, f) });
+      }
+    }
+
+    // Decorator pattern
+    patterns[2].lastIndex = 0;
+    while ((m = patterns[2].exec(content)) !== null) {
+      resolvers.push({ type: m[1], name: m[2], file: relative(ROOT, f) });
+    }
+  }
+
+  return resolvers;
+}
+
+// ── Main validation ──
+
+export function validateAPI() {
+  const results = { specs: [], openapi: { documented: [], implemented: [], onlyDoc: [], onlyCode: [] }, graphql: { documented: [], implemented: [], onlyDoc: [], onlyCode: [] }, errors: [] };
+
+  // Find specs
+  const openapiSpecs = findOpenAPISpecs();
+  const graphqlSchemas = findGraphQLSchemas();
+  results.specs = { openapi: openapiSpecs, graphql: graphqlSchemas };
+
+  // Guard clause: sin specs, no hay nada que validar
+  if (openapiSpecs.length === 0 && graphqlSchemas.length === 0) {
+    return results;
+  }
+
+  // Find controllers and resolvers (costoso, solo si hay specs)
+  const srcFiles = isDir(SRC) ? listDir(SRC, true).filter(f => /\.(ts|js)$/.test(f)) : [];
+  const controllerRoutes = extractControllerRoutes(srcFiles);
+  const graphqlResolvers = extractGraphQLResolvers(srcFiles);
+
+  // Validate OpenAPI
+  for (const specPath of openapiSpecs) {
+    const content = read(specPath);
+    if (!content) continue;
+    const docPaths = parseOpenAPIPaths(content);
+    results.openapi.documented = docPaths;
+
+    for (const dp of docPaths) {
+      const found = controllerRoutes.some(cr => cr.method === dp.method && (cr.path === dp.path || cr.path.endsWith(dp.path) || dp.path.endsWith(cr.path)));
+      if (!found) {
+        results.openapi.onlyDoc.push({ method: dp.method, path: dp.path, spec: relative(ROOT, specPath) });
+      }
+    }
+
+    for (const cr of controllerRoutes) {
+      const found = docPaths.some(dp => dp.method === cr.method && (dp.path === cr.path || dp.path.endsWith(cr.path) || cr.path.endsWith(dp.path)));
+      if (!found) {
+        results.openapi.onlyCode.push(cr);
+      }
+    }
+  }
+
+  // Validate GraphQL
+  for (const schemaPath of graphqlSchemas) {
+    const content = read(schemaPath);
+    if (!content) continue;
+    const types = parseGraphQLSchema(content);
+    results.graphql.documented = types;
+
+    for (const t of types) {
+      const found = graphqlResolvers.some(r => r.type === t.type && r.name === t.name);
+      if (!found) {
+        results.graphql.onlyDoc.push(t);
+      }
+    }
+
+    const seen = new Set();
+    for (const r of graphqlResolvers) {
+      const key = `${r.type}:${r.name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const found = types.some(t => t.type === r.type && t.name === r.name);
+      if (!found) {
+        results.graphql.onlyCode.push(r);
+      }
+    }
+  }
+
+  results.errors = [
+    ...results.openapi.onlyDoc.map(d => `[DOCUMENTADO] ${d.method} ${d.path} — sin implementación`),
+    ...results.openapi.onlyCode.map(c => `[NO DOC] ${c.method} ${c.path} (${c.file})`),
+    ...results.graphql.onlyDoc.map(d => `[DOCUMENTADO] ${d.type}.${d.name} — sin resolver`),
+    ...results.graphql.onlyCode.map(r => `[NO DOC] ${r.type}.${r.name} (${r.file})`),
+  ];
+
+  return results;
+}
+
+function printReport(results) {
+  console.log("\n═══ API Contract Validation ═══\n");
+
+  console.log("── Specs encontrados ──");
+  if (results.specs.openapi.length > 0) {
+    for (const s of results.specs.openapi) console.log(`  OpenAPI: ${relative(ROOT, s)}`);
+  } else {
+    console.log("  OpenAPI: (ninguno)");
+  }
+  if (results.specs.graphql.length > 0) {
+    for (const s of results.specs.graphql) console.log(`  GraphQL: ${relative(ROOT, s)}`);
+  } else {
+    console.log("  GraphQL: (ninguno)");
+  }
+
+  if (results.errors.length === 0) {
+    console.log(`\n${"✓ Sin discrepancias — API contracts OK"}`);
+    return;
+  }
+
+  console.log(`\n── Discrepancias (${results.errors.length}) ──\n`);
+  for (const err of results.errors) {
+    const type = err.startsWith("[DOCUMENTADO]") ? "WARNING" : err.startsWith("[NO DOC]") ? "ERROR" : "INFO";
+    const icon = type === "ERROR" ? "✘" : type === "WARNING" ? "⚠" : "ℹ";
+    console.log(`  ${icon} [${type}] ${err}`);
+  }
+
+  console.log(`\nTotal: ${results.errors.length} discrepancia(s)`);
+  if (results.openapi.onlyDoc.length > 0)
+    console.log(`  ${results.openapi.onlyDoc.length} endpoint(s) documentados sin implementar`);
+  if (results.openapi.onlyCode.length > 0)
+    console.log(`  ${results.openapi.onlyCode.length} endpoint(s) implementados sin documentar`);
+  if (results.graphql.onlyDoc.length > 0)
+    console.log(`  ${results.graphql.onlyDoc.length} resolver(s) documentados sin implementar`);
+  if (results.graphql.onlyCode.length > 0)
+    console.log(`  ${results.graphql.onlyCode.length} resolver(s) implementados sin documentar`);
+}
+
+async function main() {
+  const isJson = process.argv.includes("--json");
+  const onlyOpenAPI = process.argv.includes("--openapi");
+  const onlyGraphQL = process.argv.includes("--graphql");
+  const findSpecs = process.argv.includes("--find-specs");
+
+  if (findSpecs) {
+    const openapi = findOpenAPISpecs();
+    const graphql = findGraphQLSchemas();
+    if (isJson) {
+      console.log(JSON.stringify({ openapi: openapi.map(f => relative(ROOT, f)), graphql: graphql.map(f => relative(ROOT, f)) }, null, 2));
+    } else {
+      console.log("OpenAPI specs:"); openapi.forEach(f => console.log(`  ${relative(ROOT, f)}`));
+      console.log("GraphQL schemas:"); graphql.forEach(f => console.log(`  ${relative(ROOT, f)}`));
+    }
+    process.exit(0);
+  }
+
+  const results = validateAPI();
+  if (isJson) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    printReport(results);
+  }
+  process.exit(results.errors.length > 0 ? 1 : 0);
+}
+
+if (process.argv[1] && (process.argv[1].endsWith("forge-api.mjs") || process.argv[1].endsWith("forge-api.js"))) {
+  main().catch(console.error);
+}

package/skills/forge/scripts/forge-config.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+
+const ROOT = process.cwd();
+const CONFIG_DIR = join(ROOT, ".forge");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const STATE_PATH = join(CONFIG_DIR, "state.json");
+const HISTORY_DIR = join(CONFIG_DIR, "history");
+
+const DEFAULT_CONFIG = {
+  profile: null,
+  framework: null,
+  database: null,
+  orm: null,
+  diStrategy: null,
+  runtime: null,
+  ignorePaths: ["src/generated", "src/__tests__/fixtures", "src/**/*.spec.ts", "src/**/*.test.ts"],
+  lastContextUpdate: null,
+};
+
+const DEFAULT_STATE = {
+  lastAudit: null,
+  lastScore: null,
+  lastGrade: null,
+  violationCount: 0,
+  totalFeatures: 0,
+  migratedFeatures: 0,
+  legacyFeatures: 0,
+  platformExists: false,
+  health: "unknown",
+};
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, data) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function loadConfig() {
+  const config = readJson(CONFIG_PATH);
+  if (!config) {
+    return { ...DEFAULT_CONFIG };
+  }
+  return { ...DEFAULT_CONFIG, ...config };
+}
+
+export function saveConfig(config) {
+  return writeJson(CONFIG_PATH, config);
+}
+
+export function loadState() {
+  const state = readJson(STATE_PATH);
+  if (!state) {
+    return { ...DEFAULT_STATE };
+  }
+  return { ...DEFAULT_STATE, ...state };
+}
+
+export function saveState(state) {
+  return writeJson(STATE_PATH, state);
+}
+
+export function updateStateFromAudit(auditResult) {
+  const state = loadState();
+  state.lastAudit = new Date().toISOString();
+  state.lastScore = auditResult.total || 0;
+  state.lastGrade = auditResult.grade || "F";
+  state.violationCount = (auditResult.violations || []).length;
+  state.health = auditResult.health || "unknown";
+  if (auditResult.context) {
+    state.totalFeatures = auditResult.context.features?.total || 0;
+    state.migratedFeatures = auditResult.context.features?.migrated?.length || 0;
+    state.legacyFeatures = auditResult.context.features?.legacy?.length || 0;
+  }
+  return saveState(state);
+}
+
+export function saveHistory(snapshot) {
+  mkdirSync(HISTORY_DIR, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const path = join(HISTORY_DIR, `audit-${ts}.json`);
+  return writeJson(path, { ...snapshot, timestamp: new Date().toISOString() });
+}
+
+export function loadHistory(limit = 20) {
+  mkdirSync(HISTORY_DIR, { recursive: true });
+  try {
+    const files = readdirSync(HISTORY_DIR)
+      .filter(f => f.startsWith("audit-") && f.endsWith(".json"))
+      .sort()
+      .slice(-limit);
+    return files.map(f => readJson(join(HISTORY_DIR, f))).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function displayTrend(entries) {
+  if (entries.length === 0) return console.log("No hay historial de auditorías.");
+  console.log("\n── Forge Trend ──\n");
+  console.log(`${"Fecha".padEnd(22)} ${"Score".padEnd(6)} ${"Grade".padEnd(6)} ${"Violaciones".padEnd(12)} ${"Features"}`);
+  console.log("─".repeat(60));
+  for (const e of entries) {
+    const date = (e.timestamp || "").slice(0, 19).replace("T", " ");
+    const score = e.score !== undefined ? `${e.score}/110` : "—";
+    const grade = e.grade || "—";
+    const violations = e.violationCount !== undefined ? String(e.violationCount) : "—";
+    const features = e.totalFeatures !== undefined ? `${e.migratedFeatures || 0}/${e.totalFeatures}` : "—";
+    console.log(`${date.padEnd(22)} ${score.padEnd(6)} ${grade.padEnd(6)} ${violations.padEnd(12)} ${features}`);
+  }
+  if (entries.length >= 2) {
+    const first = entries[0];
+    const last = entries[entries.length - 1];
+    const delta = (last.score || 0) - (first.score || 0);
+    console.log("─".repeat(60));
+    console.log(`Δ total: ${delta > 0 ? "+" : ""}${delta} puntos (${delta > 0 ? "mejora" : delta < 0 ? "empeora" : "estable"})`);
+  }
+}
+
+export function updateConfigFromContext(ctx) {
+  const config = loadConfig();
+  let changed = false;
+
+  if (ctx.framework && ctx.framework !== "unknown" && ctx.framework !== config.framework) {
+    config.framework = ctx.framework;
+    changed = true;
+  }
+  if (ctx.database && ctx.database !== "unknown" && ctx.database !== config.database) {
+    config.database = ctx.database;
+    changed = true;
+  }
+  if (ctx.orm && ctx.orm !== "none" && ctx.orm !== config.orm) {
+    config.orm = ctx.orm;
+    changed = true;
+  }
+  if (ctx.diStrategy && ctx.diStrategy !== "manual" && ctx.diStrategy !== config.diStrategy) {
+    config.diStrategy = ctx.diStrategy;
+    changed = true;
+  }
+  if (ctx.runtime && ctx.runtime !== config.runtime) {
+    config.runtime = ctx.runtime;
+    changed = true;
+  }
+  if (ctx.profile && ctx.profile !== config.profile) {
+    config.profile = ctx.profile;
+    changed = true;
+  }
+
+  if (changed) {
+    config.lastContextUpdate = new Date().toISOString();
+    return saveConfig(config);
+  }
+  return true;
+}
+
+export function configNeedsRefresh(config) {
+  if (!config.lastContextUpdate) return true;
+  const daysSinceUpdate = (Date.now() - new Date(config.lastContextUpdate).getTime()) / 86400000;
+  return daysSinceUpdate > 7;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const isJson = args.includes("--json");
+  const action = args.find(a => a === "--init" || a === "--update" || a === "--show" || a === "--clear-state" || a === "--history" || a === "--trend");
+
+  if (action === "--init") {
+    if (existsSync(CONFIG_PATH)) {
+      console.log("forge-config: config.json ya existe en .forge/");
+      process.exit(0);
+    }
+    const ok = writeJson(CONFIG_PATH, DEFAULT_CONFIG);
+    writeJson(STATE_PATH, DEFAULT_STATE);
+    console.log(`forge-config: config.json ${ok ? "creado" : "ERROR"} en .forge/`);
+    process.exit(ok ? 0 : 1);
+  }
+
+  if (action === "--show") {
+    const config = loadConfig();
+    const state = loadState();
+    if (isJson) {
+      console.log(JSON.stringify({ config, state }, null, 2));
+    } else {
+      console.log("── Forge Config ──");
+      for (const [k, v] of Object.entries(config)) {
+        console.log(`  ${k}: ${v ?? "(sin detectar)"}`);
+      }
+      console.log("\n── Forge State ──");
+      for (const [k, v] of Object.entries(state)) {
+        console.log(`  ${k}: ${v ?? "(sin datos)"}`);
+      }
+    }
+    process.exit(0);
+  }
+
+  if (action === "--clear-state") {
+    writeJson(STATE_PATH, DEFAULT_STATE);
+    console.log("forge-config: state.json limpiado");
+    process.exit(0);
+  }
+
+  if (action === "--history") {
+    const entries = loadHistory(isJson ? 999 : 20);
+    if (isJson) {
+      console.log(JSON.stringify(entries, null, 2));
+    } else {
+      displayTrend(entries);
+    }
+    process.exit(0);
+  }
+
+  if (action === "--trend") {
+    const entries = loadHistory(20);
+    if (isJson) {
+      console.log(JSON.stringify(entries.map(e => ({ timestamp: e.timestamp, score: e.score, grade: e.grade })), null, 2));
+    } else {
+      displayTrend(entries);
+    }
+    process.exit(0);
+  }
+
+  if (action === "--update") {
+    const { buildContext } = await import("./context.mjs");
+    const { detectProfile } = await import("./profile.mjs");
+    const ctx = await buildContext();
+    const profile = detectProfile(ctx);
+    ctx.profile = profile;
+    updateConfigFromContext(ctx);
+    console.log("forge-config: config.json actualizado desde context");
+    process.exit(0);
+  }
+
+  // Default: print status
+  const config = loadConfig();
+  const state = loadState();
+  const needsRefresh = configNeedsRefresh(config);
+  const summary = {
+    configExists: existsSync(CONFIG_PATH),
+    stateExists: existsSync(STATE_PATH),
+    needsRefresh,
+    config,
+    state,
+  };
+  if (isJson) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(`Config: ${summary.configExists ? "✓" : "✗"} | State: ${summary.stateExists ? "✓" : "✗"} | Refresh needed: ${needsRefresh}`);
+  }
+  process.exit(0);
+}
+
+if (process.argv[1] && (process.argv[1].endsWith("forge-config.mjs") || process.argv[1].endsWith("forge-config.js"))) {
+  main().catch(console.error);
+}