@vibecheckai/cli 3.2.0 → 3.2.2

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

@@ -1,322 +1,1155 @@
 /**
- * Route Truth v1 - JavaScript Runtime
- * 
- * Generates a normalized route map with evidence from:
- * - Next.js (App Router + Pages Router)
- * - Fastify (shorthand + .route() + register prefixes)
- * 
- * Then implements validate_claim(route_exists) on top of it.
+ * 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');
+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
+// CANONICALIZATION + MATCHING
 // ============================================================================
 
-/**
- * Canonicalize a path to standard format.
- */
 function canonicalizePath(p) {
-  let s = p.trim();
-  if (!s.startsWith('/')) s = '/' + s;
-  s = s.replace(/\/+/g, '/');
-  
-  // Convert 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(/\/$/, '');
+  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 = m.toUpperCase();
-  if (u === 'ALL' || u === 'ANY') return '*';
-  return u;
+  const u = String(m || "").toUpperCase();
+  if (u === "ALL" || u === "ANY" || u === "*" ) return "*";
+  return u || "*";
 }
 
 function joinPrefix(prefix, p) {
-  const cleanPrefix = prefix.replace(/\/$/, '');
-  const cleanPath = p.startsWith('/') ? p : '/' + p;
-  return canonicalizePath(cleanPrefix + cleanPath);
+  const a = canonicalizePath(prefix || "/");
+  const b = canonicalizePath(p || "/");
+  if (a === "/") return b;
+  if (b === "/") return a;
+  return canonicalizePath(a + "/" + b);
 }
 
-function isParameterizedPath(path) {
-  return path.includes(':') || path.includes('*');
+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 patternParts = pattern.split('/');
-  const concreteParts = concrete.split('/');
-  
+  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 < patternParts.length && cIdx < concreteParts.length) {
-    const pPart = patternParts[pIdx];
-    const cPart = concreteParts[cIdx];
-    
-    if (pPart.startsWith('*')) return true;
-    if (pPart.startsWith(':')) { pIdx++; cIdx++; continue; }
-    if (pPart !== cPart) return false;
+
+  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++;
   }
-  
-  return pIdx === patternParts.length && cIdx === concreteParts.length;
+
+  // 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) {
-  if (pattern === '*') return true;
-  return pattern === concrete;
+  const p = canonicalizeMethod(pattern);
+  const c = canonicalizeMethod(concrete);
+  if (p === "*") return true;
+  return p === c;
 }
 
 // ============================================================================
-// NEXT.JS RESOLVER
+// COMMON HELPERS
 // ============================================================================
 
-const NEXT_HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
+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')}`,
+    id: `ev_${String(evidenceCounter).padStart(4, "0")}`,
     file,
     lines,
-    snippetHash: `sha256:${crypto.createHash('sha256').update(snippet || '').digest('hex').slice(0, 16)}`,
+    snippetHash: `sha256:${sha256Short(snippet || "")}`,
     reason,
   };
 }
 
-function findFiles(dir, include, exclude) {
-  const files = [];
-  
+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) {
-    try {
-      const entries = fs.readdirSync(d, { withFileTypes: true });
-      for (const entry of entries) {
-        const fullPath = path.join(d, entry.name);
-        if (entry.isDirectory()) {
-          if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
-            walk(fullPath);
-          }
-        } else if (entry.isFile()) {
-          if (include.test(entry.name) && (!exclude || !exclude.test(entry.name))) {
-            files.push(fullPath);
-          }
-        }
+    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);
       }
-    } catch {}
+    }
   }
-  
-  walk(dir);
-  return files;
+  walk(dirAbs);
+  return out;
 }
 
