@vibecheckai/cli 3.5.1 → 3.5.2

package/bin/runners/lib/truth.js

@@ -18,6 +18,19 @@ const { buildEnforcementTruth } = require("./enforcement");
 // Multi-framework route detection v2
 const { resolveAllRoutes, detectFrameworks } = require("./route-detection");
 
+// ---------- constants ----------
+const IGNORE_GLOBS = [
+  "**/node_modules/**",
+  "**/.next/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.turbo/**",
+  "**/.git/**",
+  "**/.vibecheck/**",
+];
+
+const CODE_FILE_GLOBS = ["**/*.{ts,tsx,js,jsx}"];
+
 // ---------- helpers ----------
 function sha256(text) {
   return "sha256:" + crypto.createHash("sha256").update(text).digest("hex");
@@ -29,15 +42,43 @@ function canonicalizeMethod(m) {
   return u;
 }
 
+function stripQueryHash(s) {
+  const v = String(s || "");
+  const q = v.indexOf("?");
+  const h = v.indexOf("#");
+  const cut = (q === -1 ? h : (h === -1 ? q : Math.min(q, h)));
+  return cut === -1 ? v : v.slice(0, cut);
+}
+
+/**
+ * Canonical path rules:
+ * - ensure leading slash
+ * - collapse multiple slashes
+ * - strip query/hash
+ * - normalize Next dynamic segments:
+ *   [[...slug]] -> *slug?
+ *   [...slug]   -> *slug
+ *   [id]        -> :id
+ */
 function canonicalizePath(p) {
-  let s = String(p || "").trim();
+  let s = stripQueryHash(String(p || "").trim());
+
+  // If someone passed a full URL, only keep pathname-like portion if possible.
+  // (We still require local routes to start with "/" for client refs.)
+  const protoIdx = s.indexOf("://");
+  if (protoIdx !== -1) {
+    // attempt to strip scheme+host
+    const slashAfterHost = s.indexOf("/", protoIdx + 3);
+    s = slashAfterHost === -1 ? "/" : s.slice(slashAfterHost);
+  }
+
   if (!s.startsWith("/")) s = "/" + s;
   s = s.replace(/\/+/g, "/");
 
-  // Next dynamic segments
+  // Next dynamic segments (filesystem style)
   s = s.replace(/\[\[\.{3}([^\]]+)\]\]/g, "*$1?"); // [[...slug]] -> *slug?
-  s = s.replace(/\[\.{3}([^\]]+)\]/g, "*$1");     // [...slug]  -> *slug
-  s = s.replace(/\[([^\]]+)\]/g, ":$1");          // [id]       -> :id
+  s = s.replace(/\[\.{3}([^\]]+)\]/g, "*$1"); // [...slug]  -> *slug
+  s = s.replace(/\[([^\]]+)\]/g, ":$1"); // [id]       -> :id
 
   if (s.length > 1) s = s.replace(/\/$/, "");
   return s;
@@ -51,12 +92,46 @@ function joinPaths(prefix, p) {
   return canonicalizePath(a + "/" + b);
 }
 
