@vibecheckai/cli 3.0.4 → 3.0.7

package/bin/runners/lib/extractors/fastify-route-dump.js

@@ -0,0 +1,573 @@
+/**
+ * Fastify Runtime Route Dump v2
+ * 
+ * Spawns Fastify app with VIBECHECK_ROUTE_DUMP=1 to extract
+ * runtime routes, which are more accurate than static extraction.
+ */
+
+"use strict";
+
+const { spawn } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const DUMP_ENV_VAR = "VIBECHECK_ROUTE_DUMP";
+const DUMP_TIMEOUT_MS = 30000; // 30s max for app startup
+const OUTPUT_DIR = ".vibecheck/runtime";
+const ROUTES_TXT = "fastify_routes.txt";
+const ROUTES_JSON = "fastify_routes.json";
+
+// Fastify route dump script injected at runtime
+const DUMP_SCRIPT = `
+// Vibecheck Fastify Route Dump
+// Injected when VIBECHECK_ROUTE_DUMP=1
+
+const originalListen = require('fastify').prototype.listen;
+
+require('fastify').prototype.listen = async function(...args) {
+  await this.ready();
+  
+  const routes = [];
+  const routeTable = [];
+  
+  // Iterate all registered routes
+  const printRoutes = (routeArray) => {
+    for (const route of routeArray) {
+      const methods = Array.isArray(route.method) ? route.method : [route.method];
+      for (const method of methods) {
+        routes.push({
+          method: method.toUpperCase(),
+          path: route.path || route.url,
+          prefix: route.prefix || '',
+          fullPath: (route.prefix || '') + (route.path || route.url),
+        });
+        routeTable.push(\`\${method.toUpperCase().padEnd(8)} \${(route.prefix || '') + (route.path || route.url)}\`);
+      }
+    }
+  };
+  
+  // Try different Fastify versions' APIs
+  if (this.printRoutes) {
+    // Fastify 4.x has printRoutes
+    const output = [];
+    this.printRoutes({ commonPrefix: false }, (chunk) => output.push(chunk));
+    console.log('[VIBECHECK_ROUTES_TXT]');
+    console.log(output.join(''));
+    console.log('[/VIBECHECK_ROUTES_TXT]');
+  }
+  
+  // Manual route extraction (works on all versions)
+  if (this[Symbol.for('fastify.routeList')] || this.routes) {
+    const routeList = this[Symbol.for('fastify.routeList')] || this.routes || [];
+    printRoutes(routeList);
+  } else if (this._router && this._router.routes) {
+    printRoutes(this._router.routes);
+  }
+  
+  // Output JSON
+  console.log('[VIBECHECK_ROUTES_JSON]');
+  console.log(JSON.stringify(routes, null, 2));
+  console.log('[/VIBECHECK_ROUTES_JSON]');
+  
+  // Output table
+  console.log('[VIBECHECK_ROUTES_TABLE]');
+  routeTable.forEach(r => console.log(r));
+  console.log('[/VIBECHECK_ROUTES_TABLE]');
+  
+  // Exit cleanly
+  process.exit(0);
+};
+`;
+
+// =============================================================================
+// ROUTE DUMP EXECUTION
+// =============================================================================
+
+/**
+ * Find Fastify entry point
+ */
+function findFastifyEntry(repoRoot, options = {}) {
+  const { fastifyEntry } = options;
+
+  // User-specified entry
+  if (fastifyEntry) {
+    const entryPath = path.join(repoRoot, fastifyEntry);
+    if (fs.existsSync(entryPath)) {
+      return entryPath;
+    }
+  }
+
+  // Common patterns
+  const candidates = [
+    "src/app.ts",
+    "src/app.js",
+    "src/server.ts",
+    "src/server.js",
+    "src/index.ts",
+    "src/index.js",
+    "app.ts",
+    "app.js",
+    "server.ts",
+    "server.js",
+    "index.ts",
+    "index.js",
+  ];
+
+  for (const candidate of candidates) {
+    const candidatePath = path.join(repoRoot, candidate);
+    if (fs.existsSync(candidatePath)) {
+      // Check if it imports fastify
+      try {
+        const content = fs.readFileSync(candidatePath, "utf8");
+        if (content.includes("fastify") || content.includes("Fastify")) {
+          return candidatePath;
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Execute runtime route dump
+ */
+async function executeRouteDump(repoRoot, options = {}) {
+  const { fastifyEntry, timeout = DUMP_TIMEOUT_MS } = options;
+
+  const entryPath = findFastifyEntry(repoRoot, { fastifyEntry });
+  if (!entryPath) {
+    return {
+      success: false,
+      error: "Could not find Fastify entry point",
+      routes: [],
+    };
+  }
+
+  // Determine if we need ts-node
+  const isTypeScript = entryPath.endsWith(".ts");
+  const nodeCommand = isTypeScript ? "npx" : "node";
+  const nodeArgs = isTypeScript
+    ? ["ts-node", "--transpile-only", entryPath]
+    : [entryPath];
+
+  return new Promise((resolve) => {
+    const stdout = [];
+    const stderr = [];
+
+    const child = spawn(nodeCommand, nodeArgs, {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        [DUMP_ENV_VAR]: "1",
+        NODE_ENV: "development",
+        PORT: "0", // Don't actually bind
+      },
+      timeout,
+      shell: process.platform === "win32",
+    });
+
+    child.stdout.on("data", (data) => {
+      stdout.push(data.toString());
+    });
+
+    child.stderr.on("data", (data) => {
+      stderr.push(data.toString());
+    });
+
+    const timeoutId = setTimeout(() => {
+      child.kill("SIGTERM");
+      resolve({
+        success: false,
+        error: `Route dump timed out after ${timeout}ms`,
+        routes: [],
+        stderr: stderr.join(""),
+      });
+    }, timeout);
+
+    child.on("close", (code) => {
+      clearTimeout(timeoutId);
+
+      const output = stdout.join("");
+      const routes = parseRouteDumpOutput(output);
+
+      resolve({
+        success: routes.length > 0,
+        exitCode: code,
+        routes,
+        rawOutput: output,
+        stderr: stderr.join(""),
+        entryPath,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timeoutId);
+      resolve({
+        success: false,
+        error: err.message,
+        routes: [],
+      });
+    });
+  });
+}
+
+/**
+ * Parse route dump output
+ */
+function parseRouteDumpOutput(output) {
+  const routes = [];
+
+  // Try to parse JSON block
+  const jsonMatch = output.match(/\[VIBECHECK_ROUTES_JSON\]([\s\S]*?)\[\/VIBECHECK_ROUTES_JSON\]/);
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1].trim());
+      if (Array.isArray(parsed)) {
+        return parsed.map(normalizeRoute);
+      }
+    } catch {
+      // Fall through to table parsing
+    }
+  }
+
+  // Try to parse table block
+  const tableMatch = output.match(/\[VIBECHECK_ROUTES_TABLE\]([\s\S]*?)\[\/VIBECHECK_ROUTES_TABLE\]/);
+  if (tableMatch) {
+    const lines = tableMatch[1].trim().split("\n");
+    for (const line of lines) {
+      const match = line.match(/^(\w+)\s+(.+)$/);
+      if (match) {
+        routes.push(normalizeRoute({
+          method: match[1].toUpperCase(),
+          path: match[2].trim(),
+        }));
+      }
+    }
+    return routes;
+  }
+
+  // Try printRoutes output (Fastify default format)
+  const printMatch = output.match(/\[VIBECHECK_ROUTES_TXT\]([\s\S]*?)\[\/VIBECHECK_ROUTES_TXT\]/);
+  if (printMatch) {
+    // Parse Fastify's tree format
+    const lines = printMatch[1].trim().split("\n");
+    for (const line of lines) {
+      // Match patterns like "├── GET    /api/users"
+      const match = line.match(/(?:├──|└──|│\s+├──|│\s+└──)?\s*(\w+)\s+(.+?)(?:\s*\(|$)/);
+      if (match) {
+        routes.push(normalizeRoute({
+          method: match[1].toUpperCase(),
+          path: match[2].trim(),
+        }));
+      }
+    }
+  }
+
+  return routes;
+}
+
+/**
+ * Normalize route to standard format
+ */
+function normalizeRoute(route) {
+  const fullPath = route.fullPath || route.path;
+  return {
+    method: (route.method || "GET").toUpperCase(),
+    path: fullPath,
+    canonicalPath: canonicalizePath(fullPath),
+    source: "runtime",
+    confidence: "high",
+  };
+}
+
+/**
+ * Canonicalize path for matching
+ */
+function canonicalizePath(p) {
+  if (!p) return "";
+  return p
+    .replace(/\/+/g, "/")
+    .replace(/\/$/, "")
+    .replace(/:(\w+)/g, ":param")
+    .toLowerCase();
+}
+
+// =============================================================================
+// ROUTE MERGING
+// =============================================================================
+
+/**
+ * Merge runtime routes with static routes
+ * Runtime routes take precedence for existence/method validation
+ */
+function mergeWithStaticRoutes(runtimeRoutes, staticRoutes) {
+  const merged = new Map();
+
+  // Add static routes first
+  for (const route of staticRoutes) {
+    const key = `${route.method}:${route.canonicalPath || canonicalizePath(route.path)}`;
+    merged.set(key, { ...route, source: "static" });
+  }
+
+  // Override with runtime routes
+  for (const route of runtimeRoutes) {
+    const key = `${route.method}:${route.canonicalPath}`;
+    const existing = merged.get(key);
+    
+    if (existing) {
+      // Runtime confirms static
+      merged.set(key, {
+        ...existing,
+        ...route,
+        source: "runtime",
+        staticEvidence: existing.evidence,
+      });
+    } else {
+      // Runtime-only route (autoloaded, etc.)
+      merged.set(key, {
+        ...route,
+        source: "runtime",
+        confidence: "high",
+      });
+    }
+  }
+
+  return Array.from(merged.values());
+}
+
+/**
+ * Find routes in static that don't exist in runtime
+ * These might be false positives
+ */
+function findStaticOnlyRoutes(runtimeRoutes, staticRoutes) {
+  const runtimeKeys = new Set(
+    runtimeRoutes.map(r => `${r.method}:${r.canonicalPath}`)
+  );
+
+  return staticRoutes.filter(route => {
+    const key = `${route.method}:${canonicalizePath(route.path)}`;
+    return !runtimeKeys.has(key);
+  });
+}
+
+// =============================================================================
+// OUTPUT WRITING
+// =============================================================================
+
+/**
+ * Write route dump results to disk
+ */
+function writeRouteDump(repoRoot, result) {
+  const outputDir = path.join(repoRoot, OUTPUT_DIR);
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  // Write routes.json
+  const jsonPath = path.join(outputDir, ROUTES_JSON);
+  const jsonData = {
+    specVersion: "2.0",
+    generatedAt: new Date().toISOString(),
+    source: "runtime",
+    entryPath: result.entryPath,
+    routes: result.routes,
+    count: result.routes.length,
+    fingerprint: generateRouteFingerprint(result.routes),
+  };
+  fs.writeFileSync(jsonPath, JSON.stringify(jsonData, null, 2));
+
+  // Write routes.txt (human-readable)
+  const txtPath = path.join(outputDir, ROUTES_TXT);
+  const txtContent = result.routes
+    .map(r => `${r.method.padEnd(8)} ${r.path}`)
+    .join("\n");
+  fs.writeFileSync(txtPath, txtContent);
+
+  return {
+    jsonPath,
+    txtPath,
+    fingerprint: jsonData.fingerprint,
+  };
+}
+
+/**
+ * Generate fingerprint for routes
+ */
+function generateRouteFingerprint(routes) {
+  const sorted = routes
+    .map(r => `${r.method}:${r.canonicalPath || r.path}`)
+    .sort()
+    .join("\n");
+  return "sha256:" + crypto.createHash("sha256").update(sorted).digest("hex");
+}
+
+/**
+ * Load cached route dump
+ */
+function loadCachedRouteDump(repoRoot) {
+  const jsonPath = path.join(repoRoot, OUTPUT_DIR, ROUTES_JSON);
+  
+  if (!fs.existsSync(jsonPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// SAFETY RULES
+// =============================================================================
+
+/**
+ * Check if route-missing finding should be blocked
+ * Key safety rule: If runtime dump fails, never BLOCK "missing route" 
+ * for Fastify-only routes unless runtime (Playwright) proved 404/405.
+ */
+function shouldBlockMissingRoute(finding, context = {}) {
+  const { runtimeDumpSuccess, runtimeProof, routeFramework } = context;
+
+  // If route-missing was proven by Playwright (404/405), always allow BLOCK
+  if (runtimeProof?.httpStatus === 404 || runtimeProof?.httpStatus === 405) {
+    return true;
+  }
+
+  // If runtime dump succeeded and route not found, allow BLOCK
+  if (runtimeDumpSuccess) {
+    return true;
+  }
+
+  // If Fastify-only and no runtime proof, downgrade to WARN
+  if (routeFramework === "fastify" && !runtimeProof) {
+    return false;
+  }
+
+  // For other frameworks (Next.js, etc.), static analysis is reliable
+  return true;
+}
+
+/**
+ * Apply safety rules to findings
+ */
+function applySafetyRules(findings, context = {}) {
+  return findings.map(finding => {
+    if (finding.detectorId === "D_ROUTE_MISSING" || finding.detectorId === "D_ROUTE_HALLUCINATED") {
+      const shouldBlock = shouldBlockMissingRoute(finding, {
+        ...context,
+        routeFramework: finding.evidence?.[0]?.framework,
+      });
+
+      if (!shouldBlock && finding.severity === "BLOCK") {
+        return {
+          ...finding,
+          severity: "WARN",
+          why: (finding.why || "") + " [Downgraded: runtime dump unavailable]",
+        };
+      }
+    }
+
+    return finding;
+  });
+}
+
+// =============================================================================
+// MAIN EXPORT: EXTRACT WITH RUNTIME
+// =============================================================================
+
+/**
+ * Extract Fastify routes with optional runtime dump
+ */
+async function extractFastifyRoutesWithRuntime(repoRoot, options = {}) {
+  const { 
+    staticRoutes = [], 
+    fastifyEntry,
+    useCache = true,
+    forceRuntime = false,
+  } = options;
+
+  // Try cached first
+  if (useCache && !forceRuntime) {
+    const cached = loadCachedRouteDump(repoRoot);
+    if (cached && cached.routes?.length > 0) {
+      return {
+        success: true,
+        source: "cache",
+        routes: mergeWithStaticRoutes(cached.routes, staticRoutes),
+        runtimeRoutes: cached.routes,
+        staticOnlyRoutes: findStaticOnlyRoutes(cached.routes, staticRoutes),
+        fingerprint: cached.fingerprint,
+      };
+    }
+  }
+
+  // Execute runtime dump
+  const result = await executeRouteDump(repoRoot, { fastifyEntry });
+
+  if (result.success) {
+    // Write to cache
+    const written = writeRouteDump(repoRoot, result);
+
+    return {
+      success: true,
+      source: "runtime",
+      routes: mergeWithStaticRoutes(result.routes, staticRoutes),
+      runtimeRoutes: result.routes,
+      staticOnlyRoutes: findStaticOnlyRoutes(result.routes, staticRoutes),
+      fingerprint: written.fingerprint,
+      entryPath: result.entryPath,
+    };
+  }
+
+  // Runtime failed - return static only with warning
+  return {
+    success: false,
+    source: "static",
+    routes: staticRoutes,
+    runtimeRoutes: [],
+    staticOnlyRoutes: staticRoutes,
+    error: result.error,
+    warning: "Runtime route dump failed; static extraction may have false positives",
+  };
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+module.exports = {
+  // Constants
+  DUMP_ENV_VAR,
+  OUTPUT_DIR,
+  ROUTES_JSON,
+  ROUTES_TXT,
+
+  // Core functions
+  findFastifyEntry,
+  executeRouteDump,
+  parseRouteDumpOutput,
+
+  // Merging
+  mergeWithStaticRoutes,
+  findStaticOnlyRoutes,
+
+  // Output
+  writeRouteDump,
+  loadCachedRouteDump,
+  generateRouteFingerprint,
+
+  // Safety rules
+  shouldBlockMissingRoute,
+  applySafetyRules,
+
+  // Main entry
+  extractFastifyRoutesWithRuntime,
+};