@vibecheckai/cli 3.2.5 → 3.3.0

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

@@ -1,573 +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,
-};
+/**
+ * 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,
+};