-function extractAppRouterMethods(code) {
-  const methods = [];
-  const lines = code.split('\n');
-  
-  const patterns = [
-    /export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s*\(/,
-    /export\s+const\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s*=/,
-  ];
-  
-  for (let i = 0; i < lines.length; i++) {
-    for (const pattern of patterns) {
-      const match = lines[i].match(pattern);
-      if (match && NEXT_HTTP_METHODS.includes(match[1].toUpperCase())) {
-        methods.push({
-          name: match[1].toUpperCase(),
-          line: i + 1,
-          snippet: lines[i].trim(),
-        });
-      }
+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: app/api/**/route.ts|js
-  const appDirs = ['app', 'src/app'];
-  for (const appDir of appDirs) {
-    const apiDir = path.join(repoRoot, appDir, 'api');
-    if (!fs.existsSync(apiDir)) continue;
-    
-    const routeFiles = findFiles(apiDir, /route\.(ts|js)$/);
-    
-    for (const file of routeFiles) {
-      const relPath = path.relative(repoRoot, file).replace(/\\/g, '/');
-      const apiIdx = relPath.indexOf('/api/');
-      const sub = relPath.slice(apiIdx + '/api/'.length).replace(/\/route\.(ts|js)$/, '');
-      const routePath = canonicalizePath('/api/' + sub);
-      
-      const code = fs.readFileSync(file, 'utf8');
-      const methods = extractAppRouterMethods(code);
-      
-      if (methods.length === 0) {
-        routes.push({
-          method: '*',
-          path: routePath,
-          handler: relPath,
-          framework: 'next',
-          routerType: 'app',
-          confidence: 'low',
-          evidence: [createEvidence(relPath, '1', 'route file with no exports', code.slice(0, 100))],
-        });
-        continue;
-      }
-      
-      for (const m of methods) {
-        routes.push({
-          method: m.name,
-          path: routePath,
-          handler: `${relPath}:${m.line}`,
-          framework: 'next',
-          routerType: 'app',
-          confidence: 'high',
-          evidence: [createEvidence(relPath, String(m.line), `export ${m.name}`, m.snippet)],
-        });
-      }
+
+  // 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;
     }
-  }
-  
-  // Pages Router: pages/api/**/*.ts|js
-  const pagesDirs = ['pages', 'src/pages'];
-  for (const pagesDir of pagesDirs) {
-    const apiDir = path.join(repoRoot, pagesDir, 'api');
-    if (!fs.existsSync(apiDir)) continue;
-    
-    const apiFiles = findFiles(apiDir, /\.(ts|js)$/, /\.d\.ts$/);
-    
-    for (const file of apiFiles) {
-      const relPath = path.relative(repoRoot, file).replace(/\\/g, '/');
-      const apiIdx = relPath.indexOf('/api/');
-      const sub = relPath
-        .slice(apiIdx + '/api/'.length)
-        .replace(/\.(ts|js)$/, '')
-        .replace(/\/index$/, '');
-      
-      const routePath = canonicalizePath('/api/' + sub);
-      const code = fs.readFileSync(file, 'utf8');
-      const hasDefaultExport = /export\s+default/.test(code);
-      
+
+    for (const m of methods) {
       routes.push({
-        method: '*',
+        method: m.name,
         path: routePath,
-        handler: relPath,
-        framework: 'next',
-        routerType: 'pages',
-        confidence: hasDefaultExport ? 'med' : 'low',
-        evidence: [createEvidence(relPath, '1', 'Pages API route', code.slice(0, 100))],
+        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 (Simplified - regex based)
+// FASTIFY RESOLVER (AST, follows register prefixes + relative plugin modules)
 // ============================================================================
 
-async function resolveFastifyRoutes(repoRoot) {
-  const routes = [];
-  const gaps = [];
-  
-  const entryPoints = [
-    'src/server.ts', 'src/server.js', 'src/index.ts', 'src/index.js',
-    'server.ts', 'server.js', 'apps/api/src/server.ts', 'apps/api/src/index.ts',
-  ];
-  
-  const fastifyMethods = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'all'];
-  
-  // Find source files
-  const srcDirs = ['src', 'apps/api/src', 'server'];
-  const files = [];
-  
-  for (const srcDir of srcDirs) {
-    const fullDir = path.join(repoRoot, srcDir);
-    if (fs.existsSync(fullDir)) {
-      files.push(...findFiles(fullDir, /\.(ts|js)$/, /\.d\.ts$/));
+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;
+        }
+      }
     }
   }
-  
-  // Patterns to detect routes
-  const patterns = [
-    // fastify.get('/path', handler)
-    /(?:fastify|app|server)\.(get|post|put|patch|delete|options|head|all)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-    // router.get('/path', handler)
-    /router\.(get|post|put|patch|delete|options|head|all)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-    // .route({ method: 'GET', url: '/path' })
-    /\.route\s*\(\s*\{[^}]*method:\s*['"`]([^'"`]+)['"`][^}]*url:\s*['"`]([^'"`]+)['"`]/gi,
-    /\.route\s*\(\s*\{[^}]*url:\s*['"`]([^'"`]+)['"`][^}]*method:\s*['"`]([^'"`]+)['"`]/gi,
+
+  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"),
   ];
-  
-  // Track prefixes from register calls
-  const prefixMap = new Map(); // file → prefix
-  
-  for (const file of files) {
-    try {
-      const code = fs.readFileSync(file, 'utf8');
-      const relPath = path.relative(repoRoot, file).replace(/\\/g, '/');
-      const lines = code.split('\n');
-      
-      // Detect prefix from register calls
-      const registerPattern = /\.register\s*\([^,]+,\s*\{[^}]*prefix:\s*['"`]([^'"`]+)['"`]/g;
-      let match;
-      while ((match = registerPattern.exec(code)) !== null) {
-        prefixMap.set(relPath, match[1]);
+  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);
       }
-      
-      // Extract routes
-      for (const pattern of patterns) {
-        pattern.lastIndex = 0;
-        while ((match = pattern.exec(code)) !== null) {
-          let method, routePath;
-          
-          if (match[0].includes('.route')) {
-            // Handle .route() pattern - order varies
-            if (match[0].indexOf('method') < match[0].indexOf('url')) {
-              method = match[1];
-              routePath = match[2];
-            } else {
-              routePath = match[1];
-              method = match[2];
+    }
+
+    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;
             }
-          } else {
-            method = match[1];
-            routePath = match[2];
           }
-          
-          const prefix = prefixMap.get(relPath) || '';
-          const fullPath = joinPrefix(prefix, routePath);
-          const lineNum = code.substring(0, match.index).split('\n').length;
-          const snippet = lines[lineNum - 1] || '';
-          
+        },
+        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(method),
-            path: fullPath,
-            handler: `${relPath}:${lineNum}`,
-            framework: 'fastify',
-            confidence: 'med',
-            evidence: [createEvidence(relPath, String(lineNum), `fastify.${method}('${routePath}')`, snippet)],
+            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);
+            }
+          }
         }
       }
-    } catch {}
+
+      // 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
 // ============================================================================
@@ -329,87 +1162,88 @@ class RouteIndex {
     this.parameterized = [];
     this.gaps = [];
   }
-  
-  async build(repoRoot) {
-    // Resolve Next.js routes
+
+  async build(repoRoot, options = {}) {
     const nextRoutes = await resolveNextRoutes(repoRoot);
     this.routes.push(...nextRoutes);
-    
-    // Resolve Fastify routes
-    const { routes: fastifyRoutes, gaps } = await resolveFastifyRoutes(repoRoot);
+
+    const { routes: fastifyRoutes, gaps } = await resolveFastifyRoutes(repoRoot, options.fastifyEntry || null);
     this.routes.push(...fastifyRoutes);
-    this.gaps.push(...gaps);
-    
-    // Build indexes
-    for (const route of this.routes) {
-      const methodKey = route.method;
-      if (!this.byMethod.has(methodKey)) this.byMethod.set(methodKey, []);
-      this.byMethod.get(methodKey).push(route);
-      
-      const pathKey = route.path;
-      if (!this.byPath.has(pathKey)) this.byPath.set(pathKey, []);
-      this.byPath.get(pathKey).push(route);
-      
-      if (isParameterizedPath(route.path)) {
-        this.parameterized.push(route);
-      }
+    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, path) {
-    const canonicalMethod = canonicalizeMethod(method);
-    const canonicalPath = canonicalizePath(path);
+
+  findRoutes(method, p) {
+    const m = canonicalizeMethod(method);
+    const cp = canonicalizePath(p);
+
     const matches = [];
-    
+
     // Exact path match
-    const pathMatches = this.byPath.get(canonicalPath) || [];
-    for (const route of pathMatches) {
-      if (matchMethod(route.method, canonicalMethod)) {
-        matches.push(route);
-      }
+    for (const r of this.byPath.get(cp) || []) {
+      if (matchMethod(r.method, m)) matches.push(r);
     }
-    
-    // Wildcard method match
-    const wildcardMethods = this.byMethod.get('*') || [];
-    for (const route of wildcardMethods) {
-      if (route.path === canonicalPath && !matches.includes(route)) {
-        matches.push(route);
-      }
+
+    // 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 route of this.parameterized) {
-      if (matchPath(route.path, canonicalPath) && matchMethod(route.method, canonicalMethod)) {
-        if (!matches.includes(route)) matches.push(route);
+    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(path, limit = 3) {
-    const canonicalPath = canonicalizePath(path);
-    const pathParts = canonicalPath.split('/').filter(Boolean);
-    
-    const scored = this.routes.map(route => {
-      const routeParts = route.path.split('/').filter(Boolean);
+
+  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] || routeParts[i].startsWith(':')) {
-          score++;
-        } else break;
+        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.5;
-      return { route, score };
+
+      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, limit).map(s => s.route);
+
+    return scored
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(0, limit))
+      .map((s) => s.route);
   }
-  
+
   getRouteMap() {
     return {
       server: this.routes,
@@ -427,43 +1261,53 @@ class RouteIndex {
 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;
-  
+
+  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: matches[0].confidence,
-      evidence: matches[0].evidence,
-      matchedRoute: matches[0],
+      result: "true",
+      confidence: best.confidence || "med",
+      evidence: best.evidence || [],
+      matchedRoute: best,
     };
   }
-  
-  const closest = index.findClosestRoutes(routePath);
-  const hasGaps = index.gaps.length > 0;
-  
+
+  const closest = index.findClosestRoutes(routePath, 3);
+  const hasGaps = (index.gaps || []).length > 0;
+
   if (hasGaps) {
     return {
-      result: 'unknown',
-      confidence: 'low',
+      result: "unknown",
+      confidence: "low",
       evidence: [],
       closestRoutes: closest,
       gaps: index.gaps,
-      nextSteps: ['Some routes may not be detected due to unresolved plugins'],
+      nextSteps: ["Some routes may not be detected due to unresolved plugins/imports."],
     };
   }
-  
+
   return {
-    result: 'false',
-    confidence: 'high',
+    result: "false",
+    confidence: "high",
     evidence: [],
     closestRoutes: closest,
-    nextSteps: closest.length > 0
-      ? [`Did you mean: ${closest.map(r => `${r.method} ${r.path}`).join(', ')}?`]
-      : ['No similar routes found'],
+    nextSteps: closest.length
+      ? [`Did you mean: ${closest.map(r => `${r.method} ${r.path}`).join(", ")}?`]
+      : ["No similar routes found"],
   };
 }
 
@@ -472,6 +1316,7 @@ module.exports = {
   canonicalizeMethod,
   resolveNextRoutes,
   resolveFastifyRoutes,
+  detectFastifyEntry,
   RouteIndex,
   validateRouteExists,
 };