-function parseFile(code) {
-  return parser.parse(code, { sourceType: "unambiguous", plugins: ["typescript", "jsx"] });
+function parseFile(code, fileAbsForErrors) {
+  // Be permissive: production repos contain decorators, top-level await, etc.
+  return parser.parse(code, {
+    sourceType: "unambiguous",
+    errorRecovery: true,
+    allowImportExportEverywhere: true,
+    plugins: [
+      "typescript",
+      "jsx",
+      "dynamicImport",
+      "importMeta",
+      "topLevelAwait",
+      "classProperties",
+      "classPrivateProperties",
+      "classPrivateMethods",
+      "optionalChaining",
+      "nullishCoalescingOperator",
+      "decorators-legacy",
+    ],
+    sourceFilename: fileAbsForErrors || undefined,
+  });
 }
 
+// File cache for performance (avoids reading the same file multiple times)
+const _FILE_CACHE = new Map();
+
 function safeRead(fileAbs) {
-  return fs.readFileSync(fileAbs, "utf8");
+  if (_FILE_CACHE.has(fileAbs)) return _FILE_CACHE.get(fileAbs);
+  try {
+    const content = fs.readFileSync(fileAbs, "utf8");
+    _FILE_CACHE.set(fileAbs, content);
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+// Clear cache to free memory after a scan (important for long-running processes)
+function clearCache() {
+  _FILE_CACHE.clear();
 }
 
 function ensureDir(p) {
@@ -65,68 +140,154 @@ function ensureDir(p) {
 
 function evidenceFromLoc({ fileAbs, fileRel, loc, reason }) {
   if (!loc) return null;
-  const lines = fs.readFileSync(fileAbs, "utf8").split(/\r?\n/);
+  const code = safeRead(fileAbs);
+  if (!code) return null;
+
+  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 {
     id: `ev_${crypto.randomBytes(4).toString("hex")}`,
     file: fileRel,
     lines: `${start}-${end}`,
     snippetHash: sha256(snippet),
-    reason
+    reason,
   };
 }
 
+function normalizeRel(repoRoot, fileAbs) {
+  return path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+}
+
+function scoreConfidence(c) {
+  if (c === "high") return 3;
+  if (c === "med") return 2;
+  if (c === "low") return 1;
+  return 0;
+}
+
+function isRouteGroupSegment(seg) {
+  // Next route group: (group)
+  return seg.startsWith("(") && seg.endsWith(")");
+}
+
+function isParallelSegment(seg) {
+  // Next parallel routes: @slot
+  return seg.startsWith("@");
+}
+
 // ---------- Next: app router API ----------
-const HTTP_EXPORTS = new Set(["GET","POST","PUT","PATCH","DELETE","OPTIONS","HEAD"]);
+const HTTP_EXPORTS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+
+function nextAppApiPathFromRel(fileRel) {
+  const idx = fileRel.indexOf("app/api/");
+  if (idx === -1) return null;
+
+  let sub = fileRel.slice(idx + "app/api/".length);
+
+  // route.ts / route.js / route.tsx / route.jsx
+  sub = sub.replace(/\/route\.(ts|tsx|js|jsx)$/, "");
 
-async function resolveNextAppApiRoutes(repoRoot) {
-  const files = await fg(["**/app/api/**/route.@(ts|js)"], {
+  // remove route groups + parallel segments from the filesystem path
+  const parts = sub.split("/").filter(Boolean).filter((seg) => !isRouteGroupSegment(seg) && !isParallelSegment(seg));
+  sub = parts.join("/");
+
+  return canonicalizePath("/api/" + sub);
+}
+
+async function resolveNextAppApiRoutes(repoRoot, stats) {
+  const files = await fg(["**/app/api/**/route.@(ts|tsx|js|jsx)"], {
     cwd: repoRoot,
     absolute: true,
-    ignore: ["**/node_modules/**","**/.next/**","**/dist/**","**/build/**"]
+    ignore: IGNORE_GLOBS,
   });
 
   const out = [];
 
   for (const fileAbs of files) {
-    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
-    const idx = fileRel.indexOf("app/api/");
-    const sub = fileRel.slice(idx + "app/api/".length).replace(/\/route\.(ts|js)$/, "");
-    const routePath = canonicalizePath("/api/" + sub);
+    const fileRel = normalizeRel(repoRoot, fileAbs);
+    const routePath = nextAppApiPathFromRel(fileRel);
+    if (!routePath) continue;
 
     const code = safeRead(fileAbs);
+    if (!code) continue;
+
     let ast;
-    try { ast = parseFile(code); } catch { continue; }
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      stats.parseErrors++;
+      continue;
+    }
 
     const methods = [];
-    traverse(ast, {
-      ExportNamedDeclaration(p) {
-        const decl = p.node.declaration;
-        if (t.isFunctionDeclaration(decl) && decl.id?.name) {
-          const n = decl.id.name.toUpperCase();
-          if (HTTP_EXPORTS.has(n)) methods.push({ method: n, loc: decl.loc });
-        }
-      }
-    });
+
+    try {
+      traverse(ast, {
+        // export async function GET() {}
+        ExportNamedDeclaration(p) {
+          const decl = p.node.declaration;
+
+          if (t.isFunctionDeclaration(decl) && decl.id?.name) {
+            const n = decl.id.name.toUpperCase();
+            if (HTTP_EXPORTS.has(n)) methods.push({ method: n, loc: decl.loc, why: "export function" });
+          }
+
+          // export const GET = async () => {}
+          if (t.isVariableDeclaration(decl)) {
+            for (const d of decl.declarations) {
+              if (!t.isVariableDeclarator(d)) continue;
+              if (!t.isIdentifier(d.id)) continue;
+              const n = d.id.name.toUpperCase();
+              if (HTTP_EXPORTS.has(n)) methods.push({ method: n, loc: d.loc || decl.loc, why: "export const" });
+            }
+          }
+
+          // export { GET } from "./handler"
+          for (const s of p.node.specifiers || []) {
+            if (!t.isExportSpecifier(s)) continue;
+            if (!t.isIdentifier(s.exported)) continue;
+            const n = s.exported.name.toUpperCase();
+            if (HTTP_EXPORTS.has(n)) methods.push({ method: n, loc: s.loc || p.node.loc, why: "export re-export" });
+          }
+        },
+      });
+    } catch {
+      // Babel traverse can fail on some edge-case files; skip them
+      stats.parseErrors++;
+      continue;
+    }
 
     if (methods.length === 0) {
-      out.push({ method: "*", path: routePath, handler: fileRel, confidence: "low", evidence: [] });
+      // Still include route.ts, but with "*" and low confidence to avoid missing-route spam.
+      out.push({
+        method: "*",
+        path: routePath,
+        handler: fileRel,
+        confidence: "low",
+        framework: "next",
+        evidence: [],
+      });
       continue;
     }
 
     for (const m of methods) {
       const ev = evidenceFromLoc({
-        fileAbs, fileRel, loc: m.loc,
-        reason: `Next app router export ${m.method}` 
+        fileAbs,
+        fileRel,
+        loc: m.loc,
+        reason: `Next app router ${m.method} (${m.why})`,
       });
+
       out.push({
         method: m.method,
         path: routePath,
         handler: fileRel,
-        confidence: "high",
-        evidence: ev ? [ev] : []
+        confidence: m.why === "export re-export" ? "med" : "high",
+        framework: "next",
+        evidence: ev ? [ev] : [],
       });
     }
   }
@@ -135,51 +296,133 @@ async function resolveNextAppApiRoutes(repoRoot) {
 }
 
 // ---------- Next: pages router API ----------
-async function resolveNextPagesApiRoutes(repoRoot) {
-  const files = await fg(["**/pages/api/**/*.@(ts|js)"], {
+function nextPagesApiPathFromRel(fileRel) {
+  const idx = fileRel.indexOf("pages/api/");
+  if (idx === -1) return null;
+
+  let sub = fileRel.slice(idx + "pages/api/".length);
+  sub = sub.replace(/\.(ts|tsx|js|jsx)$/, "");
+
+  // pages/api/foo/index.ts -> /api/foo
+  if (sub === "index") sub = "";
+  sub = sub.replace(/\/index$/, "");
+
+  return canonicalizePath("/api/" + sub);
+}
+
+async function resolveNextPagesApiRoutes(repoRoot, stats) {
+  const files = await fg(["**/pages/api/**/*.@(ts|tsx|js|jsx)"], {
     cwd: repoRoot,
     absolute: true,
-    ignore: ["**/node_modules/**","**/.next/**","**/dist/**","**/build/**"]
+    ignore: IGNORE_GLOBS,
   });
 
   const out = [];
+
   for (const fileAbs of files) {
-    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
-    const idx = fileRel.indexOf("pages/api/");
-    const sub = fileRel.slice(idx + "pages/api/".length).replace(/\.(ts|js)$/, "");
-    const routePath = canonicalizePath("/api/" + sub);
+    const fileRel = normalizeRel(repoRoot, fileAbs);
+
+    // Skip Next.js special files that aren't API routes (_app, _document, _utils, etc.)
+    if (fileRel.includes("/_") && !fileRel.includes("/_next")) continue;
+
+    const routePath = nextPagesApiPathFromRel(fileRel);
+    if (!routePath) continue;
+
+    const code = safeRead(fileAbs);
+    if (!code) continue;
+
+    // Parse to verify it's actually a route (has export default)
+    let ast;
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      stats.parseErrors++;
+      continue;
+    }
+
+    // Check for 'export default' (Required for Pages Router API routes)
+    // Files without default export are helper files (db.ts, types.ts, utils.ts)
+    let hasDefaultExport = false;
+    try {
+      traverse(ast, {
+        ExportDefaultDeclaration(p) {
+          hasDefaultExport = true;
+          p.stop(); // Found it, stop traversing
+        },
+      });
+    } catch {
+      // Traverse failed, skip this file
+      stats.parseErrors++;
+      continue;
+    }
+
+    if (!hasDefaultExport) continue; // It's a helper file, not an API route
 
     out.push({
-      method: "*",
+      method: "*", // Pages router handles all methods in one function
       path: routePath,
       handler: fileRel,
       confidence: "med",
-      evidence: []
+      framework: "next",
+      evidence: [],
     });
   }
+
   return out;
 }
 
 // ---------- minimal relative module resolver ----------
 function exists(p) {
-  try { return fs.statSync(p).isFile(); } catch { return false; }
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
 }
+
 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 + ".tsx",
     base + ".js",
+    base + ".jsx",
     path.join(base, "index.ts"),
-    path.join(base, "index.js")
+    path.join(base, "index.tsx"),
+    path.join(base, "index.js"),
+    path.join(base, "index.jsx"),
   ];
+
   for (const c of candidates) if (exists(c)) return c;
   return null;
 }
 
+function extractRequireOrImportSpec(node) {
+  // require("./x")
+  if (t.isCallExpression(node) && t.isIdentifier(node.callee, { name: "require" })) {
+    const a0 = node.arguments && node.arguments[0];
+    if (t.isStringLiteral(a0)) return a0.value;
+  }
+
+  // import("./x")
+  if (t.isCallExpression(node) && node.callee && node.callee.type === "Import") {
+    const a0 = node.arguments && node.arguments[0];
+    if (t.isStringLiteral(a0)) return a0.value;
+  }
+
+  // await import("./x")
+  if (t.isAwaitExpression(node)) {
+    return extractRequireOrImportSpec(node.argument);
+  }
+
+  return null;
+}
+
 // ---------- Fastify route extraction ----------
-const FASTIFY_METHODS = new Set(["get","post","put","patch","delete","options","head","all"]);
+const FASTIFY_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "all"]);
 
 function isFastifyMethod(name) {
   return FASTIFY_METHODS.has(name);
@@ -222,18 +465,18 @@ function extractRouteObject(objExpr) {
     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);
+        methods = p.value.elements.filter((e) => t.isStringLiteral(e)).map((e) => e.value);
       }
     }
 
     if (key === "handler") hasHandler = true;
-    if (["preHandler","onRequest","preValidation","preSerialization"].includes(key)) hooks.push(key);
+    if (["preHandler", "onRequest", "preValidation", "preSerialization"].includes(key)) hooks.push(key);
   }
 
   return { url, methods, hasHandler, hooks };
 }
 
-function resolveFastifyRoutes(repoRoot, entryAbs) {
+function resolveFastifyRoutes(repoRoot, entryAbs, stats) {
   const seen = new Set();
   const routes = [];
   const gaps = [];
@@ -242,217 +485,521 @@ function resolveFastifyRoutes(repoRoot, entryAbs) {
     if (!fileAbs || seen.has(fileAbs)) return;
     seen.add(fileAbs);
 
-    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const fileRel = normalizeRel(repoRoot, fileAbs);
     const code = safeRead(fileAbs);
+    if (!code) return;
 
     let ast;
-    try { ast = parseFile(code); } catch { return; }
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      stats.parseErrors++;
+      return;
+    }
 
     // best-effort: fastify instance identifiers
     const fastifyNames = new Set(["fastify"]);
 
-    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);
+    // Static string + local-plugin harvesting (cheap, big impact on false positives)
+    const _rawConstInits = new Map();   // name -> init node (evaluated lazily)
+    const _constStrings = new Map();    // name -> resolved string
+    const _localPlugins = new Map();    // name -> Function node
+
+    function evalStaticString(node, depth = 0) {
+      if (!node || depth > 6) return null;
+
+      if (t.isStringLiteral(node)) return node.value;
+
+      if (t.isTemplateLiteral(node) && node.expressions.length === 0) {
+        return node.quasis.map((q) => q.value.cooked || "").join("");
+      }
+
+      if (t.isIdentifier(node)) {
+        const name = node.name;
+        if (_constStrings.has(name)) return _constStrings.get(name);
+        const init = _rawConstInits.get(name);
+        if (!init) return null;
+        const v = evalStaticString(init, depth + 1);
+        if (typeof v === "string") {
+          // cap to avoid pathological blowups
+          if (v.length <= 4096) _constStrings.set(name, v);
+          return v;
         }
+        return null;
       }
-    });
 
-    // helper: resolve imports for register(pluginIdent,...)
-    function resolveImportSpecForLocal(localName) {
-      let spec = null;
+      if (t.isBinaryExpression(node, { operator: "+" })) {
+        const l = evalStaticString(node.left, depth + 1);
+        const r = evalStaticString(node.right, depth + 1);
+        if (typeof l !== "string" || typeof r !== "string") return null;
+        const out = l + r;
+        return out.length <= 4096 ? out : 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;
-            }
+      return null;
+    }
+
+    function extractPrefixFromOptsV3(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") continue;
+        return evalStaticString(p.value);
+      }
+      return null;
+    }
+
+    function extractRouteObjectV3(objExpr) {
+      let url = null;
+      let methods = [];
+      let hasHandler = false;
+      const hooks = [];
+
+      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") {
+          const u = evalStaticString(p.value);
+          if (typeof u === "string") url = u;
+        }
+
+        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);
           }
