@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/extractors/next-routes.js

@@ -1,524 +1,524 @@
-/**
- * Next.js Route Extractor v2
- * 
- * Spec-compliant extraction for App Router + Pages Router API routes.
- * Handles dynamic segments, route groups, catch-alls, and method detection.
- * 
- * Canonical path format:
- * - Static: /api/billing/portal
- * - Params: /api/users/{id}
- * - Catch-all: /api/files/{*path}
- * - Optional catch-all: /api/blog/{*slug?}
- */
-
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const fg = require("fast-glob");
-const crypto = require("crypto");
-
-const NEXT_HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
-
-/**
- * Detect Next.js mode and roots
- */
-function detectNextMode(projectRoot) {
-  const result = {
-    present: false,
-    router: "unknown",
-    appDir: null,
-    pagesDir: null,
-    middlewareFile: null,
-    basePath: "",
-    trailingSlash: false,
-    rewrites: [],
-  };
-
-  // Check for Next.js presence
-  const pkgPath = path.join(projectRoot, "package.json");
-  if (fs.existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-      if (pkg.dependencies?.next || pkg.devDependencies?.next) {
-        result.present = true;
-      }
-    } catch {}
-  }
-
-  // Check for next.config
-  const configFiles = ["next.config.js", "next.config.mjs", "next.config.ts"];
-  for (const configFile of configFiles) {
-    const configPath = path.join(projectRoot, configFile);
-    if (fs.existsSync(configPath)) {
-      result.present = true;
-      parseNextConfig(configPath, result);
-      break;
-    }
-  }
-
-  // Check for app/ and pages/ directories
-  const appDir = path.join(projectRoot, "app");
-  const srcAppDir = path.join(projectRoot, "src", "app");
-  const pagesDir = path.join(projectRoot, "pages");
-  const srcPagesDir = path.join(projectRoot, "src", "pages");
-
-  if (fs.existsSync(appDir)) {
-    result.appDir = appDir;
-    result.present = true;
-  } else if (fs.existsSync(srcAppDir)) {
-    result.appDir = srcAppDir;
-    result.present = true;
-  }
-
-  if (fs.existsSync(pagesDir)) {
-    result.pagesDir = pagesDir;
-    result.present = true;
-  } else if (fs.existsSync(srcPagesDir)) {
-    result.pagesDir = srcPagesDir;
-    result.present = true;
-  }
-
-  // Determine router mode
-  if (result.appDir && result.pagesDir) {
-    result.router = "mixed";
-  } else if (result.appDir) {
-    result.router = "app";
-  } else if (result.pagesDir) {
-    result.router = "pages";
-  }
-
-  // Find middleware
-  const middlewareLocations = [
-    path.join(projectRoot, "middleware.ts"),
-    path.join(projectRoot, "middleware.js"),
-    path.join(projectRoot, "src", "middleware.ts"),
-    path.join(projectRoot, "src", "middleware.js"),
-  ];
-  for (const loc of middlewareLocations) {
-    if (fs.existsSync(loc)) {
-      result.middlewareFile = loc;
-      break;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Parse next.config for basePath, trailingSlash, rewrites
- */
-function parseNextConfig(configPath, result) {
-  try {
-    const content = fs.readFileSync(configPath, "utf8");
-    
-    // Extract basePath
-    const basePathMatch = content.match(/basePath\s*:\s*['"`]([^'"`]+)['"`]/);
-    if (basePathMatch) {
-      result.basePath = basePathMatch[1];
-    }
-
-    // Extract trailingSlash
-    if (/trailingSlash\s*:\s*true/.test(content)) {
-      result.trailingSlash = true;
-    }
-
-    // Extract rewrites (basic pattern matching)
-    const rewriteMatches = content.matchAll(/source\s*:\s*['"`]([^'"`]+)['"`][\s\S]*?destination\s*:\s*['"`]([^'"`]+)['"`]/g);
-    for (const match of rewriteMatches) {
-      result.rewrites.push({
-        source: match[1],
-        destination: match[2],
-        isExternal: match[2].startsWith("http"),
-      });
-    }
-  } catch {}
-}
-
-/**
- * Extract App Router API routes from app/api directory
- */
-function extractAppRouterRoutes(appDir, projectRoot) {
-  const routes = [];
-  
-  if (!appDir || !fs.existsSync(appDir)) return routes;
-
-  // Find all route handlers
-  const pattern = path.join(appDir, "api", "**", "route.{js,jsx,ts,tsx}").replace(/\\/g, "/");
-  const files = fg.sync(pattern, { onlyFiles: true, absolute: true });
-
-  for (const file of files) {
-    const route = extractAppRouteHandler(file, appDir, projectRoot);
-    if (route) {
-      routes.push(route);
-    }
-  }
-
-  return routes;
-}
-
-/**
- * Extract a single App Router route handler
- */
-function extractAppRouteHandler(file, appDir, projectRoot) {
-  const content = fs.readFileSync(file, "utf8");
-  const relPath = path.relative(appDir, file).replace(/\\/g, "/");
-  
-  // Build canonical path from file path
-  // Strip api/ prefix and route.* suffix
-  let urlPath = relPath
-    .replace(/^api\//, "/api/")
-    .replace(/\/route\.(js|jsx|ts|tsx)$/, "")
-    .replace(/^\/api/, "/api"); // Ensure /api prefix
-
-  // Handle special segments
-  urlPath = convertNextPathToCanonical(urlPath);
-
-  // Extract HTTP methods from exports
-  const methods = extractExportedMethods(content);
-  const confidence = methods.length > 0 && !methods.includes("UNKNOWN") ? "high" : "low";
-
-  // Build evidence
-  const evidence = [];
-  for (const method of methods) {
-    const methodMatch = content.match(new RegExp(`export\\s+(async\\s+)?function\\s+${method}|export\\s+const\\s+${method}\\s*=`, "m"));
-    if (methodMatch) {
-      const lineNum = content.substring(0, methodMatch.index).split("\n").length;
-      evidence.push({
-        id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
-        kind: "file",
-        reason: `${method} handler export`,
-        file: path.relative(projectRoot, file).replace(/\\/g, "/"),
-        lines: `${lineNum}-${lineNum + 5}`,
-        snippetHash: hashSnippet(methodMatch[0]),
-      });
-    }
-  }
-
-  // If no methods found, add generic evidence
-  if (evidence.length === 0) {
-    evidence.push({
-      id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
-      kind: "file",
-      reason: "Route handler file",
-      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
-      lines: "1-10",
-    });
-  }
-
-  return {
-    id: `R_NEXT_APP_${hashPath(urlPath)}`,
-    kind: "next_route_handler",
-    methods: methods.length > 0 ? methods : ["UNKNOWN"],
-    rawPath: relPath,
-    path: urlPath,
-    canonicalPath: urlPath,
-    authRequired: "unknown",
-    confidence,
-    handler: {
-      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
-      export: methods[0] || "handler",
-    },
-    evidence,
-  };
-}
-
-/**
- * Extract Pages Router API routes (pages/api/**)
- */
-function extractPagesRouterRoutes(pagesDir, projectRoot) {
-  const routes = [];
-  
-  if (!pagesDir || !fs.existsSync(pagesDir)) return routes;
-
-  const apiDir = path.join(pagesDir, "api");
-  if (!fs.existsSync(apiDir)) return routes;
-
-  // Find all API files
-  const pattern = path.join(apiDir, "**", "*.{js,jsx,ts,tsx}").replace(/\\/g, "/");
-  const files = fg.sync(pattern, { onlyFiles: true, absolute: true });
-
-  for (const file of files) {
-    const route = extractPagesApiHandler(file, pagesDir, projectRoot);
-    if (route) {
-      routes.push(route);
-    }
-  }
-
-  return routes;
-}
-
-/**
- * Extract a single Pages API handler
- */
-function extractPagesApiHandler(file, pagesDir, projectRoot) {
-  const content = fs.readFileSync(file, "utf8");
-  const relPath = path.relative(pagesDir, file).replace(/\\/g, "/");
-
-  // Build URL path
-  let urlPath = "/" + relPath
-    .replace(/^api\//, "api/")
-    .replace(/\.(js|jsx|ts|tsx)$/, "")
-    .replace(/\/index$/, "");
-
-  // Ensure /api prefix
-  if (!urlPath.startsWith("/api")) {
-    urlPath = "/api" + urlPath;
-  }
-
-  // Convert dynamic segments
-  urlPath = convertNextPathToCanonical(urlPath);
-
-  // Extract methods from req.method checks
-  const methods = extractReqMethodChecks(content);
-  const confidence = methods.length > 0 && !methods.includes("UNKNOWN") ? "medium" : "low";
-
-  // Build evidence
-  const evidence = [{
-    id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
-    kind: "file",
-    reason: "Pages API handler",
-    file: path.relative(projectRoot, file).replace(/\\/g, "/"),
-    lines: "1-20",
-  }];
-
-  // Add evidence for method checks
-  const methodCheckMatch = content.match(/req\.method\s*===?\s*['"`](\w+)['"`]/);
-  if (methodCheckMatch) {
-    const lineNum = content.substring(0, methodCheckMatch.index).split("\n").length;
-    evidence.push({
-      id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
-      kind: "file",
-      reason: "Method check",
-      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
-      lines: `${lineNum}-${lineNum}`,
-      snippetHash: hashSnippet(methodCheckMatch[0]),
-    });
-  }
-
-  return {
-    id: `R_NEXT_PAGES_${hashPath(urlPath)}`,
-    kind: "next_pages_api",
-    methods: methods.length > 0 ? methods : ["UNKNOWN"],
-    rawPath: relPath,
-    path: urlPath,
-    canonicalPath: urlPath,
-    authRequired: "unknown",
-    confidence,
-    handler: {
-      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
-      export: "default",
-    },
-    evidence,
-  };
-}
-
-/**
- * Convert Next.js path segments to canonical format
- * [id] → {id}
- * [...slug] → {*slug}
- * [[...slug]] → {*slug?}
- * (group) → removed
- */
-function convertNextPathToCanonical(urlPath) {
-  return urlPath
-    // Remove route groups (parentheses)
-    .replace(/\/\([^)]+\)/g, "")
-    // Remove parallel routes (@)
-    .replace(/\/@[^/]+/g, "")
-    // Optional catch-all [[...slug]]
-    .replace(/\[\[\.\.\.([^\]]+)\]\]/g, "{*$1?}")
-    // Catch-all [...slug]
-    .replace(/\[\.\.\.([^\]]+)\]/g, "{*$1}")
-    // Dynamic segment [id]
-    .replace(/\[([^\]]+)\]/g, "{$1}")
-    // Clean up double slashes
-    .replace(/\/+/g, "/")
-    // Remove trailing slash except root
-    .replace(/(.)\/$/, "$1");
-}
-
-/**
- * Extract exported HTTP methods from App Router file
- */
-function extractExportedMethods(content) {
-  const methods = [];
-
-  for (const method of NEXT_HTTP_METHODS) {
-    // export async function GET
-    // export function GET
-    // export const GET = 
-    const patterns = [
-      new RegExp(`export\\s+async\\s+function\\s+${method}\\s*\\(`, "m"),
-      new RegExp(`export\\s+function\\s+${method}\\s*\\(`, "m"),
-      new RegExp(`export\\s+const\\s+${method}\\s*=`, "m"),
-    ];
-
-    for (const pattern of patterns) {
-      if (pattern.test(content)) {
-        methods.push(method);
-        break;
-      }
-    }
-  }
-
-  return methods;
-}
-
-/**
- * Extract methods from req.method checks in Pages API
- */
-function extractReqMethodChecks(content) {
-  const methods = new Set();
-
-  // Match patterns like: req.method === "POST" or req.method === 'GET'
-  const matches = content.matchAll(/req\.method\s*===?\s*['"`](\w+)['"`]/g);
-  for (const match of matches) {
-    const method = match[1].toUpperCase();
-    if (NEXT_HTTP_METHODS.includes(method)) {
-      methods.add(method);
-    }
-  }
-
-  // Match switch case patterns
-  const caseMatches = content.matchAll(/case\s*['"`](\w+)['"`]\s*:/g);
-  for (const match of caseMatches) {
-    const method = match[1].toUpperCase();
-    if (NEXT_HTTP_METHODS.includes(method)) {
-      methods.add(method);
-    }
-  }
-
-  return [...methods];
-}
-
-/**
- * Extract middleware matchers for auth hints
- */
-function extractMiddlewareMatchers(middlewareFile, projectRoot) {
-  const result = {
-    matchers: [],
-    protectedHints: [],
-  };
-
-  if (!middlewareFile || !fs.existsSync(middlewareFile)) return result;
-
-  const content = fs.readFileSync(middlewareFile, "utf8");
-
-  // Extract config.matcher
-  const matcherMatch = content.match(/export\s+const\s+config\s*=\s*\{[^}]*matcher\s*:\s*(\[[^\]]+\]|['"`][^'"`]+['"`])/s);
-  if (matcherMatch) {
-    const matcherValue = matcherMatch[1];
-    
-    // Parse array
-    if (matcherValue.startsWith("[")) {
-      const patterns = matcherValue.matchAll(/['"`]([^'"`]+)['"`]/g);
-      for (const p of patterns) {
-        result.matchers.push(p[1]);
-      }
-    } else {
-      // Single string
-      const singleMatch = matcherValue.match(/['"`]([^'"`]+)['"`]/);
-      if (singleMatch) {
-        result.matchers.push(singleMatch[1]);
-      }
-    }
-  }
-
-  // Detect auth signals (protected hints)
-  const authSignals = [
-    /getToken\s*\(/,
-    /getServerSession\s*\(/,
-    /auth\s*\(\s*\)/,
-    /cookies\(\)\.get\s*\(/,
-    /NextResponse\.redirect.*login/i,
-    /clerk/i,
-    /supabase.*auth/i,
-  ];
-
-  for (const signal of authSignals) {
-    if (signal.test(content)) {
-      result.protectedHints.push({
-        signal: signal.toString(),
-        file: path.relative(projectRoot, middlewareFile).replace(/\\/g, "/"),
-      });
-    }
-  }
-
-  return result;
-}
-
-/**
- * Main extraction function
- */
-function extractNextRoutes(projectRoot) {
-  const mode = detectNextMode(projectRoot);
-  
-  if (!mode.present) {
-    return {
-      present: false,
-      router: "unknown",
-      routes: [],
-      middleware: { matchers: [], protectedHints: [] },
-    };
-  }
-
-  const routes = [];
-
-  // Extract App Router routes
-  if (mode.appDir) {
-    const appRoutes = extractAppRouterRoutes(mode.appDir, projectRoot);
-    routes.push(...appRoutes);
-  }
-
-  // Extract Pages Router routes
-  if (mode.pagesDir) {
-    const pagesRoutes = extractPagesRouterRoutes(mode.pagesDir, projectRoot);
-    routes.push(...pagesRoutes);
-  }
-
-  // Apply basePath to all routes
-  if (mode.basePath) {
-    for (const route of routes) {
-      route.path = mode.basePath + route.path;
-      route.canonicalPath = mode.basePath + route.canonicalPath;
-    }
-  }
-
-  // Extract middleware
-  const middleware = extractMiddlewareMatchers(mode.middlewareFile, projectRoot);
-
-  return {
-    present: true,
-    router: mode.router,
-    appDir: mode.appDir ? path.relative(projectRoot, mode.appDir) : null,
-    pagesDir: mode.pagesDir ? path.relative(projectRoot, mode.pagesDir) : null,
-    basePath: mode.basePath,
-    trailingSlash: mode.trailingSlash,
-    rewrites: mode.rewrites,
-    middlewareFile: mode.middlewareFile ? path.relative(projectRoot, mode.middlewareFile) : null,
-    routes,
-    middleware,
-  };
-}
-
-// Helpers
-function hashSnippet(text) {
-  return `sha256:${crypto.createHash("sha256").update(text).digest("hex")}`;
-}
-
-function hashPath(urlPath) {
-  return crypto.createHash("sha256").update(urlPath).digest("hex").slice(0, 12).toUpperCase();
-}
-
-module.exports = {
-  detectNextMode,
-  extractNextRoutes,
-  extractAppRouterRoutes,
-  extractPagesRouterRoutes,
-  extractMiddlewareMatchers,
-  convertNextPathToCanonical,
-  extractExportedMethods,
-  extractReqMethodChecks,
-  NEXT_HTTP_METHODS,
-};
+/**
+ * Next.js Route Extractor v2
+ * 
+ * Spec-compliant extraction for App Router + Pages Router API routes.
+ * Handles dynamic segments, route groups, catch-alls, and method detection.
+ * 
+ * Canonical path format:
+ * - Static: /api/billing/portal
+ * - Params: /api/users/{id}
+ * - Catch-all: /api/files/{*path}
+ * - Optional catch-all: /api/blog/{*slug?}
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const fg = require("fast-glob");
+const crypto = require("crypto");
+
+const NEXT_HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+
+/**
+ * Detect Next.js mode and roots
+ */
+function detectNextMode(projectRoot) {
+  const result = {
+    present: false,
+    router: "unknown",
+    appDir: null,
+    pagesDir: null,
+    middlewareFile: null,
+    basePath: "",
+    trailingSlash: false,
+    rewrites: [],
+  };
+
+  // Check for Next.js presence
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      if (pkg.dependencies?.next || pkg.devDependencies?.next) {
+        result.present = true;
+      }
+    } catch {}
+  }
+
+  // Check for next.config
+  const configFiles = ["next.config.js", "next.config.mjs", "next.config.ts"];
+  for (const configFile of configFiles) {
+    const configPath = path.join(projectRoot, configFile);
+    if (fs.existsSync(configPath)) {
+      result.present = true;
+      parseNextConfig(configPath, result);
+      break;
+    }
+  }
+
+  // Check for app/ and pages/ directories
+  const appDir = path.join(projectRoot, "app");
+  const srcAppDir = path.join(projectRoot, "src", "app");
+  const pagesDir = path.join(projectRoot, "pages");
+  const srcPagesDir = path.join(projectRoot, "src", "pages");
+
+  if (fs.existsSync(appDir)) {
+    result.appDir = appDir;
+    result.present = true;
+  } else if (fs.existsSync(srcAppDir)) {
+    result.appDir = srcAppDir;
+    result.present = true;
+  }
+
+  if (fs.existsSync(pagesDir)) {
+    result.pagesDir = pagesDir;
+    result.present = true;
+  } else if (fs.existsSync(srcPagesDir)) {
+    result.pagesDir = srcPagesDir;
+    result.present = true;
+  }
+
+  // Determine router mode
+  if (result.appDir && result.pagesDir) {
+    result.router = "mixed";
+  } else if (result.appDir) {
+    result.router = "app";
+  } else if (result.pagesDir) {
+    result.router = "pages";
+  }
+
+  // Find middleware
+  const middlewareLocations = [
+    path.join(projectRoot, "middleware.ts"),
+    path.join(projectRoot, "middleware.js"),
+    path.join(projectRoot, "src", "middleware.ts"),
+    path.join(projectRoot, "src", "middleware.js"),
+  ];
+  for (const loc of middlewareLocations) {
+    if (fs.existsSync(loc)) {
+      result.middlewareFile = loc;
+      break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse next.config for basePath, trailingSlash, rewrites
+ */
+function parseNextConfig(configPath, result) {
+  try {
+    const content = fs.readFileSync(configPath, "utf8");
+    
+    // Extract basePath
+    const basePathMatch = content.match(/basePath\s*:\s*['"`]([^'"`]+)['"`]/);
+    if (basePathMatch) {
+      result.basePath = basePathMatch[1];
+    }
+
+    // Extract trailingSlash
+    if (/trailingSlash\s*:\s*true/.test(content)) {
+      result.trailingSlash = true;
+    }
+
+    // Extract rewrites (basic pattern matching)
+    const rewriteMatches = content.matchAll(/source\s*:\s*['"`]([^'"`]+)['"`][\s\S]*?destination\s*:\s*['"`]([^'"`]+)['"`]/g);
+    for (const match of rewriteMatches) {
+      result.rewrites.push({
+        source: match[1],
+        destination: match[2],
+        isExternal: match[2].startsWith("http"),
+      });
+    }
+  } catch {}
+}
+
+/**
+ * Extract App Router API routes from app/api directory
+ */
+function extractAppRouterRoutes(appDir, projectRoot) {
+  const routes = [];
+  
+  if (!appDir || !fs.existsSync(appDir)) return routes;
+
+  // Find all route handlers
+  const pattern = path.join(appDir, "api", "**", "route.{js,jsx,ts,tsx}").replace(/\\/g, "/");
+  const files = fg.sync(pattern, { onlyFiles: true, absolute: true });
+
+  for (const file of files) {
+    const route = extractAppRouteHandler(file, appDir, projectRoot);
+    if (route) {
+      routes.push(route);
+    }
+  }
+
+  return routes;
+}
+
+/**
+ * Extract a single App Router route handler
+ */
+function extractAppRouteHandler(file, appDir, projectRoot) {
+  const content = fs.readFileSync(file, "utf8");
+  const relPath = path.relative(appDir, file).replace(/\\/g, "/");
+  
+  // Build canonical path from file path
+  // Strip api/ prefix and route.* suffix
+  let urlPath = relPath
+    .replace(/^api\//, "/api/")
+    .replace(/\/route\.(js|jsx|ts|tsx)$/, "")
+    .replace(/^\/api/, "/api"); // Ensure /api prefix
+
+  // Handle special segments
+  urlPath = convertNextPathToCanonical(urlPath);
+
+  // Extract HTTP methods from exports
+  const methods = extractExportedMethods(content);
+  const confidence = methods.length > 0 && !methods.includes("UNKNOWN") ? "high" : "low";
+
+  // Build evidence
+  const evidence = [];
+  for (const method of methods) {
+    const methodMatch = content.match(new RegExp(`export\\s+(async\\s+)?function\\s+${method}|export\\s+const\\s+${method}\\s*=`, "m"));
+    if (methodMatch) {
+      const lineNum = content.substring(0, methodMatch.index).split("\n").length;
+      evidence.push({
+        id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
+        kind: "file",
+        reason: `${method} handler export`,
+        file: path.relative(projectRoot, file).replace(/\\/g, "/"),
+        lines: `${lineNum}-${lineNum + 5}`,
+        snippetHash: hashSnippet(methodMatch[0]),
+      });
+    }
+  }
+
+  // If no methods found, add generic evidence
+  if (evidence.length === 0) {
+    evidence.push({
+      id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
+      kind: "file",
+      reason: "Route handler file",
+      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
+      lines: "1-10",
+    });
+  }
+
+  return {
+    id: `R_NEXT_APP_${hashPath(urlPath)}`,
+    kind: "next_route_handler",
+    methods: methods.length > 0 ? methods : ["UNKNOWN"],
+    rawPath: relPath,
+    path: urlPath,
+    canonicalPath: urlPath,
+    authRequired: "unknown",
+    confidence,
+    handler: {
+      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
+      export: methods[0] || "handler",
+    },
+    evidence,
+  };
+}
+
+/**
+ * Extract Pages Router API routes (pages/api/**)
+ */
+function extractPagesRouterRoutes(pagesDir, projectRoot) {
+  const routes = [];
+  
+  if (!pagesDir || !fs.existsSync(pagesDir)) return routes;
+
+  const apiDir = path.join(pagesDir, "api");
+  if (!fs.existsSync(apiDir)) return routes;
+
+  // Find all API files
+  const pattern = path.join(apiDir, "**", "*.{js,jsx,ts,tsx}").replace(/\\/g, "/");
+  const files = fg.sync(pattern, { onlyFiles: true, absolute: true });
+
+  for (const file of files) {
+    const route = extractPagesApiHandler(file, pagesDir, projectRoot);
+    if (route) {
+      routes.push(route);
+    }
+  }
+
+  return routes;
+}
+
+/**
+ * Extract a single Pages API handler
+ */
+function extractPagesApiHandler(file, pagesDir, projectRoot) {
+  const content = fs.readFileSync(file, "utf8");
+  const relPath = path.relative(pagesDir, file).replace(/\\/g, "/");
+
+  // Build URL path
+  let urlPath = "/" + relPath
+    .replace(/^api\//, "api/")
+    .replace(/\.(js|jsx|ts|tsx)$/, "")
+    .replace(/\/index$/, "");
+
+  // Ensure /api prefix
+  if (!urlPath.startsWith("/api")) {
+    urlPath = "/api" + urlPath;
+  }
+
+  // Convert dynamic segments
+  urlPath = convertNextPathToCanonical(urlPath);
+
+  // Extract methods from req.method checks
+  const methods = extractReqMethodChecks(content);
+  const confidence = methods.length > 0 && !methods.includes("UNKNOWN") ? "medium" : "low";
+
+  // Build evidence
+  const evidence = [{
+    id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
+    kind: "file",
+    reason: "Pages API handler",
+    file: path.relative(projectRoot, file).replace(/\\/g, "/"),
+    lines: "1-20",
+  }];
+
+  // Add evidence for method checks
+  const methodCheckMatch = content.match(/req\.method\s*===?\s*['"`](\w+)['"`]/);
+  if (methodCheckMatch) {
+    const lineNum = content.substring(0, methodCheckMatch.index).split("\n").length;
+    evidence.push({
+      id: `E_${crypto.randomBytes(4).toString("hex").toUpperCase()}`,
+      kind: "file",
+      reason: "Method check",
+      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
+      lines: `${lineNum}-${lineNum}`,
+      snippetHash: hashSnippet(methodCheckMatch[0]),
+    });
+  }
+
+  return {
+    id: `R_NEXT_PAGES_${hashPath(urlPath)}`,
+    kind: "next_pages_api",
+    methods: methods.length > 0 ? methods : ["UNKNOWN"],
+    rawPath: relPath,
+    path: urlPath,
+    canonicalPath: urlPath,
+    authRequired: "unknown",
+    confidence,
+    handler: {
+      file: path.relative(projectRoot, file).replace(/\\/g, "/"),
+      export: "default",
+    },
+    evidence,
+  };
+}
+
+/**
+ * Convert Next.js path segments to canonical format
+ * [id] → {id}
+ * [...slug] → {*slug}
+ * [[...slug]] → {*slug?}
+ * (group) → removed
+ */
+function convertNextPathToCanonical(urlPath) {
+  return urlPath
+    // Remove route groups (parentheses)
+    .replace(/\/\([^)]+\)/g, "")
+    // Remove parallel routes (@)
+    .replace(/\/@[^/]+/g, "")
+    // Optional catch-all [[...slug]]
+    .replace(/\[\[\.\.\.([^\]]+)\]\]/g, "{*$1?}")
+    // Catch-all [...slug]
+    .replace(/\[\.\.\.([^\]]+)\]/g, "{*$1}")
+    // Dynamic segment [id]
+    .replace(/\[([^\]]+)\]/g, "{$1}")
+    // Clean up double slashes
+    .replace(/\/+/g, "/")
+    // Remove trailing slash except root
+    .replace(/(.)\/$/, "$1");
+}
+
+/**
+ * Extract exported HTTP methods from App Router file
+ */
+function extractExportedMethods(content) {
+  const methods = [];
+
+  for (const method of NEXT_HTTP_METHODS) {
+    // export async function GET
+    // export function GET
+    // export const GET = 
+    const patterns = [
+      new RegExp(`export\\s+async\\s+function\\s+${method}\\s*\\(`, "m"),
+      new RegExp(`export\\s+function\\s+${method}\\s*\\(`, "m"),
+      new RegExp(`export\\s+const\\s+${method}\\s*=`, "m"),
+    ];
+
+    for (const pattern of patterns) {
+      if (pattern.test(content)) {
+        methods.push(method);
+        break;
+      }
+    }
+  }
+
+  return methods;
+}
+
+/**
+ * Extract methods from req.method checks in Pages API
+ */
+function extractReqMethodChecks(content) {
+  const methods = new Set();
+
+  // Match patterns like: req.method === "POST" or req.method === 'GET'
+  const matches = content.matchAll(/req\.method\s*===?\s*['"`](\w+)['"`]/g);
+  for (const match of matches) {
+    const method = match[1].toUpperCase();
+    if (NEXT_HTTP_METHODS.includes(method)) {
+      methods.add(method);
+    }
+  }
+
+  // Match switch case patterns
+  const caseMatches = content.matchAll(/case\s*['"`](\w+)['"`]\s*:/g);
+  for (const match of caseMatches) {
+    const method = match[1].toUpperCase();
+    if (NEXT_HTTP_METHODS.includes(method)) {
+      methods.add(method);
+    }
+  }
+
+  return [...methods];
+}
+
+/**
+ * Extract middleware matchers for auth hints
+ */
+function extractMiddlewareMatchers(middlewareFile, projectRoot) {
+  const result = {
+    matchers: [],
+    protectedHints: [],
+  };
+
+  if (!middlewareFile || !fs.existsSync(middlewareFile)) return result;
+
+  const content = fs.readFileSync(middlewareFile, "utf8");
+
+  // Extract config.matcher
+  const matcherMatch = content.match(/export\s+const\s+config\s*=\s*\{[^}]*matcher\s*:\s*(\[[^\]]+\]|['"`][^'"`]+['"`])/s);
+  if (matcherMatch) {
+    const matcherValue = matcherMatch[1];
+    
+    // Parse array
+    if (matcherValue.startsWith("[")) {
+      const patterns = matcherValue.matchAll(/['"`]([^'"`]+)['"`]/g);
+      for (const p of patterns) {
+        result.matchers.push(p[1]);
+      }
+    } else {
+      // Single string
+      const singleMatch = matcherValue.match(/['"`]([^'"`]+)['"`]/);
+      if (singleMatch) {
+        result.matchers.push(singleMatch[1]);
+      }
+    }
+  }
+
+  // Detect auth signals (protected hints)
+  const authSignals = [
+    /getToken\s*\(/,
+    /getServerSession\s*\(/,
+    /auth\s*\(\s*\)/,
+    /cookies\(\)\.get\s*\(/,
+    /NextResponse\.redirect.*login/i,
+    /clerk/i,
+    /supabase.*auth/i,
+  ];
+
+  for (const signal of authSignals) {
+    if (signal.test(content)) {
+      result.protectedHints.push({
+        signal: signal.toString(),
+        file: path.relative(projectRoot, middlewareFile).replace(/\\/g, "/"),
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Main extraction function
+ */
+function extractNextRoutes(projectRoot) {
+  const mode = detectNextMode(projectRoot);
+  
+  if (!mode.present) {
+    return {
+      present: false,
+      router: "unknown",
+      routes: [],
+      middleware: { matchers: [], protectedHints: [] },
+    };
+  }
+
+  const routes = [];
+
+  // Extract App Router routes
+  if (mode.appDir) {
+    const appRoutes = extractAppRouterRoutes(mode.appDir, projectRoot);
+    routes.push(...appRoutes);
+  }
+
+  // Extract Pages Router routes
+  if (mode.pagesDir) {
+    const pagesRoutes = extractPagesRouterRoutes(mode.pagesDir, projectRoot);
+    routes.push(...pagesRoutes);
+  }
+
+  // Apply basePath to all routes
+  if (mode.basePath) {
+    for (const route of routes) {
+      route.path = mode.basePath + route.path;
+      route.canonicalPath = mode.basePath + route.canonicalPath;
+    }
+  }
+
+  // Extract middleware
+  const middleware = extractMiddlewareMatchers(mode.middlewareFile, projectRoot);
+
+  return {
+    present: true,
+    router: mode.router,
+    appDir: mode.appDir ? path.relative(projectRoot, mode.appDir) : null,
+    pagesDir: mode.pagesDir ? path.relative(projectRoot, mode.pagesDir) : null,
+    basePath: mode.basePath,
+    trailingSlash: mode.trailingSlash,
+    rewrites: mode.rewrites,
+    middlewareFile: mode.middlewareFile ? path.relative(projectRoot, mode.middlewareFile) : null,
+    routes,
+    middleware,
+  };
+}
+
+// Helpers
+function hashSnippet(text) {
+  return `sha256:${crypto.createHash("sha256").update(text).digest("hex")}`;
+}
+
+function hashPath(urlPath) {
+  return crypto.createHash("sha256").update(urlPath).digest("hex").slice(0, 12).toUpperCase();
+}
+
+module.exports = {
+  detectNextMode,
+  extractNextRoutes,
+  extractAppRouterRoutes,
+  extractPagesRouterRoutes,
+  extractMiddlewareMatchers,
+  convertNextPathToCanonical,
+  extractExportedMethods,
+  extractReqMethodChecks,
+  NEXT_HTTP_METHODS,
+};