vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/extractors/index.js

@@ -0,0 +1,363 @@
+/**
+ * Route Extractors v2 - Main Entry Point
+ * 
+ * Unified API for extracting routes from Next.js and Fastify projects.
+ * Implements spec-compliant extraction with confidence levels and runtime proof support.
+ */
+
+"use strict";
+
+const path = require("path");
+const { extractNextRoutes, detectNextMode, NEXT_HTTP_METHODS } = require("./next-routes");
+const { extractFastifyRoutes, detectFastify, FASTIFY_METHODS } = require("./fastify-routes");
+const { 
+  normalizeUrl, 
+  toCanonicalPath, 
+  matchRoute, 
+  RouteIndex,
+  getMissingRouteSeverity,
+  isCriticalPath,
+  calculateSpecificity,
+} = require("./route-matcher");
+const {
+  extractClientCalls,
+  extractWrappers,
+  extractUIBindings: extractUIBindingsSimple,
+  canonicalizeUrl,
+  CALL_KINDS,
+  RUNTIMES,
+} = require("./client-calls");
+const {
+  buildProofGraph,
+  findProofGaps,
+  generateProofFindings,
+  serializeProofGraph,
+  mergeRuntimeProof,
+} = require("./proof-graph");
+const {
+  buildTruthpackV2,
+  writeTruthpackV2,
+  loadTruthpackV2,
+} = require("./truthpack-v2");
+const {
+  extractUIBindings,
+  linkBindingsToClientCalls,
+  UI_EVENT_ATTRIBUTES,
+  FORM_ACTION_PATTERNS,
+  TRANSITION_HOOKS,
+} = require("./ui-bindings");
+const {
+  extractFastifyRoutesWithRuntime,
+  findFastifyEntry,
+  executeRouteDump,
+  mergeWithStaticRoutes,
+  applySafetyRules,
+  shouldBlockMissingRoute,
+  DUMP_ENV_VAR,
+} = require("./fastify-route-dump");
+
+/**
+ * Extract all server routes from a project
+ * Detects framework(s) and extracts routes with confidence levels
+ */
+function extractServerRoutes(projectRoot, options = {}) {
+  const { fastifyEntry = null } = options;
+  
+  const result = {
+    stack: {
+      next: { present: false, router: "unknown" },
+      fastify: { present: false, entryFile: null },
+    },
+    routes: [],
+    gaps: [],
+    middleware: { matchers: [], protectedHints: [] },
+    rewrites: [],
+  };
+
+  // Extract Next.js routes
+  const nextResult = extractNextRoutes(projectRoot);
+  if (nextResult.present) {
+    result.stack.next = {
+      present: true,
+      router: nextResult.router,
+      appDir: nextResult.appDir,
+      pagesDir: nextResult.pagesDir,
+      middlewareFile: nextResult.middlewareFile,
+    };
+    result.routes.push(...nextResult.routes);
+    result.middleware = nextResult.middleware;
+    result.rewrites = nextResult.rewrites || [];
+  }
+
+  // Extract Fastify routes
+  const fastifyResult = extractFastifyRoutes(projectRoot, fastifyEntry);
+  if (fastifyResult.present) {
+    result.stack.fastify = {
+      present: true,
+      entryFile: fastifyResult.entryFile,
+      prefixes: fastifyResult.prefixes,
+    };
+    result.routes.push(...fastifyResult.routes);
+    result.gaps.push(...(fastifyResult.gaps || []));
+  }
+
+  // Dedupe routes by canonical path + method
+  result.routes = dedupeRoutes(result.routes);
+
+  return result;
+}
+
+/**
+ * Deduplicate routes, keeping highest confidence
+ */
+function dedupeRoutes(routes) {
+  const seen = new Map();
+  
+  for (const route of routes) {
+    const key = `${route.methods.sort().join(",")}:${route.canonicalPath}`;
+    const existing = seen.get(key);
+    
+    if (!existing) {
+      seen.set(key, route);
+    } else {
+      // Keep higher confidence
+      const confOrder = { high: 3, medium: 2, low: 1 };
+      if ((confOrder[route.confidence] || 0) > (confOrder[existing.confidence] || 0)) {
+        seen.set(key, route);
+      }
+    }
+  }
+
+  return [...seen.values()];
+}
+
+/**
+ * Match client calls against server routes and produce findings
+ */
+function matchClientCalls(clientCalls, serverRoutes, options = {}) {
+  const { basePath = "", trailingSlash = false, rewrites = [] } = options;
+  
+  const index = new RouteIndex(serverRoutes);
+  const results = [];
+
+  for (const call of clientCalls) {
+    const normalizedPath = normalizeUrl(call.resolvedPath || call.urlTemplate, { basePath, trailingSlash });
+    const method = call.method || "UNKNOWN";
+
+    const match = index.match(normalizedPath, method, { 
+      allowMethodMismatch: true,
+      considerRewrites: rewrites,
+    });
+
+    results.push({
+      call,
+      normalizedPath,
+      method,
+      match,
+      isCritical: isCriticalPath(normalizedPath),
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Apply runtime proof to upgrade/downgrade findings
+ * 
+ * Runtime beats static:
+ * - 404/405 at runtime → BLOCK (confirmed missing)
+ * - 2xx at runtime → route exists (even if static missed it)
+ */
+function applyRuntimeProof(matchResults, runtimeRequests) {
+  const requestMap = new Map();
+  
+  // Index runtime requests by normalized path
+  for (const req of runtimeRequests) {
+    const normalizedPath = normalizeUrl(req.url);
+    if (!requestMap.has(normalizedPath)) {
+      requestMap.set(normalizedPath, []);
+    }
+    requestMap.get(normalizedPath).push(req);
+  }
+
+  // Apply proof to each match result
+  for (const result of matchResults) {
+    const runtimeReqs = requestMap.get(result.normalizedPath) || [];
+    
+    if (runtimeReqs.length > 0) {
+      result.hasRuntimeProof = true;
+      
+      // Check for failures
+      const failures = runtimeReqs.filter(r => r.status === 404 || r.status === 405 || r.failed);
+      const successes = runtimeReqs.filter(r => r.status >= 200 && r.status < 300);
+
+      if (failures.length > 0 && successes.length === 0) {
+        result.runtimeResult = failures[0].status === 405 ? "405" : "404";
+        result.runtimeEvidence = failures.slice(0, 3);
+      } else if (successes.length > 0) {
+        result.runtimeResult = "2xx";
+        result.runtimeEvidence = successes.slice(0, 3);
+      }
+    }
+  }
+
+  return matchResults;
+}
+
+/**
+ * Generate route findings from match results
+ */
+function generateRouteFindings(matchResults, options = {}) {
+  const { framework = "unknown" } = options;
+  const findings = [];
+
+  for (const result of matchResults) {
+    // Route missing
+    if (!result.match.matched || result.match.matchType === "none") {
+      const severity = getMissingRouteSeverity({
+        framework,
+        staticConfidence: result.match.confidence,
+        hasRuntimeProof: result.hasRuntimeProof,
+        runtimeResult: result.runtimeResult,
+        isRewriteTarget: result.match.matchType === "rewrite",
+        isCriticalPath: result.isCritical,
+      });
+
+      // Skip if runtime confirmed it exists
+      if (result.runtimeResult === "2xx") continue;
+
+      findings.push({
+        detectorId: "ROUTE_MISSING",
+        severity,
+        category: "Routes",
+        scope: "client",
+        title: `Client calls ${result.method} ${result.normalizedPath} but no server route exists`,
+        why: severity === "BLOCK"
+          ? "Route confirmed missing. This will cause errors in production."
+          : "Route may be missing. Could be dynamically registered or proxied.",
+        confidence: result.hasRuntimeProof ? "high" : result.match.confidence,
+        evidence: result.call.evidence || [],
+        runtimeEvidence: result.runtimeEvidence,
+        call: result.call,
+        matchResult: result.match,
+      });
+    }
+
+    // Method mismatch
+    if (result.match.matched && result.match.methodMismatch) {
+      const severity = result.isCritical ? "BLOCK" : "WARN";
+
+      findings.push({
+        detectorId: "ROUTE_METHOD_MISMATCH",
+        severity,
+        category: "Routes",
+        scope: "client",
+        title: `Method mismatch: client uses ${result.method} but server route ${result.match.route?.canonicalPath} handles ${result.match.route?.methods?.join("/")}`,
+        why: "Method mismatch will cause 405 errors.",
+        confidence: "high",
+        evidence: [
+          ...(result.call.evidence || []),
+          ...(result.match.route?.evidence || []),
+        ],
+        call: result.call,
+        matchResult: result.match,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Build a truthpack-compatible routes structure
+ */
+function buildRoutesForTruthpack(projectRoot, options = {}) {
+  const extraction = extractServerRoutes(projectRoot, options);
+  
+  return {
+    server: extraction.routes.map(r => ({
+      id: r.id,
+      kind: r.kind,
+      methods: r.methods,
+      path: r.canonicalPath,
+      rawPath: r.rawPath,
+      authRequired: r.authRequired,
+      confidence: r.confidence,
+      handler: r.handler,
+      evidence: r.evidence,
+    })),
+    stack: extraction.stack,
+    gaps: extraction.gaps,
+    middleware: extraction.middleware,
+    rewrites: extraction.rewrites,
+  };
+}
+
+module.exports = {
+  // Main extraction
+  extractServerRoutes,
+  extractNextRoutes,
+  extractFastifyRoutes,
+  extractClientCalls,
+  
+  // Detection
+  detectNextMode,
+  detectFastify,
+  
+  // Matching
+  matchClientCalls,
+  matchRoute,
+  RouteIndex,
+  normalizeUrl,
+  toCanonicalPath,
+  canonicalizeUrl,
+  calculateSpecificity,
+  
+  // Runtime proof
+  applyRuntimeProof,
+  
+  // Findings
+  generateRouteFindings,
+  getMissingRouteSeverity,
+  isCriticalPath,
+  
+  // Truthpack integration
+  buildRoutesForTruthpack,
+  
+  // Wrappers
+  extractWrappers,
+  
+  // Proof Graph
+  buildProofGraph,
+  findProofGaps,
+  generateProofFindings,
+  serializeProofGraph,
+  mergeRuntimeProof,
+  
+  // Truthpack v2
+  buildTruthpackV2,
+  writeTruthpackV2,
+  loadTruthpackV2,
+  
+  // UI Bindings
+  extractUIBindings,
+  linkBindingsToClientCalls,
+  UI_EVENT_ATTRIBUTES,
+  FORM_ACTION_PATTERNS,
+  TRANSITION_HOOKS,
+  
+  // Fastify Runtime Dump
+  extractFastifyRoutesWithRuntime,
+  findFastifyEntry,
+  executeRouteDump,
+  mergeWithStaticRoutes,
+  applySafetyRules,
+  shouldBlockMissingRoute,
+  DUMP_ENV_VAR,
+  
+  // Constants
+  NEXT_HTTP_METHODS,
+  FASTIFY_METHODS,
+  CALL_KINDS,
+  RUNTIMES,
+};