-        },
-        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;
+        if (key === "handler") hasHandler = true;
+        if (["preHandler", "onRequest", "preValidation", "preSerialization"].includes(key)) hooks.push(key);
+      }
+
+      return { url, methods, hasHandler, hooks };
     }
 
-    traverse(ast, {
-      CallExpression(p) {
-        const callee = p.node.callee;
-        if (!t.isMemberExpression(callee)) return;
-        if (!t.isIdentifier(callee.object) || !t.isIdentifier(callee.property)) return;
+    function unwrapPluginArg(node) {
+      // fastify-plugin wrappers are common: fastify.register(fp(plugin))
+      // We unwrap 1 layer, best-effort.
+      if (!node) return node;
+      if (!t.isCallExpression(node)) return node;
 
-        const obj = callee.object.name;
-        const prop = callee.property.name;
+      const calleeName =
+        t.isIdentifier(node.callee) ? node.callee.name :
+        t.isMemberExpression(node.callee) && t.isIdentifier(node.callee.property) ? node.callee.property.name :
+        null;
 
-        if (!fastifyNames.has(obj)) return;
+      if (!calleeName) return node;
+      if (!/^(fp|fastifyPlugin|plugin|fastifyPluginify)$/i.test(calleeName)) return node;
 
-        // fastify.get('/x', ...)
-        if (isFastifyMethod(prop)) {
-          const routeStr = extractStringLiteral(p.node.arguments[0]);
-          if (!routeStr) return;
+      const a0 = node.arguments && node.arguments[0];
+      return a0 || node;
+    }
 
-          const fullPath = joinPaths(prefix, routeStr);
-          const method = canonicalizeMethod(prop);
+    try {
+      traverse(ast, {
+        FunctionDeclaration(p) {
+          if (t.isIdentifier(p.node.id)) {
+            _localPlugins.set(p.node.id.name, p.node);
+          }
+        },
+        VariableDeclarator(p) {
+          if (!t.isIdentifier(p.node.id)) return;
+          const id = p.node.id.name;
+          const init = p.node.init;
+          if (!init) return;
 
-          const ev = evidenceFromLoc({
-            fileAbs, fileRel, loc: p.node.loc,
-            reason: `Fastify ${prop.toUpperCase()}("${routeStr}")` 
-          });
+          _rawConstInits.set(id, init);
 
-          routes.push({
-            method,
-            path: fullPath,
-            handler: fileRel,
-            confidence: "med",
-            evidence: ev ? [ev] : []
-          });
-          return;
-        }
+          // local plugin: const routes = async (fastify) => { ... }
+          if (t.isFunctionExpression(init) || t.isArrowFunctionExpression(init)) {
+            _localPlugins.set(id, init);
+          }
 
-        // fastify.route({ method, url, handler })
-        if (prop === "route") {
-          const arg0 = p.node.arguments[0];
-          if (!t.isObjectExpression(arg0)) return;
+          // const app = Fastify()
+          if (t.isCallExpression(init) && t.isIdentifier(init.callee)) {
+            const cal = init.callee.name;
+            if (cal === "Fastify" || cal === "fastify") fastifyNames.add(id);
+          }
+
+          // const app = require("fastify")()
+          if (t.isCallExpression(init) && t.isCallExpression(init.callee)) {
+            const inner = init.callee;
+            if (t.isIdentifier(inner.callee, { name: "require" }) && t.isStringLiteral(inner.arguments?.[0], { value: "fastify" })) {
+              fastifyNames.add(id);
+            }
+          }
+        },
+      });
+    } catch {
+      // Babel traverse can fail on some edge-case files; skip this step
+    }
 
-          const r = extractRouteObject(arg0);
-          if (!r.url) return;
+    // helper: resolve imports for register(pluginIdent,...)
+    function resolveImportSpecForLocal(localName) {
+      let spec = null;
 
-          const fullPath = joinPaths(prefix, r.url);
-          const ms = (r.methods.length ? r.methods : ["*"]).map(canonicalizeMethod);
+      try {
+        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;
+          },
+        });
+      } catch {
+        // Babel traverse can fail; ignore
+      }
 
-          const ev = evidenceFromLoc({
-            fileAbs, fileRel, loc: p.node.loc,
-            reason: `Fastify.route({ url: "${r.url}" })` 
-          });
+      return spec;
+    }
+
+    try {
+      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 (isFastifyMethod(prop)) {
+            const routeStr = evalStaticString(p.node.arguments[0]);
+            if (!routeStr) return;
+
+            const fullPath = joinPaths(prefix, routeStr);
+            const method = canonicalizeMethod(prop);
+
+            const ev = evidenceFromLoc({
+              fileAbs,
+              fileRel,
+              loc: p.node.loc,
+              reason: `Fastify ${prop.toUpperCase()}("${routeStr}")`,
+            });
 
-          for (const m of ms) {
             routes.push({
-              method: m,
+              method,
               path: fullPath,
               handler: fileRel,
-              hooks: r.hooks,
-              confidence: r.hasHandler ? "med" : "low",
-              evidence: ev ? [ev] : []
+              confidence: "med",
+              framework: "fastify",
+              evidence: ev ? [ev] : [],
             });
+            return;
           }
-          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 ? joinPaths(prefix, childPrefixRaw) : prefix;
-
-          // inline plugin
-          if (t.isFunctionExpression(pluginArg) || t.isArrowFunctionExpression(pluginArg)) {
-            const param0 = pluginArg.params[0];
-            const innerName = t.isIdentifier(param0) ? param0.name : "fastify";
-
-            // traverse just the plugin body (best effort)
-            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 (isFastifyMethod(pr)) {
-                  const rs = extractStringLiteral(pp.node.arguments[0]);
-                  if (!rs) return;
-                  const fullPath = joinPaths(childPrefix, rs);
-                  const method = canonicalizeMethod(pr);
-
-                  const ev = evidenceFromLoc({
-                    fileAbs, fileRel, loc: pp.node.loc,
-                    reason: `Fastify plugin ${pr.toUpperCase()}("${rs}") prefix="${childPrefixRaw || ""}"` 
-                  });
-
-                  routes.push({ method, path: fullPath, handler: fileRel, confidence: "med", evidence: ev ? [ev] : [] });
-                }
+          // fastify.route({ method, url, handler })
+          if (prop === "route") {
+            const arg0 = p.node.arguments[0];
+            if (!t.isObjectExpression(arg0)) return;
 
-                if (pr === "route") {
-                  const a0 = pp.node.arguments[0];
-                  if (!t.isObjectExpression(a0)) return;
-                  const r = extractRouteObject(a0);
-                  if (!r.url) return;
-                  const fullPath = joinPaths(childPrefix, r.url);
-                  const ms = (r.methods.length ? r.methods : ["*"]).map(canonicalizeMethod);
+            const r = extractRouteObjectV3(arg0);
+            if (!r.url) return;
 
-                  const ev = evidenceFromLoc({
-                    fileAbs, fileRel, loc: pp.node.loc,
-                    reason: `Fastify plugin route("${r.url}") prefix="${childPrefixRaw || ""}"` 
-                  });
+            const fullPath = joinPaths(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, confidence: "med", evidence: ev ? [ev] : [] });
-                }
-              }
-            }, p.scope, p);
+            const ev = evidenceFromLoc({
+              fileAbs,
+              fileRel,
+              loc: p.node.loc,
+              reason: `Fastify.route({ url: "${r.url}" })`,
+            });
 
+            for (const m of ms) {
+              routes.push({
+                method: m,
+                path: fullPath,
+                handler: fileRel,
+                hooks: r.hooks,
+                confidence: r.hasHandler ? "med" : "low",
+                framework: "fastify",
+                evidence: ev ? [ev] : [],
+              });
+            }
             return;
           }
 
