vibecheck-ai 2.0.1 → 5.0.0

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

@@ -0,0 +1,1322 @@
+/**
+ * Route Truth v1 - JavaScript Runtime (hardened + more accurate)
+ *
+ * Upgrades vs your version:
+ * - Next.js App/Pages routes: AST-based export detection + safer path derivation
+ * - Fastify routes: AST-based extraction (get/post/route/register + inline plugins + relative import resolution)
+ * - Better canonicalization + prefix joining + safer matching (no weird edge crashes)
+ * - Gaps are real (unresolved plugins/modules) instead of silent “false”
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+let fg = null;
+try {
+  fg = require("fast-glob");
+} catch { /* optional */ }
+
+const parser = require("@babel/parser");
+const traverse = require("@babel/traverse").default;
+const t = require("@babel/types");
+
+// ============================================================================
+// CANONICALIZATION + MATCHING
+// ============================================================================
+
+function canonicalizePath(p) {
+  let s = String(p || "").trim();
+  if (!s) return "/";
+  if (!s.startsWith("/")) s = "/" + s;
+  s = s.replace(/\/+/g, "/");
+
+  // Next.js dynamic segments
+  s = s.replace(/\[\[\.{3}([^\]]+)\]\]/g, "*$1?"); // [[...slug]] -> *slug?
+  s = s.replace(/\[\.{3}([^\]]+)\]/g, "*$1");      // [...slug]  -> *slug
+  s = s.replace(/\[([^\]]+)\]/g, ":$1");           // [id]       -> :id
+
+  if (s.length > 1) s = s.replace(/\/$/, "");
+  return s;
+}
+
+function canonicalizeMethod(m) {
+  const u = String(m || "").toUpperCase();
+  if (u === "ALL" || u === "ANY" || u === "*" ) return "*";
+  return u || "*";
+}
+
+function joinPrefix(prefix, p) {
+  const a = canonicalizePath(prefix || "/");
+  const b = canonicalizePath(p || "/");
+  if (a === "/") return b;
+  if (b === "/") return a;
+  return canonicalizePath(a + "/" + b);
+}
+
+function isParameterizedPath(p) {
+  const s = canonicalizePath(p);
+  return s.includes(":") || s.includes("*");
+}
+
+/**
+ * Match a pattern against a concrete path.
+ * Supported:
+ * - :id matches one segment
+ * - *slug or *slug? matches the rest of the path (0+ segments)
+ */
+function matchPath(pattern, concrete) {
+  const pat = canonicalizePath(pattern);
+  const con = canonicalizePath(concrete);
+
+  if (pat === con) return true;
+
+  const pParts = pat.split("/").filter(Boolean);
+  const cParts = con.split("/").filter(Boolean);
+
+  let pIdx = 0, cIdx = 0;
+
+  while (pIdx < pParts.length && cIdx < cParts.length) {
+    const pSeg = pParts[pIdx];
+    const cSeg = cParts[cIdx];
+
+    if (pSeg.startsWith("*")) {
+      // splat: match remainder (including empty remainder)
+      return true;
+    }
+    if (pSeg.startsWith(":")) {
+      pIdx++; cIdx++; continue;
+    }
+    if (pSeg !== cSeg) return false;
+
+    pIdx++; cIdx++;
+  }
+
+  // If pattern still has a trailing splat, it matches empty remainder
+  if (pIdx === pParts.length - 1 && pParts[pIdx]?.startsWith("*")) return true;
+
+  return pIdx === pParts.length && cIdx === cParts.length;
+}
+
+function matchMethod(pattern, concrete) {
+  const p = canonicalizeMethod(pattern);
+  const c = canonicalizeMethod(concrete);
+  if (p === "*") return true;
+  return p === c;
+}
+
+// ============================================================================
+// COMMON HELPERS
+// ============================================================================
+
+const NEXT_HTTP_METHODS = new Set(["GET","POST","PUT","PATCH","DELETE","OPTIONS","HEAD"]);
+let evidenceCounter = 0;
+
+function sha256Short(txt) {
+  return crypto.createHash("sha256").update(String(txt || "")).digest("hex").slice(0, 16);
+}
+
+function createEvidence(file, lines, reason, snippet) {
+  evidenceCounter++;
+  return {
+    id: `ev_${String(evidenceCounter).padStart(4, "0")}`,
+    file,
+    lines,
+    snippetHash: `sha256:${sha256Short(snippet || "")}`,
+    reason,
+  };
+}
+
+function safeRead(fileAbs) {
+  try { return fs.readFileSync(fileAbs, "utf8"); } catch { return null; }
+}
+
+function parseFile(code) {
+  return parser.parse(code, {
+    sourceType: "unambiguous",
+    plugins: ["typescript", "jsx"],
+    errorRecovery: true,
+    ranges: false,
+  });
+}
+
+function evidenceFromLoc({ fileAbs, fileRel, loc, reason }) {
+  if (!loc || !loc.start) return [];
+  const code = safeRead(fileAbs);
+  if (!code) return [];
+  const lines = code.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 [createEvidence(fileRel, `${start}-${end}`, reason, snippet)];
+}
+
+function findFilesFallback(dirAbs, includeRe, excludeRe) {
+  const out = [];
+  function walk(d) {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      const full = path.join(d, ent.name);
+      if (ent.isDirectory()) {
+        if (
+          ent.name === "node_modules" ||
+          ent.name === ".next" ||
+          ent.name === "dist" ||
+          ent.name === "build" ||
+          ent.name === "coverage" ||
+          ent.name.startsWith(".")
+        ) continue;
+        walk(full);
+      } else if (ent.isFile()) {
+        if (excludeRe && excludeRe.test(ent.name)) continue;
+        if (includeRe.test(ent.name)) out.push(full);
+      }
+    }
+  }
+  walk(dirAbs);
+  return out;
+}
+
+async function globFiles(repoRoot, patterns, ignore) {
+  if (fg) {
+    return fg(patterns, {
+      cwd: repoRoot,
+      absolute: true,
+      dot: false,
+      ignore: ignore || [
+        "**/node_modules/**",
+        "**/.next/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/coverage/**",
+      ],
+    });
+  }
+
+  // fallback: only supports the specific Next patterns we use
+  const out = [];
+  for (const ptn of patterns) {
+    // minimal handling: find root dirs from patterns
+    if (ptn.includes("app/api") || ptn.includes("src/app/api")) {
+      const dir1 = path.join(repoRoot, "app", "api");
+      const dir2 = path.join(repoRoot, "src", "app", "api");
+      if (fs.existsSync(dir1)) out.push(...findFilesFallback(dir1, /route\.(ts|js)$/));
+      if (fs.existsSync(dir2)) out.push(...findFilesFallback(dir2, /route\.(ts|js)$/));
+    }
+    if (ptn.includes("pages/api") || ptn.includes("src/pages/api")) {
+      const dir1 = path.join(repoRoot, "pages", "api");
+      const dir2 = path.join(repoRoot, "src", "pages", "api");
+      if (fs.existsSync(dir1)) out.push(...findFilesFallback(dir1, /\.(ts|js)$/, /\.d\.ts$/));
+      if (fs.existsSync(dir2)) out.push(...findFilesFallback(dir2, /\.(ts|js)$/, /\.d\.ts$/));
+    }
+  }
+  return Array.from(new Set(out));
+}
+
+// ============================================================================
+// NEXT.JS RESOLVER (AST)
+// ============================================================================
+
+function extractNextAppRouterMethodsAST(ast) {
+  const methods = [];
+  traverse(ast, {
+    ExportNamedDeclaration(p) {
+      const decl = p.node.declaration;
+
+      // export function GET() {}
+      if (t.isFunctionDeclaration(decl) && decl.id?.name) {
+        const n = decl.id.name.toUpperCase();
+        if (NEXT_HTTP_METHODS.has(n)) {
+          methods.push({ name: n, loc: decl.loc });
+        }
+      }
+
+      // export const GET = () => {}
+      if (t.isVariableDeclaration(decl)) {
+        for (const d of decl.declarations) {
+          if (!t.isIdentifier(d.id)) continue;
+          const n = d.id.name.toUpperCase();
+          if (NEXT_HTTP_METHODS.has(n)) {
+            methods.push({ name: n, loc: d.loc || decl.loc });
+          }
+        }
+      }
+    },
+  });
+  return methods;
+}
+
+function deriveNextAppRoutePath(fileRel) {
+  // matches: app/api/**/route.ts|js OR src/app/api/**/route.ts|js
+  const m = fileRel.match(/(?:^|\/)(?:src\/)?app\/api\/(.+)\/route\.(ts|js)$/);
+  if (!m) return null;
+  const sub = m[1];
+  return canonicalizePath("/api/" + sub);
+}
+
+function deriveNextPagesRoutePath(fileRel) {
+  // matches: pages/api/**.ts|js OR src/pages/api/**.ts|js
+  const m = fileRel.match(/(?:^|\/)(?:src\/)?pages\/api\/(.+)\.(ts|js)$/);
+  if (!m) return null;
+  let sub = m[1];
+  sub = sub.replace(/\/index$/, ""); // /foo/index -> /foo
+  return canonicalizePath("/api/" + sub);
+}
+
+async function resolveNextRoutes(repoRoot) {
+  const routes = [];
+
+  // App Router
+  const appFiles = await globFiles(repoRoot, [
+    "**/app/api/**/route.@(ts|js)",
+    "**/src/app/api/**/route.@(ts|js)",
+  ]);
+
+  for (const fileAbs of appFiles) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const routePath = deriveNextAppRoutePath(fileRel);
+    if (!routePath) continue;
+
+    const code = safeRead(fileAbs);
+    if (!code) continue;
+
+    let ast;
+    try { ast = parseFile(code); } catch { continue; }
+
+    const methods = extractNextAppRouterMethodsAST(ast);
+
+    if (methods.length === 0) {
+      routes.push({
+        method: "*",
+        path: routePath,
+        handler: fileRel,
+        framework: "next",
+        routerType: "app",
+        confidence: "low",
+        evidence: [createEvidence(fileRel, "1", "route file with no method exports", code.slice(0, 140))],
+      });
+      continue;
+    }
+
+    for (const m of methods) {
+      routes.push({
+        method: m.name,
+        path: routePath,
+        handler: fileRel,
+        framework: "next",
+        routerType: "app",
+        confidence: "high",
+        evidence: evidenceFromLoc({ fileAbs, fileRel, loc: m.loc, reason: `Next app router export ${m.name}` }),
+      });
+    }
+  }
+
+  // Pages Router
+  const pagesFiles = await globFiles(repoRoot, [
+    "**/pages/api/**/*.@(ts|js)",
+    "**/src/pages/api/**/*.@(ts|js)",
+  ]);
+
+  for (const fileAbs of pagesFiles) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    if (fileRel.endsWith(".d.ts")) continue;
+
+    const routePath = deriveNextPagesRoutePath(fileRel);
+    if (!routePath) continue;
+
+    const code = safeRead(fileAbs);
+    if (!code) continue;
+
+    const hasDefaultExport = /\bexport\s+default\b/.test(code);
+
+    routes.push({
+      method: "*",
+      path: routePath,
+      handler: fileRel,
+      framework: "next",
+      routerType: "pages",
+      confidence: hasDefaultExport ? "med" : "low",
+      evidence: [createEvidence(fileRel, "1", "Next pages API route", code.slice(0, 140))],
+    });
+  }
+
+  return routes;
+}
+
+// ============================================================================
+// FASTIFY RESOLVER (AST, follows register prefixes + relative plugin modules)
+// ============================================================================
+
+const FASTIFY_METHODS = new Set(["get","post","put","patch","delete","options","head","all"]);
+
+function existsFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function existsDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Find project root by walking up from a file until we find package.json
+ */
+function findProjectRoot(fromFileAbs) {
+  let dir = path.dirname(fromFileAbs);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    if (existsFile(path.join(dir, "package.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Load and cache tsconfig.json paths for a project
+ */
+const tsconfigCache = new Map();
+
+function loadTsConfigPaths(projectRoot) {
+  if (!projectRoot) return null;
+  if (tsconfigCache.has(projectRoot)) return tsconfigCache.get(projectRoot);
+
+  const tsconfigPath = path.join(projectRoot, "tsconfig.json");
+  if (!existsFile(tsconfigPath)) {
+    tsconfigCache.set(projectRoot, null);
+    return null;
+  }
+
+  try {
+    const raw = fs.readFileSync(tsconfigPath, "utf8");
+    // Remove comments (// and /* */) for JSON parsing
+    const cleaned = raw
+      .replace(/\/\/.*$/gm, "")
+      .replace(/\/\*[\s\S]*?\*\//g, "");
+    const tsconfig = JSON.parse(cleaned);
+
+    const paths = tsconfig?.compilerOptions?.paths || {};
+    const baseUrl = tsconfig?.compilerOptions?.baseUrl || ".";
+    const baseDir = path.resolve(projectRoot, baseUrl);
+
+    const result = { paths, baseDir, projectRoot };
+    tsconfigCache.set(projectRoot, result);
+    return result;
+  } catch {
+    tsconfigCache.set(projectRoot, null);
+    return null;
+  }
+}
+
+/**
+ * Resolve a module specifier using TypeScript path mappings
+ */
+function resolveWithTsConfigPaths(spec, tsConfig) {
+  if (!tsConfig || !tsConfig.paths) return null;
+
+  const { paths, baseDir } = tsConfig;
+
+  for (const [pattern, targets] of Object.entries(paths)) {
+    // Handle exact match: "@vibecheck/core" -> ["../../packages/core/dist"]
+    if (pattern === spec) {
+      for (const target of targets) {
+        const resolved = path.resolve(baseDir, target.replace(/\/\*$/, ""));
+        const candidates = [
+          resolved,
+          resolved + ".ts",
+          resolved + ".js",
+          path.join(resolved, "index.ts"),
+          path.join(resolved, "index.js"),
+        ];
+        for (const c of candidates) if (existsFile(c)) return c;
+      }
+    }
+
+    // Handle wildcard pattern: "@/*" -> ["./src/*"]
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      if (spec.startsWith(prefix + "/")) {
+        const rest = spec.slice(prefix.length + 1);
+        for (const target of targets) {
+          const targetBase = target.replace(/\/\*$/, "");
+          const resolved = path.resolve(baseDir, targetBase, rest);
+          const candidates = [
+            resolved,
+            resolved + ".ts",
+            resolved + ".js",
+            path.join(resolved, "index.ts"),
+            path.join(resolved, "index.js"),
+          ];
+          for (const c of candidates) if (existsFile(c)) return c;
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse package.json and find the main entrypoint
+ */
+function getPackageEntrypoint(pkgJsonPath) {
+  try {
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+    const pkgDir = path.dirname(pkgJsonPath);
+
+    // Priority: exports["."] > main > index.js
+    // Handle exports field (modern packages)
+    if (pkgJson.exports) {
+      const exp = pkgJson.exports;
+
+      // exports: "./lib/index.js" (string shorthand)
+      if (typeof exp === "string") {
+        const resolved = path.resolve(pkgDir, exp);
+        if (existsFile(resolved)) return resolved;
+      }
+
+      // exports: { ".": "./lib/index.js" } or { ".": { "require": "...", "import": "..." } }
+      if (typeof exp === "object" && exp["."]) {
+        const dotExport = exp["."];
+
+        if (typeof dotExport === "string") {
+          const resolved = path.resolve(pkgDir, dotExport);
+          if (existsFile(resolved)) return resolved;
+        }
+
+        // Conditional exports - prefer require for CommonJS, then import, then default
+        if (typeof dotExport === "object") {
+          const conditions = ["require", "node", "import", "default"];
+          for (const cond of conditions) {
+            if (dotExport[cond]) {
+              const val = dotExport[cond];
+              const target = typeof val === "string" ? val : val?.default;
+              if (target) {
+                const resolved = path.resolve(pkgDir, target);
+                if (existsFile(resolved)) return resolved;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Fallback to main field
+    if (pkgJson.main) {
+      const resolved = path.resolve(pkgDir, pkgJson.main);
+      if (existsFile(resolved)) return resolved;
+    }
+
+    // Final fallback: index.js
+    const indexJs = path.join(pkgDir, "index.js");
+    if (existsFile(indexJs)) return indexJs;
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a package specifier from node_modules
+ * Handles: "fastify", "@fastify/cors", "@vibecheck/core"
+ */
+function resolveFromNodeModules(spec, projectRoot) {
+  if (!projectRoot || !spec) return null;
+
+  // Don't resolve built-in Node.js modules
+  const builtins = new Set([
+    "fs", "path", "http", "https", "url", "crypto", "os", "util", "stream",
+    "events", "buffer", "querystring", "child_process", "cluster", "dgram",
+    "dns", "net", "readline", "tls", "tty", "zlib", "assert", "async_hooks",
+    "perf_hooks", "v8", "vm", "worker_threads", "module", "process"
+  ]);
+
+  const pkgName = spec.startsWith("@")
+    ? spec.split("/").slice(0, 2).join("/")  // @scope/name
+    : spec.split("/")[0];                     // name
+
+  if (builtins.has(pkgName)) return null;
+
+  // Walk up directory tree looking for node_modules
+  let searchDir = projectRoot;
+  const root = path.parse(searchDir).root;
+
+  while (searchDir !== root) {
+    const nodeModulesDir = path.join(searchDir, "node_modules");
+
+    if (existsDir(nodeModulesDir)) {
+      const pkgDir = path.join(nodeModulesDir, pkgName);
+
+      if (existsDir(pkgDir)) {
+        const pkgJsonPath = path.join(pkgDir, "package.json");
+
+        if (existsFile(pkgJsonPath)) {
+          // Check if spec has a subpath: "@fastify/cors/lib/foo"
+          const subpath = spec.slice(pkgName.length);
+
+          if (subpath && subpath !== "/") {
+            // Resolve subpath within the package
+            const subpathResolved = path.join(pkgDir, subpath);
+            const candidates = [
+              subpathResolved,
+              subpathResolved + ".js",
+              subpathResolved + ".ts",
+              path.join(subpathResolved, "index.js"),
+              path.join(subpathResolved, "index.ts"),
+            ];
+            for (const c of candidates) if (existsFile(c)) return c;
+          }
+
+          // Resolve main entrypoint
+          const entry = getPackageEntrypoint(pkgJsonPath);
+          if (entry) return entry;
+        }
+      }
+    }
+
+    const parent = path.dirname(searchDir);
+    if (parent === searchDir) break;
+    searchDir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Check if a package is a "non-route" Fastify plugin
+ * These plugins add functionality but don't define routes themselves
+ */
+function isNonRoutePlugin(spec) {
+  const nonRoutePlugins = new Set([
+    // @fastify/* scoped plugins
+    "@fastify/cors",
+    "@fastify/helmet",
+    "@fastify/compress",
+    "@fastify/cookie",
+    "@fastify/secure-session",
+    "@fastify/session",
+    "@fastify/rate-limit",
+    "@fastify/jwt",
+    "@fastify/auth",
+    "@fastify/bearer-auth",
+    "@fastify/basic-auth",
+    "@fastify/multipart",
+    "@fastify/formbody",
+    "@fastify/static",
+    "@fastify/view",
+    "@fastify/sensible",
+    "@fastify/env",
+    "@fastify/accepts",
+    "@fastify/caching",
+    "@fastify/etag",
+    "@fastify/circuit-breaker",
+    "@fastify/response-validation",
+    "@fastify/request-context",
+    "@fastify/under-pressure",
+    "@fastify/middie",
+    "@fastify/express",
+    "@fastify/http-proxy",
+    "@fastify/reply-from",
+    "@fastify/websocket",
+    "@fastify/type-provider-json-schema-to-ts",
+    "@fastify/type-provider-typebox",
+    "@fastify/type-provider-zod",
+    "@fastify/mongodb",
+    "@fastify/postgres",
+    "@fastify/mysql",
+    "@fastify/redis",
+    "@fastify/leveldb",
+    "@fastify/elasticsearch",
+    "@fastify/metrics",
+    "@fastify/request-id",
+    // Legacy fastify-* plugins
+    "fastify-plugin",
+    "fastify-cors",
+    "fastify-helmet",
+    "fastify-compress",
+    "fastify-cookie",
+    "fastify-session",
+    "fastify-rate-limit",
+    "fastify-jwt",
+    "fastify-auth",
+    "fastify-sensible",
+    "fastify-multipart",
+    "fastify-formbody",
+    "fastify-static",
+    "fastify-websocket",
+  ]);
+
+  const pkgName = spec.startsWith("@")
+    ? spec.split("/").slice(0, 2).join("/")
+    : spec.split("/")[0];
+
+  return nonRoutePlugins.has(pkgName);
+}
+
+/**
+ * Check if this is @fastify/autoload which needs special directory handling
+ */
+function isAutoloadPlugin(spec) {
+  return spec === "@fastify/autoload" || spec === "fastify-autoload";
+}
+
+function resolveRelativeModule(fromFileAbs, spec) {
+  if (!spec || (!spec.startsWith("./") && !spec.startsWith("../"))) return null;
+  const base = path.resolve(path.dirname(fromFileAbs), spec);
+  const candidates = [
+    base,
+    base + ".ts",
+    base + ".js",
+    path.join(base, "index.ts"),
+    path.join(base, "index.js"),
+  ];
+  for (const c of candidates) if (existsFile(c)) return c;
+  return null;
+}
+
+/**
+ * Resolve any module specifier (relative, absolute, package, or TS paths)
+ * Returns: { resolved: string | null, isNonRoute: boolean, reason: string }
+ */
+function resolveModuleSpec(fromFileAbs, spec) {
+  if (!spec) return { resolved: null, isNonRoute: false, reason: "empty spec" };
+
+  // 1. Relative imports
+  if (spec.startsWith("./") || spec.startsWith("../")) {
+    const resolved = resolveRelativeModule(fromFileAbs, spec);
+    return {
+      resolved,
+      isNonRoute: false,
+      reason: resolved ? "relative import" : "relative module not found"
+    };
+  }
+
+  // 2. Check if it's a non-route plugin (skip scanning)
+  if (isNonRoutePlugin(spec)) {
+    return {
+      resolved: null,
+      isNonRoute: true,
+      reason: `non-route plugin: ${spec}`
+    };
+  }
+
+  const projectRoot = findProjectRoot(fromFileAbs);
+
+  // 3. TypeScript path mappings
+  if (projectRoot) {
+    const tsConfig = loadTsConfigPaths(projectRoot);
+    if (tsConfig) {
+      const resolved = resolveWithTsConfigPaths(spec, tsConfig);
+      if (resolved) {
+        return { resolved, isNonRoute: false, reason: "tsconfig paths" };
+      }
+    }
+  }
+
+  // 4. Node modules resolution
+  if (projectRoot) {
+    const resolved = resolveFromNodeModules(spec, projectRoot);
+    if (resolved) {
+      return { resolved, isNonRoute: false, reason: "node_modules" };
+    }
+  }
+
+  return {
+    resolved: null,
+    isNonRoute: false,
+    reason: `unresolved package: ${spec}`
+  };
+}
+
+function extractStringLiteral(node) {
+  return t.isStringLiteral(node) ? node.value : null;
+}
+
+function extractPrefixFromOpts(node) {
+  if (!t.isObjectExpression(node)) return null;
+  for (const p of node.properties) {
+    if (!t.isObjectProperty(p)) continue;
+    const key =
+      t.isIdentifier(p.key) ? p.key.name :
+      t.isStringLiteral(p.key) ? p.key.value :
+      null;
+    if (key === "prefix" && t.isStringLiteral(p.value)) return p.value.value;
+  }
+  return null;
+}
+
+function extractRouteObject(objExpr) {
+  let url = null;
+  let methods = [];
+  let hasHandler = false;
+
+  for (const p of objExpr.properties) {
+    if (!t.isObjectProperty(p)) continue;
+
+    const key =
+      t.isIdentifier(p.key) ? p.key.name :
+      t.isStringLiteral(p.key) ? p.key.value :
+      null;
+    if (!key) continue;
+
+    if (key === "url" && t.isStringLiteral(p.value)) url = p.value.value;
+
+    if (key === "method") {
+      if (t.isStringLiteral(p.value)) methods = [p.value.value];
+      if (t.isArrayExpression(p.value)) {
+        methods = p.value.elements.filter(e => t.isStringLiteral(e)).map(e => e.value);
+      }
+    }
+
+    if (key === "handler") hasHandler = true;
+  }
+
+  return { url, methods, hasHandler };
+}
+
+function detectFastifyEntry(repoRoot) {
+  const candidates = [
+    "src/server.ts","src/server.js",
+    "server.ts","server.js",
+    "src/index.ts","src/index.js",
+    "index.ts","index.js",
+    "apps/api/src/server.ts",
+    "apps/api/src/index.ts",
+  ];
+  for (const rel of candidates) {
+    const abs = path.join(repoRoot, rel);
+    if (existsFile(abs)) return rel;
+  }
+  return null;
+}
+
+function resolveFastifyRoutesFromEntry(repoRoot, entryAbs) {
+  const seen = new Set();
+  const routes = [];
+  const gaps = [];
+
+  function scanFile(fileAbs, prefix) {
+    if (!fileAbs || seen.has(fileAbs)) return;
+    seen.add(fileAbs);
+
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+    if (!code) return;
+
+    let ast;
+    try { ast = parseFile(code); } catch { return; }
+
+    // fastify instance identifiers
+    const fastifyNames = new Set(["fastify", "app", "server"]);
+
+    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;
+        if (t.isCallExpression(init) && t.isIdentifier(init.callee)) {
+          const cal = init.callee.name;
+          if (cal === "Fastify" || cal === "fastify") fastifyNames.add(id);
+        }
+      },
+    });
+
+    function resolveImportSpecForLocal(localName) {
+      let spec = null;
+
+      traverse(ast, {
+        ImportDeclaration(ip) {
+          for (const s of ip.node.specifiers) {
+            if (
+              (t.isImportDefaultSpecifier(s) || t.isImportSpecifier(s)) &&
+              s.local.name === localName
+            ) {
+              spec = ip.node.source.value;
+            }
+          }
+        },
+        VariableDeclarator(vp) {
+          if (!t.isIdentifier(vp.node.id) || vp.node.id.name !== localName) return;
+          const init = vp.node.init;
+          if (!t.isCallExpression(init)) return;
+          if (!t.isIdentifier(init.callee) || init.callee.name !== "require") return;
+          const a0 = init.arguments[0];
+          if (t.isStringLiteral(a0)) spec = a0.value;
+        },
+      });
+
+      return spec;
+    }
+
+    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 prop = callee.property.name;
+
+        if (!fastifyNames.has(obj)) return;
+
+        // fastify.get('/x', ...)
+        if (FASTIFY_METHODS.has(prop)) {
+          const routeStr = extractStringLiteral(p.node.arguments[0]);
+          if (!routeStr) return;
+
+          routes.push({
+            method: canonicalizeMethod(prop),
+            path: joinPrefix(prefix, routeStr),
+            handler: fileRel,
+            framework: "fastify",
+            confidence: "med",
+            evidence: evidenceFromLoc({
+              fileAbs,
+              fileRel,
+              loc: p.node.loc,
+              reason: `Fastify ${prop.toUpperCase()}("${routeStr}")`,
+            }),
+          });
+          return;
+        }
+
+        // fastify.route({ method, url, handler })
+        if (prop === "route") {
+          const arg0 = p.node.arguments[0];
+          if (!t.isObjectExpression(arg0)) return;
+
+          const r = extractRouteObject(arg0);
+          if (!r.url) return;
+
+          const fullPath = joinPrefix(prefix, r.url);
+          const ms = (r.methods.length ? r.methods : ["*"]).map(canonicalizeMethod);
+
+          for (const m of ms) {
+            routes.push({
+              method: m,
+              path: fullPath,
+              handler: fileRel,
+              framework: "fastify",
+              confidence: r.hasHandler ? "med" : "low",
+              evidence: evidenceFromLoc({
+                fileAbs,
+                fileRel,
+                loc: p.node.loc,
+                reason: `Fastify.route({ url: "${r.url}" })`,
+              }),
+            });
+          }
+          return;
+        }
+
+        // fastify.register(plugin, { prefix })
+        if (prop === "register") {
+          const pluginArg = p.node.arguments[0];
+          const optsArg = p.node.arguments[1];
+          const childPrefixRaw = extractPrefixFromOpts(optsArg);
+          const childPrefix = childPrefixRaw ? joinPrefix(prefix, childPrefixRaw) : prefix;
+
+          // inline plugin: fastify.register((f, opts) => { f.get(...) }, { prefix })
+          if (t.isFunctionExpression(pluginArg) || t.isArrowFunctionExpression(pluginArg)) {
+            const param0 = pluginArg.params[0];
+            const innerName = t.isIdentifier(param0) ? param0.name : "fastify";
+
+            traverse(
+              pluginArg.body,
+              {
+                CallExpression(pp) {
+                  const c = pp.node.callee;
+                  if (!t.isMemberExpression(c)) return;
+                  if (!t.isIdentifier(c.object) || !t.isIdentifier(c.property)) return;
+                  if (c.object.name !== innerName) return;
+
+                  const pr = c.property.name;
+
+                  if (FASTIFY_METHODS.has(pr)) {
+                    const rs = extractStringLiteral(pp.node.arguments[0]);
+                    if (!rs) return;
+
+                    routes.push({
+                      method: canonicalizeMethod(pr),
+                      path: joinPrefix(childPrefix, rs),
+                      handler: fileRel,
+                      framework: "fastify",
+                      confidence: "med",
+                      evidence: evidenceFromLoc({
+                        fileAbs,
+                        fileRel,
+                        loc: pp.node.loc,
+                        reason: `Fastify plugin ${pr.toUpperCase()}("${rs}") prefix="${childPrefixRaw || ""}"`,
+                      }),
+                    });
+                  }
+
+                  if (pr === "route") {
+                    const a0 = pp.node.arguments[0];
+                    if (!t.isObjectExpression(a0)) return;
+                    const r = extractRouteObject(a0);
+                    if (!r.url) return;
+
+                    const fullPath = joinPrefix(childPrefix, r.url);
+                    const ms = (r.methods.length ? r.methods : ["*"]).map(canonicalizeMethod);
+
+                    for (const m of ms) {
+                      routes.push({
+                        method: m,
+                        path: fullPath,
+                        handler: fileRel,
+                        framework: "fastify",
+                        confidence: r.hasHandler ? "med" : "low",
+                        evidence: evidenceFromLoc({
+                          fileAbs,
+                          fileRel,
+                          loc: pp.node.loc,
+                          reason: `Fastify plugin route("${r.url}") prefix="${childPrefixRaw || ""}"`,
+                        }),
+                      });
+                    }
+                  }
+                },
+              },
+              p.scope,
+              p
+            );
+
+            return;
+          }
+
+          // imported plugin identifier: resolve module (relative, package, or TS paths)
+          if (t.isIdentifier(pluginArg)) {
+            const localName = pluginArg.name;
+            const spec = resolveImportSpecForLocal(localName);
+
+            if (!spec) {
+              gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, name: localName });
+              return;
+            }
+
+            // Handle @fastify/autoload: scan the specified directory
+            if (isAutoloadPlugin(spec)) {
+              const autoloadDir = extractAutoloadDir(optsArg, fileAbs);
+              if (autoloadDir && existsDir(autoloadDir)) {
+                scanAutoloadDir(autoloadDir, childPrefix);
+              }
+              return;
+            }
+
+            const { resolved, isNonRoute, reason } = resolveModuleSpec(fileAbs, spec);
+
+            // Skip non-route plugins silently (they don't add routes)
+            if (isNonRoute) {
+              return;
+            }
+
+            if (!resolved) {
+              gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, spec, reason });
+              return;
+            }
+
+            scanFile(resolved, childPrefix);
+          }
+
+          // Direct require/import: fastify.register(require('./routes'))
+          if (t.isCallExpression(pluginArg)) {
+            const callee = pluginArg.callee;
+            if (t.isIdentifier(callee) && callee.name === "require") {
+              const reqArg = pluginArg.arguments[0];
+              if (t.isStringLiteral(reqArg)) {
+                const spec = reqArg.value;
+
+                // Handle @fastify/autoload via require
+                if (isAutoloadPlugin(spec)) {
+                  const autoloadDir = extractAutoloadDir(optsArg, fileAbs);
+                  if (autoloadDir && existsDir(autoloadDir)) {
+                    scanAutoloadDir(autoloadDir, childPrefix);
+                  }
+                  return;
+                }
+
+                const { resolved, isNonRoute, reason } = resolveModuleSpec(fileAbs, spec);
+
+                if (isNonRoute) return;
+
+                if (!resolved) {
+                  gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, spec, reason });
+                  return;
+                }
+
+                scanFile(resolved, childPrefix);
+              }
+            }
+          }
+        }
+      },
+    });
+  }
+
+  /**
+   * Extract the 'dir' option from autoload config
+   * Handles: { dir: path.join(__dirname, 'routes') } or { dir: './routes' }
+   */
+  function extractAutoloadDir(optsNode, fromFileAbs) {
+    if (!t.isObjectExpression(optsNode)) return null;
+
+    for (const prop of optsNode.properties) {
+      if (!t.isObjectProperty(prop)) continue;
+
+      const key = t.isIdentifier(prop.key) ? prop.key.name :
+                  t.isStringLiteral(prop.key) ? prop.key.value : null;
+
+      if (key !== "dir") continue;
+
+      // Simple string: { dir: './routes' }
+      if (t.isStringLiteral(prop.value)) {
+        return path.resolve(path.dirname(fromFileAbs), prop.value.value);
+      }
+
+      // path.join(__dirname, 'routes')
+      if (t.isCallExpression(prop.value)) {
+        const callee = prop.value.callee;
+        if (t.isMemberExpression(callee) &&
+            t.isIdentifier(callee.object) && callee.object.name === "path" &&
+            t.isIdentifier(callee.property) && callee.property.name === "join") {
+          const args = prop.value.arguments;
+          // path.join(__dirname, 'subdir')
+          if (args.length >= 2 && t.isIdentifier(args[0]) && args[0].name === "__dirname") {
+            const parts = args.slice(1)
+              .filter(a => t.isStringLiteral(a))
+              .map(a => a.value);
+            if (parts.length > 0) {
+              return path.resolve(path.dirname(fromFileAbs), ...parts);
+            }
+          }
+        }
+      }
+
+      // Template literal or identifier - can't resolve statically
+      return null;
+    }
+
+    return null;
+  }
+
+  /**
+   * Scan a directory for route files (used by @fastify/autoload)
+   */
+  function scanAutoloadDir(dirAbs, prefix) {
+    if (!existsDir(dirAbs)) return;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const ent of entries) {
+      const fullPath = path.join(dirAbs, ent.name);
+
+      if (ent.isDirectory()) {
+        // Subdirectory: recurse with directory name as prefix segment
+        // @fastify/autoload uses directory names as route prefixes
+        const subPrefix = joinPrefix(prefix, "/" + ent.name);
+        scanAutoloadDir(fullPath, subPrefix);
+      } else if (ent.isFile() && /\.(ts|js)$/.test(ent.name) && !ent.name.endsWith(".d.ts")) {
+        // Skip index files for prefix (they define routes at current prefix level)
+        const isIndex = /^index\.(ts|js)$/.test(ent.name);
+        const filePrefix = isIndex ? prefix : joinPrefix(prefix, "/" + ent.name.replace(/\.(ts|js)$/, ""));
+
+        scanFile(fullPath, filePrefix);
+      }
+    }
+  }
+
+  scanFile(entryAbs, "/");
+  return { routes, gaps };
+}
+
+async function resolveFastifyRoutes(repoRoot, entryRel = null) {
+  const entry = entryRel || detectFastifyEntry(repoRoot);
+  if (!entry) return { routes: [], gaps: [{ kind: "fastify_entry_missing", file: null }] };
+
+  const entryAbs = path.isAbsolute(entry) ? entry : path.join(repoRoot, entry);
+  if (!existsFile(entryAbs)) {
+    return { routes: [], gaps: [{ kind: "fastify_entry_missing", file: entry }] };
+  }
+
+  return resolveFastifyRoutesFromEntry(repoRoot, entryAbs);
+}
+
+// ============================================================================
+// ROUTE INDEX
+// ============================================================================
+
+class RouteIndex {
+  constructor() {
+    this.routes = [];
+    this.byMethod = new Map();
+    this.byPath = new Map();
+    this.parameterized = [];
+    this.gaps = [];
+  }
+
+  async build(repoRoot, options = {}) {
+    const nextRoutes = await resolveNextRoutes(repoRoot);
+    this.routes.push(...nextRoutes);
+
+    const { routes: fastifyRoutes, gaps } = await resolveFastifyRoutes(repoRoot, options.fastifyEntry || null);
+    this.routes.push(...fastifyRoutes);
+    this.gaps.push(...(gaps || []));
+
+    for (const r of this.routes) {
+      const m = canonicalizeMethod(r.method);
+      const p = canonicalizePath(r.path);
+
+      r.method = m;
+      r.path = p;
+
+      if (!this.byMethod.has(m)) this.byMethod.set(m, []);
+      this.byMethod.get(m).push(r);
+
+      if (!this.byPath.has(p)) this.byPath.set(p, []);
+      this.byPath.get(p).push(r);
+
+      if (isParameterizedPath(p)) this.parameterized.push(r);
+    }
+
+    return this;
+  }
+
+  findRoutes(method, p) {
+    const m = canonicalizeMethod(method);
+    const cp = canonicalizePath(p);
+
+    const matches = [];
+
+    // Exact path match
+    for (const r of this.byPath.get(cp) || []) {
+      if (matchMethod(r.method, m)) matches.push(r);
+    }
+
+    // Wildcard method match on exact path
+    for (const r of this.byMethod.get("*") || []) {
+      if (r.path === cp && !matches.includes(r)) matches.push(r);
+    }
+
+    // Parameterized route match
+    for (const r of this.parameterized) {
+      if (r.path === cp) continue;
+      if (matchPath(r.path, cp) && matchMethod(r.method, m)) {
+        if (!matches.includes(r)) matches.push(r);
+      }
+    }
+
+    return matches;
+  }
+
+  findClosestRoutes(p, limit = 3) {
+    const cp = canonicalizePath(p);
+    const pathParts = cp.split("/").filter(Boolean);
+
+    const scored = this.routes.map((r) => {
+      const routeParts = r.path.split("/").filter(Boolean);
+      let score = 0;
+
+      for (let i = 0; i < Math.min(pathParts.length, routeParts.length); i++) {
+        if (pathParts[i] === routeParts[i]) score += 1;
+        else if (routeParts[i].startsWith(":")) score += 0.8;
+        else if (routeParts[i].startsWith("*")) { score += 0.6; break; }
+        else break;
+      }
+
+      if (pathParts.length === routeParts.length) score += 0.25;
+      if (isParameterizedPath(r.path)) score += 0.05;
+
+      return { route: r, score };
+    });
+
+    return scored
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(0, limit))
+      .map((s) => s.route);
+  }
+
+  getRouteMap() {
+    return {
+      server: this.routes,
+      clientRefs: [],
+      gaps: this.gaps,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+}
+
+// ============================================================================
+// VALIDATE CLAIM
+// ============================================================================
+
+async function validateRouteExists(claim, repoRoot, routeIndex) {
+  const index = routeIndex || new RouteIndex();
+  if (!routeIndex) await index.build(repoRoot);
+
+  const method = claim?.method || "*";
+  const routePath = claim?.path;
+
+  if (!routePath) {
+    return {
+      result: "unknown",
+      confidence: "low",
+      evidence: [],
+      nextSteps: ["Claim missing path"],
+    };
+  }
+
+  const matches = index.findRoutes(method, routePath);
+
+  if (matches.length > 0) {
+    const best = matches[0];
+    return {
+      result: "true",
+      confidence: best.confidence || "med",
+      evidence: best.evidence || [],
+      matchedRoute: best,
+    };
+  }
+
+  const closest = index.findClosestRoutes(routePath, 3);
+  const hasGaps = (index.gaps || []).length > 0;
+
+  if (hasGaps) {
+    return {
+      result: "unknown",
+      confidence: "low",
+      evidence: [],
+      closestRoutes: closest,
+      gaps: index.gaps,
+      nextSteps: ["Some routes may not be detected due to unresolved plugins/imports."],
+    };
+  }
+
+  return {
+    result: "false",
+    confidence: "high",
+    evidence: [],
+    closestRoutes: closest,
+    nextSteps: closest.length
+      ? [`Did you mean: ${closest.map(r => `${r.method} ${r.path}`).join(", ")}?`]
+      : ["No similar routes found"],
+  };
+}
+
+module.exports = {
+  canonicalizePath,
+  canonicalizeMethod,
+  resolveNextRoutes,
+  resolveFastifyRoutes,
+  detectFastifyEntry,
+  RouteIndex,
+  validateRouteExists,
+};