@vibecheckai/cli 3.0.4 → 3.0.7

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

@@ -0,0 +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,
+};