-          // imported plugin identifier
-          if (t.isIdentifier(pluginArg)) {
-            const localName = pluginArg.name;
-            const spec = resolveImportSpecForLocal(localName);
+          // fastify.register(plugin, { prefix })
+          if (prop === "register") {
+            const pluginArgRaw = unwrapPluginArg(p.node.arguments[0]);
+            const optsArg = p.node.arguments[1];
+
+            const childPrefixRaw = extractPrefixFromOptsV3(optsArg);
+            const childPrefix = childPrefixRaw ? joinPaths(prefix, childPrefixRaw) : prefix;
+
+            // inline plugin OR local plugin identifier (common in real Fastify codebases)
+            let pluginFn = null;
+            const localIdentName = t.isIdentifier(pluginArgRaw) ? pluginArgRaw.name : null;
+            if (t.isFunctionExpression(pluginArgRaw) || t.isArrowFunctionExpression(pluginArgRaw)) pluginFn = pluginArgRaw;
+            if (!pluginFn && localIdentName) pluginFn = _localPlugins.get(localIdentName) || null;
+
+            if (pluginFn) {
+              const param0 = pluginFn.params && pluginFn.params[0];
+              const innerName = t.isIdentifier(param0) ? param0.name : "fastify";
+              const bodyNode = pluginFn.body;
+              if (!t.isBlockStatement(bodyNode)) {
+                // We only handle block bodies. Expression-bodied arrows are rare for route plugins.
+                if (localIdentName) return;
+              }
+
+              // traverse just the plugin body (best effort)
+              try {
+                traverse(
+                  bodyNode,
+                  {
+                    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 (isFastifyMethod(pr)) {
+                        const rs = evalStaticString(pp.node.arguments[0]);
+                        if (!rs) return;
+
+                        const fullPath = joinPaths(childPrefix, rs);
+                        const method = canonicalizeMethod(pr);
+
+                        const ev = evidenceFromLoc({
+                          fileAbs,
+                          fileRel,
+                          loc: pp.node.loc,
+                          reason: `Fastify plugin ${pr.toUpperCase()}("${rs}") prefix="${childPrefixRaw || ""}"`,
+                        });
+
+                        routes.push({
+                          method,
+                          path: fullPath,
+                          handler: fileRel,
+                          confidence: "med",
+                          framework: "fastify",
+                          evidence: ev ? [ev] : [],
+                        });
+                      }
+
+                      if (pr === "route") {
+                        const a0 = pp.node.arguments[0];
+                        if (!t.isObjectExpression(a0)) return;
+
+                        const r = extractRouteObjectV3(a0);
+                        if (!r.url) return;
+
+                        const fullPath = joinPaths(childPrefix, r.url);
+                        const ms = (r.methods.length ? r.methods : ["*"]).map(canonicalizeMethod);
+
+                        const ev = evidenceFromLoc({
+                          fileAbs,
+                          fileRel,
+                          loc: pp.node.loc,
+                          reason: `Fastify plugin route("${r.url}") prefix="${childPrefixRaw || ""}"`,
+                        });
+
+                        for (const m of ms) {
+                          routes.push({
+                            method: m,
+                            path: fullPath,
+                            handler: fileRel,
+                            confidence: "med",
+                            framework: "fastify",
+                            evidence: ev ? [ev] : [],
+                          });
+                        }
+                      }
+                    },
+                  },
+                  p.scope,
+                  p
+                );
+              } catch {
+                // Inner traverse can fail; skip this plugin body
+              }
 
-            if (!spec) {
-              gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, name: localName });
+              // If this was a local plugin identifier, we've already extracted its routes.
+              if (localIdentName) return;
               return;
             }
 
-            const resolved = resolveRelativeModule(fileAbs, spec);
-            if (!resolved) {
-              gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, spec });
+            // Resolve dynamic require/import spec directly (fastify.register(require("./x")) / import("./x"))
+            const dynSpec = extractRequireOrImportSpec(pluginArgRaw);
+            if (dynSpec) {
+              const resolved = resolveRelativeModule(fileAbs, dynSpec);
+              if (!resolved) {
+                gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, spec: dynSpec });
+                return;
+              }
+              scanFile(resolved, childPrefix);
+              return;
+            }
+
+            // imported plugin identifier
+            if (t.isIdentifier(pluginArgRaw)) {
+              const localName = pluginArgRaw.name;
+              const spec = resolveImportSpecForLocal(localName);
+
+              if (!spec) {
+                gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, name: localName });
+                return;
+              }
+
+              const resolved = resolveRelativeModule(fileAbs, spec);
+              if (!resolved) {
+                gaps.push({ kind: "fastify_plugin_unresolved", file: fileRel, spec });
+                return;
+              }
+
+              scanFile(resolved, childPrefix);
               return;
             }
 
-            scanFile(resolved, childPrefix);
+            // Anything else: unknown plugin shape. Mark a gap so analyzers can be lenient.
+            gaps.push({
+              kind: "fastify_plugin_unresolved",
+              file: fileRel,
+              note: "register() plugin not statically resolvable",
+            });
           }
-        }
-      }
-    });
+        },
+      });
+    } catch {
+      // Babel traverse can fail on some edge-case files; skip
+      stats.parseErrors++;
+    }
   }
 
   scanFile(entryAbs, "/");
   return { routes, gaps };
 }
 
