@vibecheckai/cli 2.8.2 → 3.0.0

package/bin/runners/lib/route-detection.js

@@ -0,0 +1,1140 @@
+// bin/runners/lib/route-detection.js
+// Multi-framework route detection: Express, Flask, FastAPI, Django, Hono, Koa, etc.
+
+const fg = require("fast-glob");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const parser = require("@babel/parser");
+const traverse = require("@babel/traverse").default;
+const t = require("@babel/types");
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function sha256(text) {
+  return "sha256:" + crypto.createHash("sha256").update(text).digest("hex");
+}
+
+function canonicalizeMethod(m) {
+  const u = String(m || "").toUpperCase();
+  if (u === "ALL" || u === "ANY" || u === "*") return "*";
+  return u;
+}
+
+function canonicalizePath(p) {
+  let s = String(p || "").trim();
+  if (!s.startsWith("/")) s = "/" + s;
+  s = s.replace(/\/+/g, "/");
+  // Next dynamic segments
+  s = s.replace(/\[\[\.{3}([^\]]+)\]\]/g, "*$1?");
+  s = s.replace(/\[\.{3}([^\]]+)\]/g, "*$1");
+  s = s.replace(/\[([^\]]+)\]/g, ":$1");
+  // Python path params: <id> or <int:id>
+  s = s.replace(/<(?:\w+:)?(\w+)>/g, ":$1");
+  // FastAPI path params: {id}
+  s = s.replace(/\{(\w+)\}/g, ":$1");
+  if (s.length > 1) s = s.replace(/\/$/, "");
+  return s;
+}
+
+function joinPaths(prefix, p) {
+  const a = canonicalizePath(prefix || "/");
+  const b = canonicalizePath(p || "/");
+  if (a === "/") return b;
+  if (b === "/") return a;
+  return canonicalizePath(a + "/" + b);
+}
+
+function exists(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function safeRead(fileAbs) {
+  try { return fs.readFileSync(fileAbs, "utf8"); } catch { return ""; }
+}
+
+function parseJS(code) {
+  return parser.parse(code, { sourceType: "unambiguous", plugins: ["typescript", "jsx"] });
+}
+
+function evidenceFromLoc({ fileAbs, fileRel, loc, reason }) {
+  if (!loc) return null;
+  try {
+    const lines = fs.readFileSync(fileAbs, "utf8").split(/\r?\n/);
+    const start = Math.max(1, loc.start?.line || 1);
+    const end = Math.max(start, loc.end?.line || start);
+    const snippet = lines.slice(start - 1, end).join("\n");
+    return {
+      id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+      file: fileRel,
+      lines: `${start}-${end}`,
+      snippetHash: sha256(snippet),
+      reason
+    };
+  } catch { return null; }
+}
+
+// ============================================================================
+// FRAMEWORK DETECTION
+// ============================================================================
+
+const FRAMEWORK_SIGNATURES = {
+  // JavaScript/TypeScript
+  express: ["express", "app.get", "app.post", "app.use", "router.get", "router.post"],
+  fastify: ["fastify", "Fastify", "fastify.get", "fastify.post", "fastify.register"],
+  koa: ["koa", "new Koa", "ctx.body", "router.get"],
+  hono: ["hono", "Hono", "app.get", "app.post"],
+  nestjs: ["@nestjs", "@Controller", "@Get", "@Post"],
+  nextjs: ["next", "next/server", "NextResponse"],
+  
+  // Python
+  flask: ["flask", "Flask", "@app.route", "@blueprint.route"],
+  fastapi: ["fastapi", "FastAPI", "@app.get", "@app.post", "@router.get"],
+  django: ["django", "urlpatterns", "path(", "re_path("],
+  starlette: ["starlette", "Route(", "Mount("],
+  
+  // Go
+  gin: ["gin-gonic", "gin.Default", "r.GET", "r.POST"],
+  echo: ["labstack/echo", "echo.New", "e.GET", "e.POST"],
+  fiber: ["gofiber/fiber", "fiber.New", "app.Get", "app.Post"],
+  
+  // Ruby
+  rails: ["rails", "resources :", "get '", "post '"],
+  sinatra: ["sinatra", "get '", "post '"],
+};
+
+async function detectFrameworks(repoRoot) {
+  const detected = new Set();
+  
+  // Check package.json for JS frameworks
+  const pkgPath = path.join(repoRoot, "package.json");
+  if (exists(pkgPath)) {
+    try {
+      const pkg = JSON.parse(safeRead(pkgPath));
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      
+      if (allDeps.express) detected.add("express");
+      if (allDeps.fastify) detected.add("fastify");
+      if (allDeps.koa) detected.add("koa");
+      if (allDeps.hono) detected.add("hono");
+      if (allDeps["@nestjs/core"]) detected.add("nestjs");
+      if (allDeps.next) detected.add("nextjs");
+    } catch {}
+  }
+  
+  // Check requirements.txt / pyproject.toml for Python
+  const reqPath = path.join(repoRoot, "requirements.txt");
+  if (exists(reqPath)) {
+    const req = safeRead(reqPath).toLowerCase();
+    if (req.includes("flask")) detected.add("flask");
+    if (req.includes("fastapi")) detected.add("fastapi");
+    if (req.includes("django")) detected.add("django");
+    if (req.includes("starlette")) detected.add("starlette");
+  }
+  
+  const pyprojectPath = path.join(repoRoot, "pyproject.toml");
+  if (exists(pyprojectPath)) {
+    const pyp = safeRead(pyprojectPath).toLowerCase();
+    if (pyp.includes("flask")) detected.add("flask");
+    if (pyp.includes("fastapi")) detected.add("fastapi");
+    if (pyp.includes("django")) detected.add("django");
+  }
+  
+  // Check Gemfile for Ruby
+  const gemfilePath = path.join(repoRoot, "Gemfile");
+  if (exists(gemfilePath)) {
+    const gem = safeRead(gemfilePath).toLowerCase();
+    if (gem.includes("rails")) detected.add("rails");
+    if (gem.includes("sinatra")) detected.add("sinatra");
+  }
+  
+  // Check go.mod for Go
+  const gomodPath = path.join(repoRoot, "go.mod");
+  if (exists(gomodPath)) {
+    const gomod = safeRead(gomodPath).toLowerCase();
+    if (gomod.includes("gin-gonic")) detected.add("gin");
+    if (gomod.includes("labstack/echo")) detected.add("echo");
+    if (gomod.includes("gofiber/fiber")) detected.add("fiber");
+    if (gomod.includes("go-chi/chi")) detected.add("chi");
+    if (gomod.includes("gorilla/mux")) detected.add("gorilla");
+    detected.add("go");
+  }
+  
+  // Check for OpenAPI/Swagger specs
+  const openapiFiles = ["openapi.json", "openapi.yaml", "openapi.yml", "swagger.json", "swagger.yaml"];
+  for (const f of openapiFiles) {
+    if (exists(path.join(repoRoot, f))) {
+      detected.add("openapi");
+      break;
+    }
+  }
+  
+  // Check for GraphQL
+  if (exists(path.join(repoRoot, "schema.graphql")) || exists(path.join(repoRoot, "schema.gql"))) {
+    detected.add("graphql");
+  }
+  
+  return Array.from(detected);
+}
+
+// ============================================================================
+// EXPRESS ROUTE DETECTION
+// ============================================================================
+
+const EXPRESS_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "all", "use"]);
+
+async function resolveExpressRoutes(repoRoot) {
+  // Find all potential Express/server files (comprehensive for monorepos)
+  const files = await fg([
+    "**/server.{ts,js}",
+    "**/app.{ts,js}",
+    "**/index.{ts,js}",
+    "**/routes/**/*.{ts,js}",
+    "**/api/**/*.{ts,js}",
+    "**/src/**/*.{ts,js}",
+    "**/apps/**/src/**/*.{ts,js}",
+    "**/packages/**/src/**/*.{ts,js}",
+    "**/services/**/*.{ts,js}"
+  ], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: [
+      "**/node_modules/**",
+      "**/.next/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/test/**",
+      "**/tests/**",
+      "**/__tests__/**",
+      "**/*.test.*",
+      "**/*.spec.*",
+      "**/jest.*",
+      "**/*.d.ts"
+    ]
+  });
+
+  const routes = [];
+  const appNames = new Set(["app", "router", "express", "server"]);
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    // Quick check if file uses Express
+    if (!code.includes("express") && !code.includes("app.") && !code.includes("router.")) continue;
+    
+    let ast;
+    try { ast = parseJS(code); } catch { continue; }
+
+    // Detect Express app/router instances
+    traverse(ast, {
+      VariableDeclarator(p) {
+        if (!t.isIdentifier(p.node.id)) return;
+        const id = p.node.id.name;
+        const init = p.node.init;
+        if (!init) return;
+        
+        // const app = express()
+        if (t.isCallExpression(init) && t.isIdentifier(init.callee) && init.callee.name === "express") {
+          appNames.add(id);
+        }
+        // const router = express.Router()
+        if (t.isCallExpression(init) && t.isMemberExpression(init.callee)) {
+          const obj = init.callee.object;
+          const prop = init.callee.property;
+          if (t.isIdentifier(obj) && obj.name === "express" && t.isIdentifier(prop) && prop.name === "Router") {
+            appNames.add(id);
+          }
+        }
+      }
+    });
+
+    // Extract routes
+    traverse(ast, {
+      CallExpression(p) {
+        const callee = p.node.callee;
+        if (!t.isMemberExpression(callee)) return;
+        if (!t.isIdentifier(callee.object) || !t.isIdentifier(callee.property)) return;
+
+        const obj = callee.object.name;
+        const method = callee.property.name;
+
+        if (!appNames.has(obj)) return;
+        if (!EXPRESS_METHODS.has(method)) return;
+
+        const arg0 = p.node.arguments[0];
+        if (!t.isStringLiteral(arg0)) return;
+
+        const routePath = canonicalizePath(arg0.value);
+        
+        // Skip middleware mounts without paths
+        if (method === "use" && !arg0.value.startsWith("/")) return;
+
+        const ev = evidenceFromLoc({
+          fileAbs, fileRel, loc: p.node.loc,
+          reason: `Express ${method.toUpperCase()}("${arg0.value}")`
+        });
+
+        routes.push({
+          method: canonicalizeMethod(method === "use" ? "*" : method),
+          path: routePath,
+          handler: fileRel,
+          framework: "express",
+          confidence: "high",
+          evidence: ev ? [ev] : []
+        });
+      }
+    });
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// PYTHON: FLASK ROUTE DETECTION
+// ============================================================================
+
+async function resolveFlaskRoutes(repoRoot) {
+  const files = await fg(["**/*.py"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/venv/**", "**/.venv/**", "**/env/**", "**/__pycache__/**", "**/site-packages/**", "**/test*/**"]
+  });
+
+  const routes = [];
+  
+  // Flask route decorator pattern: @app.route('/path', methods=['GET', 'POST'])
+  const routePattern = /@(\w+)\.(route|get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/g;
+  const methodsPattern = /methods\s*=\s*\[([^\]]+)\]/;
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    if (!code.includes("@") || (!code.includes("route") && !code.includes("flask"))) continue;
+
+    const lines = code.split(/\r?\n/);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      // Match @app.route('/path') or @blueprint.route('/path')
+      const routeMatch = line.match(/@(\w+)\.(route|get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/);
+      if (!routeMatch) continue;
+
+      const [, appName, decorator, routePath] = routeMatch;
+      let methods = ["GET"];
+      
+      if (decorator !== "route") {
+        methods = [decorator.toUpperCase()];
+      } else {
+        // Check for methods parameter
+        const methodMatch = line.match(methodsPattern);
+        if (methodMatch) {
+          methods = methodMatch[1].replace(/['"]/g, "").split(",").map(m => m.trim().toUpperCase());
+        }
+      }
+
+      for (const method of methods) {
+        routes.push({
+          method: canonicalizeMethod(method),
+          path: canonicalizePath(routePath),
+          handler: fileRel,
+          framework: "flask",
+          confidence: "high",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Flask @${appName}.${decorator}("${routePath}")`
+          }]
+        });
+      }
+    }
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// PYTHON: FASTAPI ROUTE DETECTION
+// ============================================================================
+
+async function resolveFastAPIRoutes(repoRoot) {
+  const files = await fg(["**/*.py"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/venv/**", "**/.venv/**", "**/env/**", "**/__pycache__/**", "**/site-packages/**", "**/test*/**"]
+  });
+
+  const routes = [];
+  
+  // FastAPI route decorator pattern: @app.get('/path') or @router.post('/path')
+  const routePattern = /@(\w+)\.(get|post|put|patch|delete|options|head)\s*\(\s*['"]([^'"]+)['"]/;
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    if (!code.includes("@") || !code.includes("fastapi")) continue;
+
+    const lines = code.split(/\r?\n/);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      const routeMatch = line.match(routePattern);
+      if (!routeMatch) continue;
+
+      const [, appName, method, routePath] = routeMatch;
+
+      routes.push({
+        method: canonicalizeMethod(method),
+        path: canonicalizePath(routePath),
+        handler: fileRel,
+        framework: "fastapi",
+        confidence: "high",
+        evidence: [{
+          id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+          file: fileRel,
+          lines: `${i + 1}`,
+          reason: `FastAPI @${appName}.${method}("${routePath}")`
+        }]
+      });
+    }
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// PYTHON: DJANGO ROUTE DETECTION
+// ============================================================================
+
+async function resolveDjangoRoutes(repoRoot) {
+  const files = await fg(["**/urls.py", "**/urls/*.py"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/venv/**", "**/.venv/**", "**/env/**", "**/__pycache__/**", "**/site-packages/**"]
+  });
+
+  const routes = [];
+  
+  // Django path pattern: path('route/', view, name='name')
+  const pathPattern = /path\s*\(\s*['"]([^'"]*)['"]/g;
+  const rePathPattern = /re_path\s*\(\s*r?['"]([^'"]+)['"]/g;
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    if (!code.includes("path(") && !code.includes("re_path(")) continue;
+
+    const lines = code.split(/\r?\n/);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      // Match path('route/', ...)
+      const pathMatch = line.match(/path\s*\(\s*['"]([^'"]*)['"]/);
+      if (pathMatch) {
+        const routePath = pathMatch[1];
+        routes.push({
+          method: "*",
+          path: canonicalizePath("/" + routePath),
+          handler: fileRel,
+          framework: "django",
+          confidence: "med",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Django path("${routePath}")`
+          }]
+        });
+      }
+      
+      // Match re_path(r'^route/', ...)
+      const rePathMatch = line.match(/re_path\s*\(\s*r?['"]([^'"]+)['"]/);
+      if (rePathMatch) {
+        let routePath = rePathMatch[1].replace(/^\^/, "").replace(/\$$/, "");
+        routes.push({
+          method: "*",
+          path: canonicalizePath("/" + routePath),
+          handler: fileRel,
+          framework: "django",
+          confidence: "med",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Django re_path("${routePath}")`
+          }]
+        });
+      }
+    }
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// HONO ROUTE DETECTION
+// ============================================================================
+
+async function resolveHonoRoutes(repoRoot) {
+  const files = await fg(["**/*.{ts,js}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/test/**"]
+  });
+
+  const routes = [];
+  const HONO_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "all"]);
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    if (!code.includes("Hono") && !code.includes("hono")) continue;
+
+    let ast;
+    try { ast = parseJS(code); } catch { continue; }
+
+    const honoNames = new Set(["app"]);
+
+    traverse(ast, {
+      VariableDeclarator(p) {
+        if (!t.isIdentifier(p.node.id)) return;
+        const init = p.node.init;
+        if (!init) return;
+        if (t.isNewExpression(init) && t.isIdentifier(init.callee) && init.callee.name === "Hono") {
+          honoNames.add(p.node.id.name);
+        }
+      }
+    });
+
+    traverse(ast, {
+      CallExpression(p) {
+        const callee = p.node.callee;
+        if (!t.isMemberExpression(callee)) return;
+        if (!t.isIdentifier(callee.object) || !t.isIdentifier(callee.property)) return;
+
+        const obj = callee.object.name;
+        const method = callee.property.name;
+
+        if (!honoNames.has(obj)) return;
+        if (!HONO_METHODS.has(method)) return;
+
+        const arg0 = p.node.arguments[0];
+        if (!t.isStringLiteral(arg0)) return;
+
+        const ev = evidenceFromLoc({
+          fileAbs, fileRel, loc: p.node.loc,
+          reason: `Hono ${method.toUpperCase()}("${arg0.value}")`
+        });
+
+        routes.push({
+          method: canonicalizeMethod(method),
+          path: canonicalizePath(arg0.value),
+          handler: fileRel,
+          framework: "hono",
+          confidence: "high",
+          evidence: ev ? [ev] : []
+        });
+      }
+    });
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// KOA ROUTE DETECTION
+// ============================================================================
+
+async function resolveKoaRoutes(repoRoot) {
+  const files = await fg(["**/*.{ts,js}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/test/**"]
+  });
+
+  const routes = [];
+  const KOA_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "all"]);
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    if (!code.includes("koa") && !code.includes("Router")) continue;
+
+    let ast;
+    try { ast = parseJS(code); } catch { continue; }
+
+    traverse(ast, {
+      CallExpression(p) {
+        const callee = p.node.callee;
+        if (!t.isMemberExpression(callee)) return;
+        if (!t.isIdentifier(callee.object) || !t.isIdentifier(callee.property)) return;
+
+        const obj = callee.object.name;
+        const method = callee.property.name;
+
+        if (!obj.toLowerCase().includes("router")) return;
+        if (!KOA_METHODS.has(method)) return;
+
+        const arg0 = p.node.arguments[0];
+        if (!t.isStringLiteral(arg0)) return;
+
+        const ev = evidenceFromLoc({
+          fileAbs, fileRel, loc: p.node.loc,
+          reason: `Koa router.${method}("${arg0.value}")`
+        });
+
+        routes.push({
+          method: canonicalizeMethod(method),
+          path: canonicalizePath(arg0.value),
+          handler: fileRel,
+          framework: "koa",
+          confidence: "high",
+          evidence: ev ? [ev] : []
+        });
+      }
+    });
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// OPENAPI/SWAGGER SPEC PARSING
+// ============================================================================
+
+async function resolveOpenAPIRoutes(repoRoot) {
+  const files = await fg([
+    "**/openapi.json",
+    "**/openapi.yaml",
+    "**/openapi.yml",
+    "**/swagger.json",
+    "**/swagger.yaml",
+    "**/swagger.yml",
+    "**/api-spec.json",
+    "**/api-spec.yaml"
+  ], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/dist/**", "**/build/**"]
+  });
+
+  const routes = [];
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const content = safeRead(fileAbs);
+    
+    let spec;
+    try {
+      if (fileAbs.endsWith(".json")) {
+        spec = JSON.parse(content);
+      } else {
+        // Simple YAML parsing for common patterns
+        const lines = content.split(/\r?\n/);
+        const pathMatches = [];
+        let currentPath = null;
+        
+        for (const line of lines) {
+          // Match path definitions like "  /api/users:"
+          const pathMatch = line.match(/^  ['"]?(\/[^'":\s]+)['"]?:\s*$/);
+          if (pathMatch) {
+            currentPath = pathMatch[1];
+            continue;
+          }
+          // Match HTTP methods like "    get:" or "    post:"
+          if (currentPath) {
+            const methodMatch = line.match(/^\s{4}(get|post|put|patch|delete|options|head):\s*$/);
+            if (methodMatch) {
+              pathMatches.push({ path: currentPath, method: methodMatch[1] });
+            }
+          }
+        }
+        
+        for (const { path: p, method } of pathMatches) {
+          routes.push({
+            method: canonicalizeMethod(method),
+            path: canonicalizePath(p),
+            handler: fileRel,
+            framework: "openapi",
+            confidence: "high",
+            evidence: [{
+              id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+              file: fileRel,
+              lines: "1",
+              reason: `OpenAPI spec ${method.toUpperCase()} ${p}`
+            }]
+          });
+        }
+        continue;
+      }
+    } catch { continue; }
+
+    // Parse JSON OpenAPI spec
+    if (spec && spec.paths) {
+      for (const [pathStr, pathItem] of Object.entries(spec.paths)) {
+        const methods = ["get", "post", "put", "patch", "delete", "options", "head"];
+        for (const method of methods) {
+          if (pathItem[method]) {
+            routes.push({
+              method: canonicalizeMethod(method),
+              path: canonicalizePath(pathStr),
+              handler: fileRel,
+              framework: "openapi",
+              confidence: "high",
+              evidence: [{
+                id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+                file: fileRel,
+                lines: "1",
+                reason: `OpenAPI spec ${method.toUpperCase()} ${pathStr}`
+              }]
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// GRAPHQL ENDPOINT DETECTION
+// ============================================================================
+
+async function resolveGraphQLRoutes(repoRoot) {
+  const routes = [];
+  
+  // Find GraphQL schema files
+  const schemaFiles = await fg([
+    "**/*.graphql",
+    "**/*.gql",
+    "**/schema.graphql",
+    "**/schema.gql"
+  ], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/dist/**", "**/build/**"]
+  });
+
+  // Find GraphQL server setup files
+  const serverFiles = await fg([
+    "**/*.{ts,js,py}"
+  ], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/test/**", "**/*.d.ts"]
+  });
+
+  // Check for GraphQL endpoints in server files
+  for (const fileAbs of serverFiles) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    // Skip if no GraphQL indicators
+    if (!code.includes("graphql") && !code.includes("GraphQL") && !code.includes("gql")) continue;
+
+    // Detect common GraphQL endpoint patterns
+    const patterns = [
+      // Apollo Server: app.use('/graphql', ...)
+      /(?:app|server|router)\.(use|post|get)\s*\(\s*['"]([^'"]*graphql[^'"]*)['"]/gi,
+      // Express GraphQL: graphqlHTTP({ ... })
+      /graphqlHTTP\s*\(/gi,
+      // Apollo Server: new ApolloServer
+      /new\s+ApolloServer/gi,
+      // Yoga: createYoga
+      /createYoga\s*\(/gi,
+      // Python Strawberry/Ariadne
+      /GraphQLRouter|graphql_app|make_executable_schema/gi
+    ];
+
+    let hasGraphQL = false;
+    let endpointPath = "/graphql"; // Default
+    
+    for (const pattern of patterns) {
+      const match = code.match(pattern);
+      if (match) {
+        hasGraphQL = true;
+        // Try to extract custom endpoint path
+        const pathMatch = code.match(/['"]([^'"]*graphql[^'"]*)['"]/i);
+        if (pathMatch) {
+          endpointPath = pathMatch[1];
+        }
+        break;
+      }
+    }
+
+    if (hasGraphQL) {
+      routes.push({
+        method: "POST",
+        path: canonicalizePath(endpointPath),
+        handler: fileRel,
+        framework: "graphql",
+        confidence: "high",
+        evidence: [{
+          id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+          file: fileRel,
+          lines: "1",
+          reason: `GraphQL endpoint detected`
+        }]
+      });
+      
+      // GraphQL also supports GET for queries
+      routes.push({
+        method: "GET",
+        path: canonicalizePath(endpointPath),
+        handler: fileRel,
+        framework: "graphql",
+        confidence: "med",
+        evidence: [{
+          id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+          file: fileRel,
+          lines: "1",
+          reason: `GraphQL endpoint (GET for queries)`
+        }]
+      });
+    }
+  }
+
+  // If schema files exist, assume /graphql endpoint
+  if (schemaFiles.length > 0 && routes.length === 0) {
+    const fileRel = path.relative(repoRoot, schemaFiles[0]).replace(/\\/g, "/");
+    routes.push({
+      method: "*",
+      path: "/graphql",
+      handler: fileRel,
+      framework: "graphql",
+      confidence: "med",
+      evidence: [{
+        id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+        file: fileRel,
+        lines: "1",
+        reason: `GraphQL schema file found`
+      }]
+    });
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// GO ROUTE DETECTION (Gin, Echo, Fiber)
+// ============================================================================
+
+async function resolveGoRoutes(repoRoot) {
+  const files = await fg(["**/*.go"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/vendor/**", "**/*_test.go", "**/testdata/**"]
+  });
+
+  const routes = [];
+  const GO_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "Any", "Handle"];
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    // Skip if no router indicators
+    if (!code.includes("gin") && !code.includes("echo") && !code.includes("fiber") && 
+        !code.includes("mux") && !code.includes("chi") && !code.includes("http.Handle")) continue;
+
+    const lines = code.split(/\r?\n/);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      // Gin: r.GET("/path", handler)
+      // Echo: e.GET("/path", handler)
+      // Fiber: app.Get("/path", handler)
+      const ginEchoMatch = line.match(/(\w+)\.(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|Any|Handle)\s*\(\s*["'`]([^"'`]+)["'`]/i);
+      if (ginEchoMatch) {
+        const [, , method, routePath] = ginEchoMatch;
+        routes.push({
+          method: canonicalizeMethod(method === "Any" || method === "Handle" ? "*" : method),
+          path: canonicalizePath(routePath),
+          handler: fileRel,
+          framework: "go",
+          confidence: "high",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Go ${method}("${routePath}")`
+          }]
+        });
+        continue;
+      }
+
+      // Fiber lowercase: app.Get("/path", handler)
+      const fiberMatch = line.match(/(\w+)\.(Get|Post|Put|Patch|Delete|Options|Head|All)\s*\(\s*["'`]([^"'`]+)["'`]/);
+      if (fiberMatch) {
+        const [, , method, routePath] = fiberMatch;
+        routes.push({
+          method: canonicalizeMethod(method === "All" ? "*" : method),
+          path: canonicalizePath(routePath),
+          handler: fileRel,
+          framework: "fiber",
+          confidence: "high",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Fiber ${method}("${routePath}")`
+          }]
+        });
+        continue;
+      }
+
+      // Chi router: r.Get("/path", handler)
+      const chiMatch = line.match(/(\w+)\.(Get|Post|Put|Patch|Delete|Options|Head|Connect|Trace|MethodFunc)\s*\(\s*["'`]([^"'`]+)["'`]/);
+      if (chiMatch) {
+        const [, , method, routePath] = chiMatch;
+        routes.push({
+          method: canonicalizeMethod(method),
+          path: canonicalizePath(routePath),
+          handler: fileRel,
+          framework: "chi",
+          confidence: "high",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Chi ${method}("${routePath}")`
+          }]
+        });
+        continue;
+      }
+
+      // Gorilla mux: r.HandleFunc("/path", handler).Methods("GET")
+      const muxMatch = line.match(/HandleFunc\s*\(\s*["'`]([^"'`]+)["'`]/);
+      if (muxMatch) {
+        const routePath = muxMatch[1];
+        // Try to find .Methods() on same or next line
+        const methodMatch = (line + (lines[i + 1] || "")).match(/\.Methods\s*\(\s*["'`]([^"'`]+)["'`]/);
+        const method = methodMatch ? methodMatch[1] : "*";
+        
+        routes.push({
+          method: canonicalizeMethod(method),
+          path: canonicalizePath(routePath),
+          handler: fileRel,
+          framework: "gorilla",
+          confidence: "high",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Gorilla mux HandleFunc("${routePath}")`
+          }]
+        });
+        continue;
+      }
+
+      // Standard library: http.HandleFunc("/path", handler)
+      const stdMatch = line.match(/http\.HandleFunc\s*\(\s*["'`]([^"'`]+)["'`]/);
+      if (stdMatch) {
+        routes.push({
+          method: "*",
+          path: canonicalizePath(stdMatch[1]),
+          handler: fileRel,
+          framework: "go-stdlib",
+          confidence: "high",
+          evidence: [{
+            id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+            file: fileRel,
+            lines: `${i + 1}`,
+            reason: `Go http.HandleFunc("${stdMatch[1]}")`
+          }]
+        });
+      }
+    }
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// PYTHON CLIENT REFS (requests, httpx, aiohttp)
+// ============================================================================
+
+async function resolvePythonClientRefs(repoRoot) {
+  const files = await fg(["**/*.py"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/venv/**", "**/.venv/**", "**/env/**", "**/__pycache__/**", "**/site-packages/**", "**/test*/**"]
+  });
+
+  const refs = [];
+  
+  // Match requests.get('/api/...'), httpx.post('/api/...'), etc.
+  const httpPattern = /(requests|httpx|aiohttp|session)\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/g;
+  const fetchPattern = /fetch\s*\(\s*['"]([^'"]+)['"]/g;
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    
+    const lines = code.split(/\r?\n/);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      // Match requests.get('/api/...')
+      const httpMatch = line.match(/(requests|httpx|aiohttp|session)\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/);
+      if (httpMatch) {
+        const [, lib, method, url] = httpMatch;
+        if (url.startsWith("/") || url.startsWith("http")) {
+          refs.push({
+            method: canonicalizeMethod(method),
+            path: canonicalizePath(url.replace(/^https?:\/\/[^\/]+/, "")),
+            source: fileRel,
+            confidence: "high",
+            evidence: [{
+              id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+              file: fileRel,
+              lines: `${i + 1}`,
+              reason: `Python ${lib}.${method}("${url}")`
+            }]
+          });
+        }
+      }
+    }
+  }
+
+  return refs;
+}
+
+// ============================================================================
+// MAIN: RESOLVE ALL ROUTES
+// ============================================================================
+
+async function resolveAllRoutes(repoRoot) {
+  const frameworks = await detectFrameworks(repoRoot);
+  
+  const allRoutes = [];
+  const allClientRefs = [];
+  const gaps = [];
+  
+  console.log(`  📦 Detected frameworks: ${frameworks.length > 0 ? frameworks.join(", ") : "none detected, scanning all"}`);
+  
+  // Always scan for routes regardless of detected frameworks
+  // JavaScript/TypeScript frameworks
+  try {
+    const expressRoutes = await resolveExpressRoutes(repoRoot);
+    if (expressRoutes.length > 0) {
+      console.log(`     ✓ Express: ${expressRoutes.length} routes`);
+      allRoutes.push(...expressRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "express_scan_error", error: e.message }); }
+  
+  try {
+    const honoRoutes = await resolveHonoRoutes(repoRoot);
+    if (honoRoutes.length > 0) {
+      console.log(`     ✓ Hono: ${honoRoutes.length} routes`);
+      allRoutes.push(...honoRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "hono_scan_error", error: e.message }); }
+  
+  try {
+    const koaRoutes = await resolveKoaRoutes(repoRoot);
+    if (koaRoutes.length > 0) {
+      console.log(`     ✓ Koa: ${koaRoutes.length} routes`);
+      allRoutes.push(...koaRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "koa_scan_error", error: e.message }); }
+  
+  // Python frameworks
+  try {
+    const flaskRoutes = await resolveFlaskRoutes(repoRoot);
+    if (flaskRoutes.length > 0) {
+      console.log(`     ✓ Flask: ${flaskRoutes.length} routes`);
+      allRoutes.push(...flaskRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "flask_scan_error", error: e.message }); }
+  
+  try {
+    const fastapiRoutes = await resolveFastAPIRoutes(repoRoot);
+    if (fastapiRoutes.length > 0) {
+      console.log(`     ✓ FastAPI: ${fastapiRoutes.length} routes`);
+      allRoutes.push(...fastapiRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "fastapi_scan_error", error: e.message }); }
+  
+  try {
+    const djangoRoutes = await resolveDjangoRoutes(repoRoot);
+    if (djangoRoutes.length > 0) {
+      console.log(`     ✓ Django: ${djangoRoutes.length} routes`);
+      allRoutes.push(...djangoRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "django_scan_error", error: e.message }); }
+  
+  // Python client refs
+  try {
+    const pythonRefs = await resolvePythonClientRefs(repoRoot);
+    if (pythonRefs.length > 0) {
+      console.log(`     ✓ Python client refs: ${pythonRefs.length}`);
+      allClientRefs.push(...pythonRefs);
+    }
+  } catch (e) { gaps.push({ kind: "python_client_scan_error", error: e.message }); }
+  
+  // OpenAPI/Swagger specs (high accuracy)
+  try {
+    const openapiRoutes = await resolveOpenAPIRoutes(repoRoot);
+    if (openapiRoutes.length > 0) {
+      console.log(`     ✓ OpenAPI spec: ${openapiRoutes.length} routes`);
+      allRoutes.push(...openapiRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "openapi_scan_error", error: e.message }); }
+  
+  // GraphQL endpoints
+  try {
+    const graphqlRoutes = await resolveGraphQLRoutes(repoRoot);
+    if (graphqlRoutes.length > 0) {
+      console.log(`     ✓ GraphQL: ${graphqlRoutes.length} endpoints`);
+      allRoutes.push(...graphqlRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "graphql_scan_error", error: e.message }); }
+  
+  // Go frameworks (Gin, Echo, Fiber, Chi, Gorilla, stdlib)
+  try {
+    const goRoutes = await resolveGoRoutes(repoRoot);
+    if (goRoutes.length > 0) {
+      console.log(`     ✓ Go: ${goRoutes.length} routes`);
+      allRoutes.push(...goRoutes);
+    }
+  } catch (e) { gaps.push({ kind: "go_scan_error", error: e.message }); }
+  
+  return {
+    routes: allRoutes,
+    clientRefs: allClientRefs,
+    gaps,
+    frameworks
+  };
+}
+
+module.exports = {
+  detectFrameworks,
+  resolveExpressRoutes,
+  resolveFlaskRoutes,
+  resolveFastAPIRoutes,
+  resolveDjangoRoutes,
+  resolveHonoRoutes,
+  resolveKoaRoutes,
+  resolveOpenAPIRoutes,
+  resolveGraphQLRoutes,
+  resolveGoRoutes,
+  resolvePythonClientRefs,
+  resolveAllRoutes,
+  canonicalizeMethod,
+  canonicalizePath
+};