@vibecheckai/cli 3.3.0 → 3.5.0

package/bin/runners/lib/engines/api-consistency-engine.js

@@ -1,12 +1,161 @@
 /**
  * API Consistency Engine
- * Checks API route consistency, response formats, error handling patterns
+ * Enhanced with:
+ * - REST convention checking (HTTP methods, response codes)
+ * - Response shape consistency
+ * - Input validation detection
+ * - Error response format standardization
+ * - CORS and security header detection
+ * - Rate limiting indicators
+ * - API versioning patterns
  */
 
 const { getAST } = require("./ast-cache");
 const traverse = require("@babel/traverse").default;
 const t = require("@babel/types");
 
+/**
+ * HTTP method best practices
+ */
+const HTTP_METHOD_EXPECTATIONS = {
+  GET: {
+    shouldHaveBody: false,
+    typicalStatusCodes: [200, 404],
+    description: "Retrieve data",
+  },
+  POST: {
+    shouldHaveBody: true,
+    typicalStatusCodes: [201, 400, 409],
+    description: "Create resource",
+  },
+  PUT: {
+    shouldHaveBody: true,
+    typicalStatusCodes: [200, 204, 404],
+    description: "Replace resource",
+  },
+  PATCH: {
+    shouldHaveBody: true,
+    typicalStatusCodes: [200, 204, 404],
+    description: "Update resource partially",
+  },
+  DELETE: {
+    shouldHaveBody: false,
+    typicalStatusCodes: [204, 404],
+    description: "Remove resource",
+  },
+};
+
+/**
+ * Common response wrapper patterns
+ */
+const RESPONSE_WRAPPER_PATTERNS = [
+  { pattern: /\{\s*data\s*:/, name: "data" },
+  { pattern: /\{\s*result\s*:/, name: "result" },
+  { pattern: /\{\s*payload\s*:/, name: "payload" },
+  { pattern: /\{\s*response\s*:/, name: "response" },
+  { pattern: /\{\s*body\s*:/, name: "body" },
+  { pattern: /\{\s*message\s*:/, name: "message" },
+  { pattern: /\{\s*error\s*:/, name: "error" },
+  { pattern: /\{\s*success\s*:/, name: "success" },
+];
+
+/**
+ * Detect HTTP method from file or code
+ */
+function detectHTTPMethod(code, filePath) {
+  const methods = new Set();
+  
+  // Next.js App Router pattern: export function GET/POST/etc
+  const appRouterMatch = code.match(/export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/g);
+  if (appRouterMatch) {
+    appRouterMatch.forEach(m => {
+      const method = m.match(/(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)/)[1];
+      methods.add(method);
+    });
+  }
+  
+  // Express pattern: app.get/post/etc or router.get/post/etc
+  const expressMatch = code.match(/\.(get|post|put|patch|delete|head|options)\s*\(/gi);
+  if (expressMatch) {
+    expressMatch.forEach(m => {
+      const method = m.match(/\.(get|post|put|patch|delete|head|options)/i)[1].toUpperCase();
+      methods.add(method);
+    });
+  }
+  
+  // Next.js Pages Router pattern
+  if (/req\.method\s*===?\s*['"](\w+)['"]/g.test(code)) {
+    const methodMatch = code.match(/req\.method\s*===?\s*['"](\w+)['"]/g);
+    methodMatch?.forEach(m => {
+      const method = m.match(/['"](\w+)['"]/)[1].toUpperCase();
+      methods.add(method);
+    });
+  }
+  
+  return methods;
+}
+
+/**
+ * Check for input validation
+ */
+function hasInputValidation(code) {
+  const validationPatterns = [
+    /\bzod\b/,
+    /\byup\b/,
+    /\bjoi\b/,
+    /\bvalidate\s*\(/i,
+    /\bschema\s*\.\s*parse/,
+    /\bschema\s*\.\s*safeParse/,
+    /\.input\s*\(/,   // tRPC input
+    /\bz\s*\.\s*object/,
+    /\bz\s*\.\s*string/,
+    /\bvalidateBody/i,
+    /\brequestSchema/i,
+    /\bbodySchema/i,
+  ];
+  
+  return validationPatterns.some(p => p.test(code));
+}
+
+/**
+ * Check for authentication
+ */
+function hasAuthentication(code) {
+  const authPatterns = [
+    /getServerSession/,
+    /getSession/,
+    /auth\s*\(\)/,
+    /verifyToken/,
+    /authenticate/i,
+    /authorization/i,
+    /protectedProcedure/,
+    /withAuth/i,
+    /requireAuth/i,
+    /isAuthenticated/i,
+    /bearer/i,
+    /jwt/i,
+  ];
+  
+  return authPatterns.some(p => p.test(code));
+}
+
+/**
+ * Check for rate limiting
+ */
+function hasRateLimiting(code) {
+  const rateLimitPatterns = [
+    /rateLimit/i,
+    /rateLimiter/i,
+    /throttle/i,
+    /X-RateLimit/i,
+    /upstash.*ratelimit/i,
+    /@upstash\/ratelimit/,
+    /limiter\./i,
+  ];
+  
+  return rateLimitPatterns.some(p => p.test(code));
+}
+
 /**
  * Analyze API consistency issues
  */
@@ -16,13 +165,23 @@ function analyzeAPIConsistency(code, filePath) {
   if (!ast) return findings;
 
   const lines = code.split("\n");
-  const isAPIRoute = filePath.includes("/api/") || filePath.includes("/routes/");
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const isAPIRoute = normalizedPath.includes("/api/") || 
+                     normalizedPath.includes("/routes/") ||
+                     normalizedPath.match(/\/route\.(ts|js)$/);
 
   if (!isAPIRoute) return findings;
 
   const responseFormats = new Set();
   const errorHandlingPatterns = new Set();
+  const statusCodesUsed = new Set();
+  const responseWrappers = new Set();
   let hasErrorHandler = false;
+  let readsRequestBody = false;
+  let hasContentTypeCheck = false;
+
+  // Detect HTTP methods
+  const httpMethods = detectHTTPMethod(code, filePath);
 
   traverse(ast, {
     // Check response formats
@@ -32,18 +191,39 @@ function analyzeAPIConsistency(code, filePath) {
       // Next.js API routes
       if (t.isMemberExpression(node.callee) && 
           t.isIdentifier(node.callee.object, { name: "NextResponse" })) {
-        const method = node.callee.property.name;
+        const method = node.callee.property?.name;
         if (["json", "redirect", "next"].includes(method)) {
           responseFormats.add(`NextResponse.${method}`);
         }
+        
+        // Check response wrapper in NextResponse.json()
+        if (method === "json" && node.arguments[0]) {
+          const arg = node.arguments[0];
+          if (t.isObjectExpression(arg)) {
+            arg.properties.forEach(prop => {
+              if (t.isObjectProperty(prop) && t.isIdentifier(prop.key)) {
+                responseWrappers.add(prop.key.name);
+              }
+            });
+          }
+        }
       }
       
       // Express-style responses
       if (t.isMemberExpression(node.callee)) {
         const prop = node.callee.property;
-        if (t.isIdentifier(prop) && 
-            ["json", "send", "status", "redirect"].includes(prop.name)) {
-          responseFormats.add(`res.${prop.name}`);
+        if (t.isIdentifier(prop)) {
+          if (["json", "send", "status", "redirect"].includes(prop.name)) {
+            responseFormats.add(`res.${prop.name}`);
+          }
+          
+          // Track status codes
+          if (prop.name === "status" && node.arguments[0]) {
+            const statusArg = node.arguments[0];
+            if (t.isNumericLiteral(statusArg)) {
+              statusCodesUsed.add(statusArg.value);
+            }
+          }
         }
       }
       
@@ -53,6 +233,43 @@ function analyzeAPIConsistency(code, filePath) {
         hasErrorHandler = true;
         errorHandlingPatterns.add("promise.catch");
       }
+      
+      // Request body access
+      if (t.isMemberExpression(node.callee)) {
+        const obj = node.callee.object;
+        const prop = node.callee.property;
+        
+        // req.body, request.json(), etc.
+        if ((t.isIdentifier(obj, { name: "req" }) || t.isIdentifier(obj, { name: "request" })) &&
+            t.isIdentifier(prop) && ["body", "json"].includes(prop.name)) {
+          readsRequestBody = true;
+        }
+      }
+      
+      // Content-Type check
+      if (t.isMemberExpression(node.callee)) {
+        const callee = node.callee;
+        if (t.isIdentifier(callee.property, { name: "get" }) && 
+            node.arguments[0] && 
+            t.isStringLiteral(node.arguments[0]) &&
+            node.arguments[0].value.toLowerCase() === "content-type") {
+          hasContentTypeCheck = true;
+        }
+      }
+    },
+    
+    // Await request.json() also indicates body reading
+    AwaitExpression(path) {
+      const arg = path.node.argument;
+      if (t.isCallExpression(arg) && t.isMemberExpression(arg.callee)) {
+        const obj = arg.callee.object;
+        const prop = arg.callee.property;
+        if (t.isIdentifier(prop, { name: "json" }) || 
+            t.isIdentifier(prop, { name: "formData" }) ||
+            t.isIdentifier(prop, { name: "text" })) {
+          readsRequestBody = true;
+        }
+      }
     },
     
     // Try-catch blocks
@@ -67,7 +284,6 @@ function analyzeAPIConsistency(code, filePath) {
       if (t.isBinaryExpression(test) && 
           (test.operator === "===" || test.operator === "==")) {
         const left = test.left;
-        const right = test.right;
         
         // Check for error status checks
         if ((t.isMemberExpression(left) && 
@@ -98,18 +314,59 @@ function analyzeAPIConsistency(code, filePath) {
     },
   });
 
-  // Check for inconsistent response formats
-  if (responseFormats.size > 1) {
+  // REST convention checks
+  for (const method of httpMethods) {
+    const expectations = HTTP_METHOD_EXPECTATIONS[method];
+    if (!expectations) continue;
+    
+    // Check GET/DELETE with body
+    if (!expectations.shouldHaveBody && readsRequestBody) {
+      findings.push({
+        type: "rest_convention_violation",
+        severity: "WARN",
+        category: "APIConsistency",
+        file: filePath,
+        line: 1,
+        column: 0,
+        title: `${method} request should not have body`,
+        message: `REST convention: ${method} requests typically don't have a request body. Consider using query parameters instead.`,
+        confidence: "med",
+        fixHint: "Use query parameters (searchParams) instead of request body for GET requests",
+      });
+    }
+    
+    // Check POST/PUT/PATCH without body
+    if (expectations.shouldHaveBody && !readsRequestBody && method !== "DELETE") {
+      findings.push({
+        type: "rest_convention_violation",
+        severity: "INFO",
+        category: "APIConsistency",
+        file: filePath,
+        line: 1,
+        column: 0,
+        title: `${method} request without body`,
+        message: `${method} requests typically include a request body. This might be intentional for some endpoints.`,
+        confidence: "low",
+      });
+    }
+  }
+
+  // Check for inconsistent response wrappers
+  const dataWrappers = Array.from(responseWrappers).filter(w => 
+    ["data", "result", "payload", "response", "body"].includes(w)
+  );
+  if (dataWrappers.length > 1) {
     findings.push({
-      type: "inconsistent_response_format",
+      type: "inconsistent_response_wrapper",
       severity: "WARN",
       category: "APIConsistency",
       file: filePath,
       line: 1,
       column: 0,
-      title: "Inconsistent API response formats",
-      message: `Multiple response formats used: ${Array.from(responseFormats).join(", ")}`,
-      confidence: "low",
+      title: "Inconsistent response wrapper keys",
+      message: `Multiple response wrapper keys used: ${dataWrappers.join(", ")}. Standardize on one format.`,
+      confidence: "med",
+      fixHint: "Use a consistent wrapper like { data: ... } or { result: ... } across all endpoints",
     });
   }
 
@@ -123,34 +380,78 @@ function analyzeAPIConsistency(code, filePath) {
       line: 1,
       column: 0,
       title: "API route missing error handling",
-      message: "API route should have try-catch or promise error handling",
+      message: "API route should have try-catch or promise error handling to prevent unhandled exceptions",
       confidence: "med",
+      fixHint: "Wrap async logic in try-catch and return appropriate error responses",
     });
   }
 
-  // Check for missing status codes
-  let hasStatusCode = false;
-  traverse(ast, {
-    CallExpression(path) {
-      const node = path.node;
-      if (t.isMemberExpression(node.callee) && 
-          t.isIdentifier(node.callee.property, { name: "status" })) {
-        hasStatusCode = true;
-      }
-    },
-  });
-
-  if (!hasStatusCode && responseFormats.size > 0) {
+  // Check for missing input validation on POST/PUT/PATCH
+  const mutationMethods = ["POST", "PUT", "PATCH"];
+  const hasMutationMethod = mutationMethods.some(m => httpMethods.has(m));
+  
+  if (hasMutationMethod && readsRequestBody && !hasInputValidation(code)) {
     findings.push({
-      type: "missing_status_code",
+      type: "missing_input_validation",
       severity: "WARN",
       category: "APIConsistency",
       file: filePath,
       line: 1,
       column: 0,
-      title: "API response missing explicit status code",
-      message: "API responses should explicitly set HTTP status codes",
+      title: "API endpoint missing input validation",
+      message: "Mutation endpoints should validate request body. Consider using Zod, Yup, or similar.",
       confidence: "med",
+      fixHint: "Add schema validation: const body = schema.parse(await request.json())",
+    });
+  }
+
+  // Check for missing authentication on sensitive endpoints
+  const isSensitiveEndpoint = /\/(admin|user|account|settings|billing|payment)/i.test(normalizedPath);
+  if (isSensitiveEndpoint && !hasAuthentication(code)) {
+    findings.push({
+      type: "missing_authentication",
+      severity: "WARN",
+      category: "APIConsistency",
+      file: filePath,
+      line: 1,
+      column: 0,
+      title: "Sensitive endpoint may need authentication",
+      message: `Endpoint path suggests sensitive data (${normalizedPath}). Consider adding authentication.`,
+      confidence: "low",
+      fixHint: "Add authentication check: const session = await getServerSession()",
+    });
+  }
+
+  // Check for missing rate limiting on public endpoints
+  const isPublicEndpoint = /(public|webhook|auth\/.*login|auth\/.*register)/i.test(normalizedPath);
+  if (isPublicEndpoint && !hasRateLimiting(code)) {
+    findings.push({
+      type: "missing_rate_limiting",
+      severity: "INFO",
+      category: "APIConsistency",
+      file: filePath,
+      line: 1,
+      column: 0,
+      title: "Public endpoint without rate limiting",
+      message: "Public endpoints should consider rate limiting to prevent abuse",
+      confidence: "low",
+      fixHint: "Consider using @upstash/ratelimit or similar rate limiting solution",
+    });
+  }
+
+  // Check Content-Type validation for POST/PUT/PATCH
+  if (hasMutationMethod && readsRequestBody && !hasContentTypeCheck) {
+    // This is a low-priority check - most frameworks handle this
+    findings.push({
+      type: "missing_content_type_check",
+      severity: "INFO",
+      category: "APIConsistency",
+      file: filePath,
+      line: 1,
+      column: 0,
+      title: "No explicit Content-Type validation",
+      message: "Consider validating Content-Type header for request body endpoints",
+      confidence: "low",
     });
   }
 
@@ -159,4 +460,8 @@ function analyzeAPIConsistency(code, filePath) {
 
 module.exports = {
   analyzeAPIConsistency,
+  detectHTTPMethod,
+  hasInputValidation,
+  hasAuthentication,
+  hasRateLimiting,
 };