-// ---------- client refs (fetch + axios string literal only) ----------
+// ---------- client refs (fetch + axios + template literals best-effort) ----------
 function isAxiosMember(node) {
-  return t.isMemberExpression(node) &&
+  return (
+    t.isMemberExpression(node) &&
     t.isIdentifier(node.object) &&
     t.isIdentifier(node.property) &&
-    ["get","post","put","patch","delete"].includes(node.property.name);
+    ["get", "post", "put", "patch", "delete"].includes(node.property.name)
+  );
+}
+
+function isAxiosCallee(node) {
+  return t.isIdentifier(node, { name: "axios" }) || isAxiosMember(node);
+}
+
+function extractUrlLike(node) {
+  // "literal"
+  if (t.isStringLiteral(node)) return { url: node.value, confidence: "high", note: "string" };
+
+  // `literal`
+  if (t.isTemplateLiteral(node) && node.expressions.length === 0) {
+    return { url: node.quasis.map((q) => q.value.cooked || "").join(""), confidence: "high", note: "template_static" };
+  }
+
+  // `/api/x/${id}` -> "/api/x/:id" (med confidence)
+  if (t.isTemplateLiteral(node) && node.quasis.length >= 1) {
+    const start = node.quasis[0]?.value?.cooked || "";
+    if (!start.startsWith("/")) return null;
+
+    let built = "";
+    for (let i = 0; i < node.quasis.length; i++) {
+      built += node.quasis[i].value.cooked || "";
+      if (i < node.expressions.length) {
+        const expr = node.expressions[i];
+        if (t.isIdentifier(expr)) built += `:${expr.name}`;
+        else built += "*";
+      }
+    }
+    return { url: built, confidence: "med", note: "template_dynamic" };
+  }
+
+  // "/api/x" + "/y" or "/api/x" + id (low confidence)
+  if (t.isBinaryExpression(node, { operator: "+" })) {
+    if (t.isStringLiteral(node.left) && node.left.value.startsWith("/")) {
+      const left = node.left.value;
+      let right = "";
+      if (t.isStringLiteral(node.right)) right = node.right.value;
+      else if (t.isIdentifier(node.right)) right = `:${node.right.name}`;
+      else right = "*";
+      return { url: left + right, confidence: "low", note: "concat" };
+    }
+  }
+
+  return null;
+}
+
+function extractFetchMethodFromOptions(node) {
+  if (!t.isObjectExpression(node)) return "*";
+  for (const prop of node.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 === "method" && t.isStringLiteral(prop.value)) return canonicalizeMethod(prop.value.value);
+  }
+  return "*";
 }
 
