@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/extractors/route-matcher.js

@@ -1,451 +1,451 @@
-/**
- * Route Matcher v2
- * 
- * Canonical normalization and route matching algorithm.
- * Handles path normalization, specificity scoring, and method matching.
- * 
- * 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 { URL } = require("url");
-
-/**
- * Normalize a URL or path for matching
- * 
- * Steps:
- * 1. Strip scheme + host if present
- * 2. Remove query + fragment
- * 3. Decode safe characters
- * 4. Collapse multiple slashes
- * 5. Apply basePath handling
- * 6. Handle trailingSlash policy
- */
-function normalizeUrl(urlOrPath, options = {}) {
-  const { basePath = "", trailingSlash = false } = options;
-  
-  let normalized = urlOrPath;
-
-  // Strip scheme + host if it's a full URL
-  if (normalized.startsWith("http://") || normalized.startsWith("https://")) {
-    try {
-      const url = new URL(normalized);
-      normalized = url.pathname;
-    } catch {
-      // Invalid URL, treat as path
-    }
-  }
-
-  // Remove query string and fragment
-  normalized = normalized.split("?")[0].split("#")[0];
-
-  // Decode URI components
-  try {
-    normalized = decodeURIComponent(normalized);
-  } catch {
-    // Invalid encoding, keep as-is
-  }
-
-  // Collapse multiple slashes
-  normalized = normalized.replace(/\/+/g, "/");
-
-  // Ensure leading slash
-  if (!normalized.startsWith("/")) {
-    normalized = "/" + normalized;
-  }
-
-  // Strip basePath if present
-  if (basePath && normalized.startsWith(basePath)) {
-    normalized = normalized.slice(basePath.length) || "/";
-  }
-
-  // Handle trailing slash
-  if (!trailingSlash && normalized.length > 1) {
-    normalized = normalized.replace(/\/$/, "");
-  }
-
-  return normalized;
-}
-
-/**
- * Convert any path format to canonical format
- * 
- * Input formats:
- * - Next.js: [id], [...slug], [[...slug]]
- * - Fastify: :id, :path*, /*
- * - Express: :id, :path(*)
- * 
- * Output format:
- * - Params: {id}
- * - Catch-all: {*slug}
- * - Optional catch-all: {*slug?}
- */
-function toCanonicalPath(rawPath, framework = "auto") {
-  let canonical = rawPath;
-
-  // Next.js conversions
-  canonical = canonical
-    // Optional catch-all [[...slug]]
-    .replace(/\[\[\.\.\.([^\]]+)\]\]/g, "{*$1?}")
-    // Catch-all [...slug]
-    .replace(/\[\.\.\.([^\]]+)\]/g, "{*$1}")
-    // Dynamic segment [id]
-    .replace(/\[([^\]]+)\]/g, "{$1}")
-    // Route groups (group) - remove
-    .replace(/\/\([^)]+\)/g, "")
-    // Parallel routes @slot - remove
-    .replace(/\/@[^/]+/g, "");
-
-  // Fastify/Express conversions
-  canonical = canonical
-    // Wildcard catch-all /*
-    .replace(/\/\*$/, "/{*path}")
-    // Named wildcard :path*
-    .replace(/:(\w+)\*/g, "{*$1}")
-    // Named param :id
-    .replace(/:(\w+)/g, "{$1}");
-
-  // Clean up
-  canonical = canonical
-    .replace(/\/+/g, "/")
-    .replace(/(.)\/$/, "$1");
-
-  // Ensure leading slash
-  if (!canonical.startsWith("/")) {
-    canonical = "/" + canonical;
-  }
-
-  return canonical;
-}
-
-/**
- * Convert canonical path to regex for matching
- */
-function canonicalToRegex(canonicalPath) {
-  let pattern = canonicalPath
-    // Escape regex special chars (except our placeholders)
-    .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
-    // Optional catch-all {*slug?}
-    .replace(/\\\{\\\*(\w+)\?\\\}/g, "(?:/.*)?")
-    // Required catch-all {*slug}
-    .replace(/\\\{\\\*(\w+)\\\}/g, "/.+")
-    // Named param {id}
-    .replace(/\\\{(\w+)\\\}/g, "[^/]+");
-
-  return new RegExp(`^${pattern}$`);
-}
-
-/**
- * Calculate specificity score for a route
- * Higher score = more specific = better match
- * 
- * Scoring:
- * - Static segment: +10
- * - Named param: +5
- * - Catch-all: +1
- * - Optional catch-all: +0
- */
-function calculateSpecificity(canonicalPath) {
-  const segments = canonicalPath.split("/").filter(Boolean);
-  let score = 0;
-
-  for (const segment of segments) {
-    if (segment.startsWith("{*") && segment.endsWith("?}")) {
-      // Optional catch-all
-      score += 0;
-    } else if (segment.startsWith("{*")) {
-      // Required catch-all
-      score += 1;
-    } else if (segment.startsWith("{")) {
-      // Named param
-      score += 5;
-    } else {
-      // Static segment
-      score += 10;
-    }
-  }
-
-  return score;
-}
-
-/**
- * Match a client call path against server routes
- * 
- * Algorithm:
- * 1. Exact match (method + path)
- * 2. Dynamic match with specificity scoring
- * 3. Method fallback (UNKNOWN or wildcard)
- * 
- * Returns: { matched: boolean, route: Route | null, confidence: string, matchType: string }
- */
-function matchRoute(normalizedPath, method, serverRoutes, options = {}) {
-  const { allowMethodMismatch = false, considerRewrites = [] } = options;
-  const methodUpper = method?.toUpperCase() || "UNKNOWN";
-
-  // Step 1: Exact match
-  for (const route of serverRoutes) {
-    if (route.canonicalPath === normalizedPath || route.path === normalizedPath) {
-      if (route.methods.includes(methodUpper) || route.methods.includes("UNKNOWN")) {
-        return {
-          matched: true,
-          route,
-          confidence: "high",
-          matchType: "exact",
-        };
-      }
-      // Path matches but method doesn't
-      if (allowMethodMismatch) {
-        return {
-          matched: true,
-          route,
-          confidence: "medium",
-          matchType: "path_only",
-          methodMismatch: true,
-        };
-      }
-    }
-  }
-
-  // Step 2: Dynamic match with specificity
-  const dynamicMatches = [];
-  
-  for (const route of serverRoutes) {
-    const regex = canonicalToRegex(route.canonicalPath);
-    if (regex.test(normalizedPath)) {
-      const methodMatches = route.methods.includes(methodUpper) || 
-                           route.methods.includes("UNKNOWN") ||
-                           route.methods.includes("*");
-      
-      dynamicMatches.push({
-        route,
-        specificity: calculateSpecificity(route.canonicalPath),
-        methodMatches,
-      });
-    }
-  }
-
-  if (dynamicMatches.length > 0) {
-    // Sort by specificity (descending), then method match
-    dynamicMatches.sort((a, b) => {
-      if (a.methodMatches !== b.methodMatches) {
-        return a.methodMatches ? -1 : 1;
-      }
-      return b.specificity - a.specificity;
-    });
-
-    const best = dynamicMatches[0];
-    return {
-      matched: true,
-      route: best.route,
-      confidence: best.methodMatches ? "high" : "medium",
-      matchType: "dynamic",
-      specificity: best.specificity,
-      methodMismatch: !best.methodMatches,
-    };
-  }
-
-  // Step 3: Check rewrites (Next.js)
-  for (const rewrite of considerRewrites) {
-    if (matchesGlob(normalizedPath, rewrite.source)) {
-      return {
-        matched: true,
-        route: null,
-        confidence: "low",
-        matchType: "rewrite",
-        rewrite,
-        isExternal: rewrite.isExternal,
-      };
-    }
-  }
-
-  // No match
-  return {
-    matched: false,
-    route: null,
-    confidence: "high", // High confidence it doesn't exist
-    matchType: "none",
-  };
-}
-
-/**
- * Match a glob pattern (simple implementation)
- */
-function matchesGlob(path, pattern) {
-  const regex = new RegExp(
-    "^" + pattern
-      .replace(/\*/g, ".*")
-      .replace(/\//g, "\\/")
-    + "$"
-  );
-  return regex.test(path);
-}
-
-/**
- * Find all routes that match a path (for debugging/reporting)
- */
-function findAllMatches(normalizedPath, method, serverRoutes) {
-  const matches = [];
-  const methodUpper = method?.toUpperCase() || "UNKNOWN";
-
-  for (const route of serverRoutes) {
-    // Check exact match
-    if (route.canonicalPath === normalizedPath || route.path === normalizedPath) {
-      matches.push({
-        route,
-        matchType: "exact",
-        methodMatches: route.methods.includes(methodUpper),
-        specificity: calculateSpecificity(route.canonicalPath),
-      });
-      continue;
-    }
-
-    // Check dynamic match
-    const regex = canonicalToRegex(route.canonicalPath);
-    if (regex.test(normalizedPath)) {
-      matches.push({
-        route,
-        matchType: "dynamic",
-        methodMatches: route.methods.includes(methodUpper) || route.methods.includes("UNKNOWN"),
-        specificity: calculateSpecificity(route.canonicalPath),
-      });
-    }
-  }
-
-  // Sort by specificity
-  matches.sort((a, b) => b.specificity - a.specificity);
-
-  return matches;
-}
-
-/**
- * Confidence matrix for missing route severity
- * 
- * Returns: "BLOCK" | "WARN" | "INFO"
- */
-function getMissingRouteSeverity(options = {}) {
-  const {
-    framework = "unknown",
-    staticConfidence = "medium",
-    hasRuntimeProof = false,
-    runtimeResult = null, // "404" | "405" | "2xx" | null
-    isRewriteTarget = false,
-    isCriticalPath = false,
-  } = options;
-
-  // Runtime beats static
-  if (hasRuntimeProof) {
-    if (runtimeResult === "404" || runtimeResult === "405") {
-      return "BLOCK"; // Confirmed missing
-    }
-    if (runtimeResult === "2xx") {
-      return "INFO"; // Actually exists (dynamic registration)
-    }
-  }
-
-  // Rewrite targets get WARN unless runtime confirms
-  if (isRewriteTarget) {
-    return "WARN";
-  }
-
-  // Next.js filesystem routes are high confidence
-  if (framework === "next" && staticConfidence === "high") {
-    return isCriticalPath ? "BLOCK" : "WARN";
-  }
-
-  // Fastify with low confidence (dynamic routes possible)
-  if (framework === "fastify" && staticConfidence === "low") {
-    return "WARN";
-  }
-
-  // Default: BLOCK for high confidence, WARN for medium/low
-  if (staticConfidence === "high") {
-    return "BLOCK";
-  }
-
-  return "WARN";
-}
-
-/**
- * Check if a path is a critical path (checkout, auth, payment)
- */
-function isCriticalPath(path) {
-  const criticalPatterns = [
-    /\/checkout/i,
-    /\/pay/i,
-    /\/login/i,
-    /\/auth/i,
-    /\/register/i,
-    /\/signup/i,
-    /\/billing/i,
-    /\/subscription/i,
-    /\/save/i,
-    /\/submit/i,
-    /\/order/i,
-    /\/purchase/i,
-  ];
-
-  return criticalPatterns.some(p => p.test(path));
-}
-
-/**
- * Build a route index for fast lookups
- */
-class RouteIndex {
-  constructor(routes = []) {
-    this.routes = routes;
-    this.exactIndex = new Map(); // path -> routes
-    this.methodIndex = new Map(); // method -> routes
-  }
-
-  add(route) {
-    this.routes.push(route);
-    
-    // Index by canonical path
-    if (!this.exactIndex.has(route.canonicalPath)) {
-      this.exactIndex.set(route.canonicalPath, []);
-    }
-    this.exactIndex.get(route.canonicalPath).push(route);
-
-    // Index by method
-    for (const method of route.methods) {
-      if (!this.methodIndex.has(method)) {
-        this.methodIndex.set(method, []);
-      }
-      this.methodIndex.get(method).push(route);
-    }
-  }
-
-  findExact(path) {
-    return this.exactIndex.get(path) || [];
-  }
-
-  findByMethod(method) {
-    return this.methodIndex.get(method.toUpperCase()) || [];
-  }
-
-  match(normalizedPath, method, options = {}) {
-    return matchRoute(normalizedPath, method, this.routes, options);
-  }
-
-  findAll(normalizedPath, method) {
-    return findAllMatches(normalizedPath, method, this.routes);
-  }
-}
-
-module.exports = {
-  normalizeUrl,
-  toCanonicalPath,
-  canonicalToRegex,
-  calculateSpecificity,
-  matchRoute,
-  matchesGlob,
-  findAllMatches,
-  getMissingRouteSeverity,
-  isCriticalPath,
-  RouteIndex,
-};
+/**
+ * Route Matcher v2
+ * 
+ * Canonical normalization and route matching algorithm.
+ * Handles path normalization, specificity scoring, and method matching.
+ * 
+ * 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 { URL } = require("url");
+
+/**
+ * Normalize a URL or path for matching
+ * 
+ * Steps:
+ * 1. Strip scheme + host if present
+ * 2. Remove query + fragment
+ * 3. Decode safe characters
+ * 4. Collapse multiple slashes
+ * 5. Apply basePath handling
+ * 6. Handle trailingSlash policy
+ */
+function normalizeUrl(urlOrPath, options = {}) {
+  const { basePath = "", trailingSlash = false } = options;
+  
+  let normalized = urlOrPath;
+
+  // Strip scheme + host if it's a full URL
+  if (normalized.startsWith("http://") || normalized.startsWith("https://")) {
+    try {
+      const url = new URL(normalized);
+      normalized = url.pathname;
+    } catch {
+      // Invalid URL, treat as path
+    }
+  }
+
+  // Remove query string and fragment
+  normalized = normalized.split("?")[0].split("#")[0];
+
+  // Decode URI components
+  try {
+    normalized = decodeURIComponent(normalized);
+  } catch {
+    // Invalid encoding, keep as-is
+  }
+
+  // Collapse multiple slashes
+  normalized = normalized.replace(/\/+/g, "/");
+
+  // Ensure leading slash
+  if (!normalized.startsWith("/")) {
+    normalized = "/" + normalized;
+  }
+
+  // Strip basePath if present
+  if (basePath && normalized.startsWith(basePath)) {
+    normalized = normalized.slice(basePath.length) || "/";
+  }
+
+  // Handle trailing slash
+  if (!trailingSlash && normalized.length > 1) {
+    normalized = normalized.replace(/\/$/, "");
+  }
+
+  return normalized;
+}
+
+/**
+ * Convert any path format to canonical format
+ * 
+ * Input formats:
+ * - Next.js: [id], [...slug], [[...slug]]
+ * - Fastify: :id, :path*, /*
+ * - Express: :id, :path(*)
+ * 
+ * Output format:
+ * - Params: {id}
+ * - Catch-all: {*slug}
+ * - Optional catch-all: {*slug?}
+ */
+function toCanonicalPath(rawPath, framework = "auto") {
+  let canonical = rawPath;
+
+  // Next.js conversions
+  canonical = canonical
+    // Optional catch-all [[...slug]]
+    .replace(/\[\[\.\.\.([^\]]+)\]\]/g, "{*$1?}")
+    // Catch-all [...slug]
+    .replace(/\[\.\.\.([^\]]+)\]/g, "{*$1}")
+    // Dynamic segment [id]
+    .replace(/\[([^\]]+)\]/g, "{$1}")
+    // Route groups (group) - remove
+    .replace(/\/\([^)]+\)/g, "")
+    // Parallel routes @slot - remove
+    .replace(/\/@[^/]+/g, "");
+
+  // Fastify/Express conversions
+  canonical = canonical
+    // Wildcard catch-all /*
+    .replace(/\/\*$/, "/{*path}")
+    // Named wildcard :path*
+    .replace(/:(\w+)\*/g, "{*$1}")
+    // Named param :id
+    .replace(/:(\w+)/g, "{$1}");
+
+  // Clean up
+  canonical = canonical
+    .replace(/\/+/g, "/")
+    .replace(/(.)\/$/, "$1");
+
+  // Ensure leading slash
+  if (!canonical.startsWith("/")) {
+    canonical = "/" + canonical;
+  }
+
+  return canonical;
+}
+
+/**
+ * Convert canonical path to regex for matching
+ */
+function canonicalToRegex(canonicalPath) {
+  let pattern = canonicalPath
+    // Escape regex special chars (except our placeholders)
+    .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+    // Optional catch-all {*slug?}
+    .replace(/\\\{\\\*(\w+)\?\\\}/g, "(?:/.*)?")
+    // Required catch-all {*slug}
+    .replace(/\\\{\\\*(\w+)\\\}/g, "/.+")
+    // Named param {id}
+    .replace(/\\\{(\w+)\\\}/g, "[^/]+");
+
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Calculate specificity score for a route
+ * Higher score = more specific = better match
+ * 
+ * Scoring:
+ * - Static segment: +10
+ * - Named param: +5
+ * - Catch-all: +1
+ * - Optional catch-all: +0
+ */
+function calculateSpecificity(canonicalPath) {
+  const segments = canonicalPath.split("/").filter(Boolean);
+  let score = 0;
+
+  for (const segment of segments) {
+    if (segment.startsWith("{*") && segment.endsWith("?}")) {
+      // Optional catch-all
+      score += 0;
+    } else if (segment.startsWith("{*")) {
+      // Required catch-all
+      score += 1;
+    } else if (segment.startsWith("{")) {
+      // Named param
+      score += 5;
+    } else {
+      // Static segment
+      score += 10;
+    }
+  }
+
+  return score;
+}
+
+/**
+ * Match a client call path against server routes
+ * 
+ * Algorithm:
+ * 1. Exact match (method + path)
+ * 2. Dynamic match with specificity scoring
+ * 3. Method fallback (UNKNOWN or wildcard)
+ * 
+ * Returns: { matched: boolean, route: Route | null, confidence: string, matchType: string }
+ */
+function matchRoute(normalizedPath, method, serverRoutes, options = {}) {
+  const { allowMethodMismatch = false, considerRewrites = [] } = options;
+  const methodUpper = method?.toUpperCase() || "UNKNOWN";
+
+  // Step 1: Exact match
+  for (const route of serverRoutes) {
+    if (route.canonicalPath === normalizedPath || route.path === normalizedPath) {
+      if (route.methods.includes(methodUpper) || route.methods.includes("UNKNOWN")) {
+        return {
+          matched: true,
+          route,
+          confidence: "high",
+          matchType: "exact",
+        };
+      }
+      // Path matches but method doesn't
+      if (allowMethodMismatch) {
+        return {
+          matched: true,
+          route,
+          confidence: "medium",
+          matchType: "path_only",
+          methodMismatch: true,
+        };
+      }
+    }
+  }
+
+  // Step 2: Dynamic match with specificity
+  const dynamicMatches = [];
+  
+  for (const route of serverRoutes) {
+    const regex = canonicalToRegex(route.canonicalPath);
+    if (regex.test(normalizedPath)) {
+      const methodMatches = route.methods.includes(methodUpper) || 
+                           route.methods.includes("UNKNOWN") ||
+                           route.methods.includes("*");
+      
+      dynamicMatches.push({
+        route,
+        specificity: calculateSpecificity(route.canonicalPath),
+        methodMatches,
+      });
+    }
+  }
+
+  if (dynamicMatches.length > 0) {
+    // Sort by specificity (descending), then method match
+    dynamicMatches.sort((a, b) => {
+      if (a.methodMatches !== b.methodMatches) {
+        return a.methodMatches ? -1 : 1;
+      }
+      return b.specificity - a.specificity;
+    });
+
+    const best = dynamicMatches[0];
+    return {
+      matched: true,
+      route: best.route,
+      confidence: best.methodMatches ? "high" : "medium",
+      matchType: "dynamic",
+      specificity: best.specificity,
+      methodMismatch: !best.methodMatches,
+    };
+  }
+
+  // Step 3: Check rewrites (Next.js)
+  for (const rewrite of considerRewrites) {
+    if (matchesGlob(normalizedPath, rewrite.source)) {
+      return {
+        matched: true,
+        route: null,
+        confidence: "low",
+        matchType: "rewrite",
+        rewrite,
+        isExternal: rewrite.isExternal,
+      };
+    }
+  }
+
+  // No match
+  return {
+    matched: false,
+    route: null,
+    confidence: "high", // High confidence it doesn't exist
+    matchType: "none",
+  };
+}
+
+/**
+ * Match a glob pattern (simple implementation)
+ */
+function matchesGlob(path, pattern) {
+  const regex = new RegExp(
+    "^" + pattern
+      .replace(/\*/g, ".*")
+      .replace(/\//g, "\\/")
+    + "$"
+  );
+  return regex.test(path);
+}
+
+/**
+ * Find all routes that match a path (for debugging/reporting)
+ */
+function findAllMatches(normalizedPath, method, serverRoutes) {
+  const matches = [];
+  const methodUpper = method?.toUpperCase() || "UNKNOWN";
+
+  for (const route of serverRoutes) {
+    // Check exact match
+    if (route.canonicalPath === normalizedPath || route.path === normalizedPath) {
+      matches.push({
+        route,
+        matchType: "exact",
+        methodMatches: route.methods.includes(methodUpper),
+        specificity: calculateSpecificity(route.canonicalPath),
+      });
+      continue;
+    }
+
+    // Check dynamic match
+    const regex = canonicalToRegex(route.canonicalPath);
+    if (regex.test(normalizedPath)) {
+      matches.push({
+        route,
+        matchType: "dynamic",
+        methodMatches: route.methods.includes(methodUpper) || route.methods.includes("UNKNOWN"),
+        specificity: calculateSpecificity(route.canonicalPath),
+      });
+    }
+  }
+
+  // Sort by specificity
+  matches.sort((a, b) => b.specificity - a.specificity);
+
+  return matches;
+}
+
+/**
+ * Confidence matrix for missing route severity
+ * 
+ * Returns: "BLOCK" | "WARN" | "INFO"
+ */
+function getMissingRouteSeverity(options = {}) {
+  const {
+    framework = "unknown",
+    staticConfidence = "medium",
+    hasRuntimeProof = false,
+    runtimeResult = null, // "404" | "405" | "2xx" | null
+    isRewriteTarget = false,
+    isCriticalPath = false,
+  } = options;
+
+  // Runtime beats static
+  if (hasRuntimeProof) {
+    if (runtimeResult === "404" || runtimeResult === "405") {
+      return "BLOCK"; // Confirmed missing
+    }
+    if (runtimeResult === "2xx") {
+      return "INFO"; // Actually exists (dynamic registration)
+    }
+  }
+
+  // Rewrite targets get WARN unless runtime confirms
+  if (isRewriteTarget) {
+    return "WARN";
+  }
+
+  // Next.js filesystem routes are high confidence
+  if (framework === "next" && staticConfidence === "high") {
+    return isCriticalPath ? "BLOCK" : "WARN";
+  }
+
+  // Fastify with low confidence (dynamic routes possible)
+  if (framework === "fastify" && staticConfidence === "low") {
+    return "WARN";
+  }
+
+  // Default: BLOCK for high confidence, WARN for medium/low
+  if (staticConfidence === "high") {
+    return "BLOCK";
+  }
+
+  return "WARN";
+}
+
+/**
+ * Check if a path is a critical path (checkout, auth, payment)
+ */
+function isCriticalPath(path) {
+  const criticalPatterns = [
+    /\/checkout/i,
+    /\/pay/i,
+    /\/login/i,
+    /\/auth/i,
+    /\/register/i,
+    /\/signup/i,
+    /\/billing/i,
+    /\/subscription/i,
+    /\/save/i,
+    /\/submit/i,
+    /\/order/i,
+    /\/purchase/i,
+  ];
+
+  return criticalPatterns.some(p => p.test(path));
+}
+
+/**
+ * Build a route index for fast lookups
+ */
+class RouteIndex {
+  constructor(routes = []) {
+    this.routes = routes;
+    this.exactIndex = new Map(); // path -> routes
+    this.methodIndex = new Map(); // method -> routes
+  }
+
+  add(route) {
+    this.routes.push(route);
+    
+    // Index by canonical path
+    if (!this.exactIndex.has(route.canonicalPath)) {
+      this.exactIndex.set(route.canonicalPath, []);
+    }
+    this.exactIndex.get(route.canonicalPath).push(route);
+
+    // Index by method
+    for (const method of route.methods) {
+      if (!this.methodIndex.has(method)) {
+        this.methodIndex.set(method, []);
+      }
+      this.methodIndex.get(method).push(route);
+    }
+  }
+
+  findExact(path) {
+    return this.exactIndex.get(path) || [];
+  }
+
+  findByMethod(method) {
+    return this.methodIndex.get(method.toUpperCase()) || [];
+  }
+
+  match(normalizedPath, method, options = {}) {
+    return matchRoute(normalizedPath, method, this.routes, options);
+  }
+
+  findAll(normalizedPath, method) {
+    return findAllMatches(normalizedPath, method, this.routes);
+  }
+}
+
+module.exports = {
+  normalizeUrl,
+  toCanonicalPath,
+  canonicalToRegex,
+  calculateSpecificity,
+  matchRoute,
+  matchesGlob,
+  findAllMatches,
+  getMissingRouteSeverity,
+  isCriticalPath,
+  RouteIndex,
+};