-async function resolveClientRouteRefs(repoRoot) {
-  const files = await fg(["**/*.{ts,tsx,js,jsx}"], {
+function extractAxiosConfig(node) {
+  // axios({ url: "/api/x", method: "post" })
+  if (!t.isObjectExpression(node)) return null;
+
+  let urlNode = null;
+  let methodNode = null;
+
+  for (const prop of node.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) continue;
+
+    if (key === "url") urlNode = prop.value;
+    if (key === "method") methodNode = prop.value;
+  }
+
+  const urlInfo = urlNode ? extractUrlLike(urlNode) : null;
+  if (!urlInfo) return null;
+
+  const method =
+    methodNode && t.isStringLiteral(methodNode)
+      ? canonicalizeMethod(methodNode.value)
+      : "*";
+
+  return { method, urlInfo };
+}
+
+async function resolveClientRouteRefs(repoRoot, stats) {
+  const files = await fg(CODE_FILE_GLOBS, {
     cwd: repoRoot,
     absolute: true,
     ignore: [
-      "**/node_modules/**",
-      "**/.next/**",
-      "**/dist/**",
-      "**/build/**",
+      ...IGNORE_GLOBS,
       "**/test/**",
       "**/tests/**",
       "**/__tests__/**",
@@ -462,141 +1009,372 @@ async function resolveClientRouteRefs(repoRoot) {
       "**/jest.config.*",
       "**/*.mock.*",
       "**/mocks/**",
-      "**/fixtures/**"
-    ]
+      "**/fixtures/**",
+    ],
   });
 
   const out = [];
 
   for (const fileAbs of files) {
-    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const fileRel = normalizeRel(repoRoot, fileAbs);
     const code = safeRead(fileAbs);
+    if (!code) continue;
 
     let ast;
-    try { ast = parseFile(code); } catch { continue; }
-
-    traverse(ast, {
-      CallExpression(p) {
-        const callee = p.node.callee;
-
-        // fetch("/api/x", { method: "POST" })
-        if (t.isIdentifier(callee) && callee.name === "fetch") {
-          const a0 = p.node.arguments[0];
-          if (!t.isStringLiteral(a0)) return;
-
-          const url = a0.value;
-          if (!url.startsWith("/")) return;
-
-          let method = "*";
-          const a1 = p.node.arguments[1];
-          if (t.isObjectExpression(a1)) {
-            for (const prop of a1.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 === "method" && t.isStringLiteral(prop.value)) {
-                method = canonicalizeMethod(prop.value.value);
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      stats.parseErrors++;
+      continue;
+    }
+
+    try {
+      traverse(ast, {
+        CallExpression(p) {
+          const callee = p.node.callee;
+
+          // fetch(url, opts)
+          if (t.isIdentifier(callee, { name: "fetch" })) {
+            const a0 = p.node.arguments[0];
+            const a1 = p.node.arguments[1];
+
+            const urlInfo = extractUrlLike(a0);
+            if (!urlInfo) return;
+
+            const url = urlInfo.url;
+            if (!url.startsWith("/")) return;
+
+            const method = extractFetchMethodFromOptions(a1);
+
+            const ev = evidenceFromLoc({
+              fileAbs,
+              fileRel,
+              loc: p.node.loc,
+              reason: `Client fetch(${urlInfo.note}) "${stripQueryHash(url)}"`,
+            });
+
+            out.push({
+              method,
+              path: canonicalizePath(url),
+              source: fileRel,
+              confidence: urlInfo.confidence,
+              kind: "fetch",
+              evidence: ev ? [ev] : [],
+            });
+            return;
+          }
+
+          // axios.get("/api/x") etc
+          if (isAxiosMember(callee)) {
+            const verb = callee.property.name.toUpperCase();
+            const a0 = p.node.arguments[0];
+
+            const urlInfo = extractUrlLike(a0);
+            if (!urlInfo) return;
+
+            const url = urlInfo.url;
+            if (!url.startsWith("/")) return;
+
+            const ev = evidenceFromLoc({
+              fileAbs,
+              fileRel,
+              loc: p.node.loc,
+              reason: `Client axios.${verb.toLowerCase()}(${urlInfo.note}) "${stripQueryHash(url)}"`,
+            });
+
+            out.push({
+              method: canonicalizeMethod(verb),
+              path: canonicalizePath(url),
+              source: fileRel,
+              confidence: urlInfo.confidence,
+              kind: "axios_member",
+              evidence: ev ? [ev] : [],
+            });
+            return;
+          }
+
+          // axios({ url, method })
+          if (t.isIdentifier(callee, { name: "axios" })) {
+            const a0 = p.node.arguments[0];
+            const cfg = extractAxiosConfig(a0);
+            if (!cfg) return;
+
+            const url = cfg.urlInfo.url;
+            if (!url.startsWith("/")) return;
+
+            const ev = evidenceFromLoc({
+              fileAbs,
+              fileRel,
+              loc: p.node.loc,
+              reason: `Client axios(config:${cfg.urlInfo.note}) "${stripQueryHash(url)}"`,
+            });
+
+            out.push({
+              method: cfg.method,
+              path: canonicalizePath(url),
+              source: fileRel,
+              confidence: cfg.urlInfo.confidence === "high" ? "high" : "med",
+              kind: "axios_config",
+              evidence: ev ? [ev] : [],
+            });
+            return;
+          }
+
+          // useSWR("/api/user", fetcher) - Modern React data fetching
+          if (t.isIdentifier(callee, { name: "useSWR" })) {
+            const a0 = p.node.arguments[0];
+
+            const urlInfo = extractUrlLike(a0);
+            if (!urlInfo) return;
+
+            const url = urlInfo.url;
+            if (!url.startsWith("/")) return;
+
+            const ev = evidenceFromLoc({
+              fileAbs,
+              fileRel,
+              loc: p.node.loc,
+              reason: `Client useSWR(${urlInfo.note}) "${stripQueryHash(url)}"`,
+            });
+
+            out.push({
+              method: "GET", // SWR is almost always GET
+              path: canonicalizePath(url),
+              source: fileRel,
+              confidence: urlInfo.confidence,
+              kind: "useSWR",
+              evidence: ev ? [ev] : [],
+            });
+            return;
+          }
+
+          // useQuery (React Query / TanStack Query) - Another popular data fetching library
+          if (t.isIdentifier(callee, { name: "useQuery" })) {
+            // useQuery({ queryKey: [...], queryFn: () => fetch("/api/x") })
+            // or useQuery(["key"], () => fetch("/api/x"))
+            const a0 = p.node.arguments[0];
+
+            // Try to extract URL from the arguments (often in queryFn)
+            if (t.isObjectExpression(a0)) {
+              for (const prop of a0.properties) {
+                if (!t.isObjectProperty(prop)) continue;
+                if (!t.isIdentifier(prop.key, { name: "queryFn" })) continue;
+
+                // queryFn is often an arrow function with fetch inside
+                const fn = prop.value;
+                if (t.isArrowFunctionExpression(fn) || t.isFunctionExpression(fn)) {
+                  // Best effort: look for string literals that look like API paths
+                  const fnCode = code.slice(fn.start, fn.end);
+                  const urlMatch = fnCode.match(/["'`](\/api\/[^"'`]+)["'`]/);
+                  if (urlMatch) {
+                    const url = urlMatch[1].split("?")[0].split("#")[0];
+                    const ev = evidenceFromLoc({
+                      fileAbs,
+                      fileRel,
+                      loc: p.node.loc,
+                      reason: `Client useQuery(queryFn) "${url}"`,
+                    });
+
+                    out.push({
+                      method: "GET",
+                      path: canonicalizePath(url),
+                      source: fileRel,
+                      confidence: "low", // Less certain extraction
+                      kind: "useQuery",
+                      evidence: ev ? [ev] : [],
+                    });
+                  }
+                }
               }
             }
           }
+        },
+      });
+    } catch {
+      // Babel traverse can fail on some edge-case files; skip
+      stats.parseErrors++;
+    }
+  }
 
-          const ev = evidenceFromLoc({
-            fileAbs, fileRel, loc: p.node.loc,
-            reason: `Client fetch("${url}")` 
-          });
-
-          out.push({
-            method,
-            path: canonicalizePath(url),
-            source: fileRel,
-            confidence: "high",
-            evidence: ev ? [ev] : []
-          });
-          return;
-        }
+  return out;
+}
 
-        // axios.get("/api/x")
-        if (isAxiosMember(callee)) {
-          const verb = callee.property.name.toUpperCase();
-          const a0 = p.node.arguments[0];
-          if (!t.isStringLiteral(a0)) return;
-
-          const url = a0.value;
-          if (!url.startsWith("/")) return;
-
-          const ev = evidenceFromLoc({
-            fileAbs, fileRel, loc: p.node.loc,
-            reason: `Client axios.${verb.toLowerCase()}("${url}")` 
-          });
-
-          out.push({
-            method: canonicalizeMethod(verb),
-            path: canonicalizePath(url),
-            source: fileRel,
-            confidence: "high",
-            evidence: ev ? [ev] : []
-          });
-        }
+// ---------- workspace detection (best-effort, no new deps) ----------
+function readJsonIfExists(abs) {
+  try {
+    return JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function detectWorkspaces(repoRoot) {
+  const roots = [];
+
+  const pkg = readJsonIfExists(path.join(repoRoot, "package.json"));
+  if (pkg && pkg.workspaces) {
+    const ws = pkg.workspaces;
+    const patterns = Array.isArray(ws) ? ws : Array.isArray(ws.packages) ? ws.packages : [];
+    for (const pat of patterns) {
+      if (typeof pat === "string") roots.push(pat);
+    }
+  }
+
+  // pnpm-workspace.yaml minimal parser (just handles `packages:` list)
+  const pnpmWs = path.join(repoRoot, "pnpm-workspace.yaml");
+  if (fs.existsSync(pnpmWs)) {
+    const raw = safeRead(pnpmWs) || "";
+    const lines = raw.split(/\r?\n/);
+    let inPackages = false;
+    for (const line of lines) {
+      const l = line.trim();
+      if (!l) continue;
+      if (l.startsWith("packages:")) {
+        inPackages = true;
+        continue;
       }
-    });
+      if (inPackages) {
+        const m = l.match(/^-+\s*['"]?([^'"]+)['"]?\s*$/);
+        if (m && m[1]) roots.push(m[1]);
+        else if (!l.startsWith("-")) inPackages = false;
+      }
+    }
   }
 
-  return out;
+  // Expand to actual package.json roots
+  const uniq = Array.from(new Set(roots)).filter(Boolean);
+  const pkgJsonGlobs = uniq.map((p) => (p.endsWith("/") ? p : p + "/") + "package.json");
+
+  const found = pkgJsonGlobs.length
+    ? fg.sync(pkgJsonGlobs, { cwd: repoRoot, absolute: true, ignore: IGNORE_GLOBS })
+    : [];
+
+  const workspaces = found
+    .map((abs) => path.dirname(abs))
+    .map((abs) => normalizeRel(repoRoot, abs))
+    .sort();
+
+  return workspaces;
 }
 
-// ---------- fastify entry detection ----------
-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"
-  ];
-  for (const rel of candidates) {
-    const abs = path.join(repoRoot, rel);
-    if (exists(abs)) return rel;
+// ---------- fastify entry detection (monorepo-friendly) ----------
+async function detectFastifyEntries(repoRoot) {
+  // Keep it targeted (fast), but broad enough for monorepos.
+  const candidates = await fg(
+    [
+      "**/{server,app,main,index}.{ts,tsx,js,jsx}",
+      "**/src/{server,app,main,index}.{ts,tsx,js,jsx}",
+      "**/*fastify*.{ts,tsx,js,jsx}",
+      "**/*api*.{ts,tsx,js,jsx}",
+    ],
+    {
+      cwd: repoRoot,
+      absolute: true,
+      ignore: IGNORE_GLOBS,
+    }
+  );
+
+  const entries = [];
+  const fastifySignal = /\b(Fastify\s*\(|fastify\s*\(|require\(['"]fastify['"]\)|from\s+['"]fastify['"])\b/;
+  const listenSignal = /\.\s*(listen|ready)\s*\(/;
+
+  for (const fileAbs of candidates) {
+    const code = safeRead(fileAbs);
+    if (!code) continue;
+    // Must look like fastify + server start-ish signal (reduces noise)
+    if (fastifySignal.test(code) && listenSignal.test(code)) {
+      entries.push(fileAbs);
+    }
   }
-  return null;
+
+  return Array.from(new Set(entries));
 }
 
 // ---------- truthpack build/write ----------
 async function buildTruthpack({ repoRoot, fastifyEntry }) {
+  const stats = {
+    parseErrors: 0,
+    fastifyEntries: 0,
+    fastifyRoutes: 0,
+    nextAppRoutes: 0,
+    nextPagesRoutes: 0,
+    clientRefs: 0,
+    serverRoutes: 0,
+    gaps: 0,
+  };
+
+  // Workspaces (for metadata + future use)
+  const workspaces = detectWorkspaces(repoRoot);
+
   // Next.js routes (App Router + Pages Router)
-  const nextApp = await resolveNextAppApiRoutes(repoRoot);
-  const nextPages = await resolveNextPagesApiRoutes(repoRoot);
+  const nextApp = await resolveNextAppApiRoutes(repoRoot, stats);
+  const nextPages = await resolveNextPagesApiRoutes(repoRoot, stats);
+
+  stats.nextAppRoutes = nextApp.length;
+  stats.nextPagesRoutes = nextPages.length;
 
-  // Fastify routes (legacy detection)
-  const entryRel = fastifyEntry || detectFastifyEntry(repoRoot);
+  // Fastify routes (monorepo-friendly)
   let fastify = { routes: [], gaps: [] };
-  if (entryRel) {
-    const entryAbs = path.isAbsolute(entryRel) ? entryRel : path.join(repoRoot, entryRel);
-    if (exists(entryAbs)) fastify = resolveFastifyRoutes(repoRoot, entryAbs);
+
+  if (fastifyEntry) {
+    const entryAbs = path.isAbsolute(fastifyEntry) ? fastifyEntry : path.join(repoRoot, fastifyEntry);
+    if (exists(entryAbs)) {
+      const resolved = resolveFastifyRoutes(repoRoot, entryAbs, stats);
+      fastify.routes.push(...resolved.routes);
+      fastify.gaps.push(...resolved.gaps);
+      stats.fastifyEntries = 1;
+    }
+  } else {
+    const entries = await detectFastifyEntries(repoRoot);
+    stats.fastifyEntries = entries.length;
+
+    for (const entryAbs of entries) {
+      const resolved = resolveFastifyRoutes(repoRoot, entryAbs, stats);
+      fastify.routes.push(...resolved.routes);
+      fastify.gaps.push(...resolved.gaps);
+    }
   }
 
+  stats.fastifyRoutes = fastify.routes.length;
+
   // Multi-framework route detection v2 (Express, Flask, FastAPI, Django, Hono, Koa, etc.)
   const multiFramework = await resolveAllRoutes(repoRoot);
   const detectedFrameworks = await detectFrameworks(repoRoot);
 
   // Client refs (JS/TS fetch/axios + Python requests/httpx)
-  const clientRefs = await resolveClientRouteRefs(repoRoot);
-  const allClientRefs = [...clientRefs, ...multiFramework.clientRefs];
+  const clientRefs = await resolveClientRouteRefs(repoRoot, stats);
+  const allClientRefs = [...clientRefs, ...(multiFramework.clientRefs || [])];
+
+  stats.clientRefs = allClientRefs.length;
+
+  // Merge all server routes (dedupe with priority)
+  const serverRoutesRaw = [...nextApp, ...nextPages, ...(fastify.routes || []), ...(multiFramework.routes || [])];
 
-  // Merge all server routes (dedupe by method+path)
-  const serverRoutesRaw = [...nextApp, ...nextPages, ...fastify.routes, ...multiFramework.routes];
-  const seenRoutes = new Set();
-  const server = [];
+  const bestByKey = new Map(); // key = method:path
   for (const r of serverRoutesRaw) {
-    const key = `${r.method}:${r.path}`;
-    if (!seenRoutes.has(key)) {
-      seenRoutes.add(key);
-      server.push(r);
+    const key = `${canonicalizeMethod(r.method)}:${canonicalizePath(r.path)}`;
+
+    const prev = bestByKey.get(key);
+    if (!prev) {
+      bestByKey.set(key, { ...r, method: canonicalizeMethod(r.method), path: canonicalizePath(r.path) });
+      continue;
+    }
+
+    // Prefer higher confidence, and prefer specific method over "*"
+    const prevScore = scoreConfidence(prev.confidence) + (prev.method === "*" ? 0 : 1);
+    const curScore = scoreConfidence(r.confidence) + (r.method === "*" ? 0 : 1);
+
+    if (curScore > prevScore) {
+      bestByKey.set(key, { ...r, method: canonicalizeMethod(r.method), path: canonicalizePath(r.path) });
     }
   }
 
+  const server = Array.from(bestByKey.values());
+  stats.serverRoutes = server.length;
+
   // Merge gaps
   const allGaps = [...(fastify.gaps || []), ...(multiFramework.gaps || [])];
+  stats.gaps = allGaps.length;
 
   // Env Truth v1
   const env = await buildEnvTruth(repoRoot);
@@ -611,23 +1389,32 @@ async function buildTruthpack({ repoRoot, fastifyEntry }) {
   const enforcement = buildEnforcementTruth(repoRoot, server);
 
   // Determine frameworks
-  const frameworks = new Set(["next", "fastify"]);
-  detectedFrameworks.forEach(f => frameworks.add(f));
-  server.forEach(r => r.framework && frameworks.add(r.framework));
+  const frameworks = new Set();
+  detectedFrameworks.forEach((f) => frameworks.add(f));
+  server.forEach((r) => r.framework && frameworks.add(r.framework));
+  if (nextApp.length || nextPages.length) frameworks.add("next");
+  if (fastify.routes.length) frameworks.add("fastify");
 
   const truthpack = {
     meta: {
-      version: "2.0.0",
+      version: "2.1.0",
       generatedAt: new Date().toISOString(),
       repoRoot,
-      commit: { sha: process.env.VIBECHECK_COMMIT_SHA || "unknown" }
+      commit: { sha: process.env.VIBECHECK_COMMIT_SHA || "unknown" },
+      stats,
+    },
+    project: {
+      frameworks: Array.from(frameworks),
+      workspaces,
+      entrypoints: {
+        fastify: fastifyEntry ? [fastifyEntry] : [], // entries auto-detected are not stored as rel here by default
+      },
     },
-    project: { frameworks: Array.from(frameworks), workspaces: [], entrypoints: [] },
     routes: { server, clientRefs: allClientRefs, gaps: allGaps },
     env,
     auth,
     billing,
-    enforcement
+    enforcement,
   };
 
   const hash = sha256(JSON.stringify(truthpack));
@@ -639,29 +1426,266 @@ async function buildTruthpack({ repoRoot, fastifyEntry }) {
 function writeTruthpack(repoRoot, truthpack) {
   const dir = path.join(repoRoot, ".vibecheck");
   ensureDir(dir);
-  // Spec: .vibecheck/truthpack.json (not .vibecheck/truth/truthpack.json)
-  fs.writeFileSync(path.join(dir, "truthpack.json"), JSON.stringify(truthpack, null, 2));
+
+  const target = path.join(dir, "truthpack.json");
+  const tmp = path.join(dir, `truthpack.${process.pid}.${Date.now()}.tmp.json`);
+
+  // atomic-ish write: write tmp then rename
+  fs.writeFileSync(tmp, JSON.stringify(truthpack, null, 2));
+  fs.renameSync(tmp, target);
 }
 
 function loadTruthpack(repoRoot) {
-  // Spec path: .vibecheck/truthpack.json
   const specPath = path.join(repoRoot, ".vibecheck", "truthpack.json");
-  // Legacy path: .vibecheck/truth/truthpack.json (backward compat)
   const legacyPath = path.join(repoRoot, ".vibecheck", "truth", "truthpack.json");
+
+  try {
+    return JSON.parse(fs.readFileSync(specPath, "utf8"));
+  } catch {
+    try {
+      return JSON.parse(fs.readFileSync(legacyPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+}
+
+// ---------- RepoIndex-powered build (vNext) ----------
+
+/**
+ * Build truthpack using RepoIndex for single-pass file indexing
+ * This is the optimized path that shares file reads across all extractors.
+ * 
+ * Enable with: VIBECHECK_ENGINE_V2=1
+ * 
+ * @param {Object} options
+ * @param {string} options.repoRoot
+ * @param {string} [options.fastifyEntry]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<Object>}
+ */
+async function buildTruthpackV2({ repoRoot, fastifyEntry, verbose }) {
+  const {
+    createIndex,
+    globalASTCache,
+    logIndexSummary,
+    extractNextAppRoutes,
+    extractNextPagesRoutes,
+    extractClientRefs,
+    extractFastifyRoutes,
+    detectFastifyEntries: detectFastifyEntriesV2,
+    buildEnvTruthV2,
+    buildBillingTruthV2,
+    buildAuthTruthV2,
+    buildEnforcementTruthV2,
+    extractExpressRoutes,
+  } = require("./engine");
+  
+  const startTime = Date.now();
+  
+  // Phase 0: Build RepoIndex (single glob pass)
+  const index = await createIndex(repoRoot);
+  
+  if (verbose || process.env.VIBECHECK_VERBOSE) {
+    logIndexSummary(index);
+    console.log(`   AST Cache: ${globalASTCache.getSummary().hitRate} hit rate`);
+  }
+
+  const stats = {
+    parseErrors: 0,
+    fastifyEntries: 0,
+    fastifyRoutes: 0,
+    nextAppRoutes: 0,
+    nextPagesRoutes: 0,
+    clientRefs: 0,
+    serverRoutes: 0,
+    gaps: 0,
+    indexTimeMs: index.stats.indexTimeMs,
+  };
+
+  // Use signals from index instead of re-detecting
+  const detectedFrameworks = Array.from(index.signals.detectedFrameworks);
+
+  // Workspaces
+  const workspaces = detectWorkspaces(repoRoot);
+
+  // Phase 1: Extract routes using optimized extractors (use RepoIndex + AST cache)
   
-  try { 
-    return JSON.parse(fs.readFileSync(specPath, "utf8")); 
-  } catch { 
-    // Try legacy path
-    try { return JSON.parse(fs.readFileSync(legacyPath, "utf8")); } catch { return null; }
+  // Next.js routes - use optimized extractors
+  const nextApp = extractNextAppRoutes(index, stats);
+  const nextPages = extractNextPagesRoutes(index, stats);
+
+  stats.nextAppRoutes = nextApp.length;
+  stats.nextPagesRoutes = nextPages.length;
+
+  // Fastify routes - use optimized extractor
+  let fastify = { routes: [], gaps: [] };
+
+  if (index.hasFramework("fastify") || fastifyEntry) {
+    if (fastifyEntry) {
+      const entryAbs = path.isAbsolute(fastifyEntry) ? fastifyEntry : path.join(repoRoot, fastifyEntry);
+      if (exists(entryAbs)) {
+        const resolved = extractFastifyRoutes(index, entryAbs, stats);
+        fastify.routes.push(...resolved.routes);
+        fastify.gaps.push(...resolved.gaps);
+        stats.fastifyEntries = 1;
+      }
+    } else {
+      const entries = detectFastifyEntriesV2(index);
+      stats.fastifyEntries = entries.length;
+
+      for (const entryAbs of entries) {
+        const resolved = extractFastifyRoutes(index, entryAbs, stats);
+        fastify.routes.push(...resolved.routes);
+        fastify.gaps.push(...resolved.gaps);
+      }
+    }
   }
+
+  stats.fastifyRoutes = fastify.routes.length;
+
+  // Express routes - use optimized extractor
+  const expressRoutes = extractExpressRoutes(index, stats);
+
+  // Multi-framework routes (Flask, Django, etc. - still uses old resolvers for non-JS frameworks)
+  // Express is handled above via optimized extractor
+  const multiFramework = await resolveAllRoutes(repoRoot, { 
+    mode: process.env.VIBECHECK_ROUTE_SCAN_MODE || "smart",
+    verbose: verbose || !!process.env.VIBECHECK_VERBOSE_ROUTES,
+    skipExpress: true, // Skip Express since we handle it above with optimized extractor
+  });
+
+  // Client refs - use optimized extractor
+  const clientRefsOptimized = extractClientRefs(index, stats);
+  const allClientRefs = [...clientRefsOptimized, ...(multiFramework.clientRefs || [])];
+
+  stats.clientRefs = allClientRefs.length;
+
+  // Merge server routes (including optimized Express routes)
+  const serverRoutesRaw = [...nextApp, ...nextPages, ...(fastify.routes || []), ...expressRoutes, ...(multiFramework.routes || [])];
+
+  const bestByKey = new Map();
+  for (const r of serverRoutesRaw) {
+    const key = `${canonicalizeMethod(r.method)}:${canonicalizePath(r.path)}`;
+    const prev = bestByKey.get(key);
+    if (!prev) {
+      bestByKey.set(key, { ...r, method: canonicalizeMethod(r.method), path: canonicalizePath(r.path) });
+      continue;
+    }
+    const prevScore = scoreConfidence(prev.confidence) + (prev.method === "*" ? 0 : 1);
+    const curScore = scoreConfidence(r.confidence) + (r.method === "*" ? 0 : 1);
+    if (curScore > prevScore) {
+      bestByKey.set(key, { ...r, method: canonicalizeMethod(r.method), path: canonicalizePath(r.path) });
+    }
+  }
+
+  const server = Array.from(bestByKey.values());
+  stats.serverRoutes = server.length;
+
+  // Merge gaps
+  const allGaps = [...(fastify.gaps || []), ...(multiFramework.gaps || [])];
+  stats.gaps = allGaps.length;
+
+  // Phase 2: Build other truths (env, auth, billing, enforcement)
+  // All use optimized extractors with RepoIndex
+  const env = buildEnvTruthV2(index, stats);
+  const auth = buildAuthTruthV2(index, server);
+  const billing = buildBillingTruthV2(index, stats);
+  const enforcement = buildEnforcementTruthV2(index, server);
+
+  // Determine frameworks
+  const frameworks = new Set(detectedFrameworks);
+  server.forEach((r) => r.framework && frameworks.add(r.framework));
+  if (nextApp.length || nextPages.length) frameworks.add("next");
+  if (fastify.routes.length) frameworks.add("fastify");
+
+  stats.totalTimeMs = Date.now() - startTime;
+
+  const truthpack = {
+    meta: {
+      version: "2.2.0", // Bump version for v2 engine
+      generatedAt: new Date().toISOString(),
+      repoRoot,
+      commit: { sha: process.env.VIBECHECK_COMMIT_SHA || "unknown" },
+      stats,
+      engine: "v2", // Mark as v2 engine
+    },
+    project: {
+      frameworks: Array.from(frameworks),
+      workspaces,
+      entrypoints: {
+        fastify: fastifyEntry ? [fastifyEntry] : [],
+      },
+    },
+    routes: { server, clientRefs: allClientRefs, gaps: allGaps },
+    env,
+    auth,
+    billing,
+    enforcement,
+  };
+
+  const hash = sha256(JSON.stringify(truthpack));
+  truthpack.index = { 
+    hashes: { truthpackHash: hash }, 
+    evidenceRefs: [],
+    repoIndex: {
+      totalFiles: index.stats.totalFiles,
+      totalSize: index.stats.totalSize,
+      indexTimeMs: index.stats.indexTimeMs,
+    },
+  };
+
+  // Clear caches to free memory
+  index.clearContentCache();
+  clearCache();
+
+  return truthpack;
+}
+
+/**
+ * Smart buildTruthpack - uses v2 engine by default for better performance.
+ * Set VIBECHECK_ENGINE_V1=1 to fall back to v1 for backward compatibility.
+ * 
+ * V2 Engine Benefits:
+ * - Single-pass file indexing (RepoIndex)
+ * - Shared AST cache (globalASTCache)
+ * - Token prefiltering for faster file selection
+ * - ~30% faster on typical projects
+ */
+async function buildTruthpackSmart(options) {
+  if (process.env.VIBECHECK_ENGINE_V1 === "1") {
+    return buildTruthpack(options);
+  }
+  // V2 is now the default - uses RepoIndex + AST cache
+  return buildTruthpackV2(options);
 }
 
 module.exports = {
   canonicalizeMethod,
   canonicalizePath,
   buildTruthpack,
+  buildTruthpackV2,
+  buildTruthpackSmart,
   writeTruthpack,
   loadTruthpack,
-  detectFastifyEntry
+  clearCache, // Clear file cache to free memory (important for long-running processes)
+  // kept for backward compatibility if other code imports it,
+  // but fastifyEntry is now optional and auto-detected.
+  detectFastifyEntry: 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",
+    ];
+    for (const rel of candidates) {
+      const abs = path.join(repoRoot, rel);
+      if (exists(abs)) return rel;
+    }
+    return null;
+  },
 };