@qodfy/core 0.2.5 → 0.2.7

package/dist/index.d.ts

@@ -20,6 +20,7 @@ type Issue = {
     suggestion?: string;
     fixPrompt?: string;
     evidence?: IssueEvidence[];
+    context?: IssueEvidence[];
 };
 type ScanReport = {
     projectPath: string;

package/dist/index.js

@@ -287,6 +287,7 @@ async function scanProject(input) {
     if (statResult.size > MAX_FILE_SIZE_BYTES) {
       if (runMaintainabilityChecks) {
         largeFiles++;
+        const largeFileKind = getMaintainabilityFileKind(relativeFile);
         addIssue({
           ruleId: "maintainability-large-file-skipped",
           category: "maintainability",
@@ -296,7 +297,7 @@ async function scanProject(input) {
           message: "This file is larger than 500KB and was skipped from deep content checks.",
           file: relativeFile,
           suggestion: "Review large generated or bundled files manually.",
-          fixPrompt: createLargeFileFixPrompt(relativeFile)
+          fixPrompt: createLargeFileFixPrompt(relativeFile, largeFileKind)
         });
       }
       continue;
@@ -353,18 +354,10 @@ async function scanProject(input) {
       relativeFile,
       content
     }) : null;
-    if (runWebhookChecks && apiRouteAnalysis?.intent === "webhook" && !apiRouteAnalysis.hasWebhookVerification) {
-      addIssue({
-        ruleId: "webhook-missing-signature-verification",
-        category: "webhook",
-        severity: apiRouteAnalysis.confidence === "high" ? "critical" : "warning",
-        confidence: apiRouteAnalysis.confidence,
-        title: "Webhook route may be missing signature verification",
-        message: "This webhook route appears to handle external events, but Qodfy could not find signature verification before the event is handled.",
-        file: relativeFile,
-        suggestion: getWebhookSignatureSuggestion(apiRouteAnalysis.webhookProvider),
-        fixPrompt: createWebhookSignatureFixPrompt(relativeFile),
-        evidence: apiRouteAnalysis.evidence
+    if (runWebhookChecks && apiRouteAnalysis) {
+      addWebhookSignatureIssues({
+        addIssue,
+        analysis: apiRouteAnalysis
       });
     }
     if (runSecurityChecks) {
@@ -429,16 +422,18 @@ async function scanProject(input) {
     }
   }
   for (const largeFile of getReportedLargeFiles(largeFileCandidates)) {
+    const largeFileKind = getMaintainabilityFileKind(largeFile.relativeFile);
+    const largeFileCopy = getLargeFileIssueCopy(largeFileKind);
     addIssue({
       ruleId: "maintainability-large-file",
       category: "maintainability",
       severity: "info",
       confidence: "low",
-      title: "Large file detected",
-      message: "This file is larger than the recommended maintainability threshold. Large files can be harder to review, test, and safely modify.",
+      title: largeFileCopy.title,
+      message: largeFileCopy.message,
       file: largeFile.relativeFile,
-      suggestion: "Review whether this file mixes UI, state, data fetching, validation, or business logic. If so, split it into smaller components, hooks, or utilities.",
-      fixPrompt: createLargeFileFixPrompt(largeFile.relativeFile)
+      suggestion: largeFileCopy.suggestion,
+      fixPrompt: createLargeFileFixPrompt(largeFile.relativeFile, largeFileKind)
     });
   }
   for (const [variableName, filesUsingVariable] of getSortedMissingEnvUsages(missingEnvUsages)) {
@@ -723,95 +718,125 @@ function isApiRoute(filePath) {
   const sourceFileExtension = "(?:ts|tsx|js|jsx|mts|cts|mjs|cjs)";
   return new RegExp(`/app/api(?:/.+)?/route\\.${sourceFileExtension}$`).test(normalizedFile) || new RegExp(`/pages/api/.+\\.${sourceFileExtension}$`).test(normalizedFile);
 }
+function addWebhookSignatureIssues({
+  addIssue,
+  analysis
+}) {
+  for (const handler of analysis.handlers) {
+    if (handler.intent !== "webhook" || handler.hasWebhookVerification) {
+      continue;
+    }
+    addIssue({
+      ruleId: "webhook-missing-signature-verification",
+      category: "webhook",
+      severity: handler.confidence === "high" ? "critical" : "warning",
+      confidence: handler.confidence,
+      title: `Webhook ${handler.method} handler may be missing signature verification`,
+      message: `The ${handler.method} handler in this route appears to handle external events, but Qodfy could not find signature verification before the event is handled.`,
+      file: analysis.relativeFile,
+      suggestion: getWebhookSignatureSuggestion(analysis.webhookProvider),
+      fixPrompt: createWebhookSignatureFixPrompt(analysis.relativeFile, handler.method),
+      evidence: handler.evidence,
+      context: handler.context
+    });
+  }
+}
 function addApiRouteProtectionIssues({
   addIssue,
   includeLowConfidence,
   analysis
 }) {
-  if (analysis.intent === "webhook") {
-    return;
-  }
-  if (analysis.intent === "public-read") {
-    if (includeLowConfidence) {
-      addIssue({
-        ruleId: "api-public-read-route",
-        category: "api",
-        severity: "info",
-        confidence: analysis.confidence,
-        title: "Public read API route detected",
-        message: "This route appears intentionally public. Authentication may not be required.",
-        file: analysis.relativeFile,
-        suggestion: "Verify that it only exposes public or published data and has appropriate validation, caching, and abuse protection.",
-        fixPrompt: createPublicReadRouteFixPrompt(analysis.relativeFile),
-        evidence: analysis.evidence
-      });
+  for (const handler of analysis.handlers) {
+    if (handler.intent === "webhook") {
+      continue;
     }
-    return;
-  }
-  if (analysis.intent === "public-form") {
-    if (!analysis.hasRateLimit && !analysis.hasValidation) {
-      addIssue({
-        ruleId: "public-form-missing-abuse-protection",
-        category: "api",
-        severity: "warning",
-        confidence: analysis.confidence,
-        title: "Public form route may be missing abuse protection",
-        message: "This route appears to accept public submissions. Consider adding rate limiting, validation, or spam protection.",
-        file: analysis.relativeFile,
-        suggestion: "Check for rate limiting, validation, captcha, Turnstile, reCAPTCHA, hCaptcha, or another spam protection pattern.",
-        fixPrompt: createPublicFormProtectionFixPrompt(analysis.relativeFile),
-        evidence: analysis.evidence
-      });
+    if (handler.intent === "public-read") {
+      if (includeLowConfidence) {
+        addIssue({
+          ruleId: "api-public-read-route",
+          category: "api",
+          severity: "info",
+          confidence: handler.confidence,
+          title: `Public ${handler.method} handler detected`,
+          message: `The ${handler.method} handler in this route appears intentionally public. Authentication may not be required.`,
+          file: analysis.relativeFile,
+          suggestion: "Verify that it only exposes public or published data and has appropriate validation, caching, and abuse protection.",
+          fixPrompt: createPublicReadRouteFixPrompt(analysis.relativeFile, handler.method),
+          evidence: handler.evidence,
+          context: handler.context
+        });
+      }
+      continue;
     }
-    return;
-  }
-  if (analysis.intent === "internal") {
-    if (!analysis.hasAuth && !analysis.hasSecretProtection) {
-      addIssue({
-        ruleId: "internal-route-missing-protection",
-        category: "security",
-        severity: "warning",
-        confidence: analysis.confidence,
-        title: "Internal API route may be missing protection",
-        message: "This route appears internal or operational. Confirm it is protected by auth, a secret token, or server-only access.",
-        file: analysis.relativeFile,
-        suggestion: "Use the project's existing auth pattern or a secret token check for operational routes such as cron, cleanup, or revalidation.",
-        fixPrompt: createInternalRouteProtectionFixPrompt(analysis.relativeFile),
-        evidence: analysis.evidence
-      });
+    if (handler.intent === "public-form") {
+      if (!handler.hasRateLimit && !handler.hasValidation) {
+        addIssue({
+          ruleId: "public-form-missing-abuse-protection",
+          category: "api",
+          severity: "warning",
+          confidence: handler.confidence,
+          title: `Public form ${handler.method} handler may be missing abuse protection`,
+          message: `The ${handler.method} handler in this route appears to accept public submissions. Consider adding rate limiting, validation, or spam protection.`,
+          file: analysis.relativeFile,
+          suggestion: "Check for rate limiting, validation, captcha, Turnstile, reCAPTCHA, hCaptcha, or another spam protection pattern.",
+          fixPrompt: createPublicFormProtectionFixPrompt(analysis.relativeFile, handler.method),
+          evidence: handler.evidence,
+          context: handler.context
+        });
+      }
+      continue;
     }
-    return;
-  }
-  if (analysis.intent === "sensitive-mutation") {
-    if (!analysis.hasAuth) {
+    if (handler.intent === "internal") {
+      if (!handler.hasAuth && !handler.hasSecretProtection) {
+        addIssue({
+          ruleId: "internal-route-missing-protection",
+          category: "security",
+          severity: "warning",
+          confidence: handler.confidence,
+          title: `Internal ${handler.method} handler may be missing protection`,
+          message: `The ${handler.method} handler in this route appears internal or operational. Confirm it is protected by auth, a secret token, or server-only access.`,
+          file: analysis.relativeFile,
+          suggestion: "Use the project's existing auth pattern or a secret token check for operational handlers such as cron, cleanup, or revalidation.",
+          fixPrompt: createInternalRouteProtectionFixPrompt(analysis.relativeFile, handler.method),
+          evidence: handler.evidence,
+          context: handler.context
+        });
+      }
+      continue;
+    }
+    if (handler.intent === "sensitive-mutation") {
+      if (!handler.hasAuth) {
+        addIssue({
+          ruleId: "sensitive-api-route-missing-auth",
+          category: "security",
+          severity: "warning",
+          confidence: handler.confidence,
+          title: getSensitiveHandlerTitle(handler),
+          message: `The ${handler.method} handler in this route appears to handle uploads or sensitive operations. Confirm it is protected before launch.`,
+          file: analysis.relativeFile,
+          suggestion: "Review the existing project auth/session pattern and apply it if this handler processes private data, uploads, payments, or account changes.",
+          fixPrompt: createApiAuthFixPrompt(analysis.relativeFile, handler.method, handler.intent),
+          evidence: handler.evidence,
+          context: handler.context
+        });
+      }
+      continue;
+    }
+    if (handler.authExpected === "review" && !handler.hasAuth) {
       addIssue({
-        ruleId: "sensitive-api-route-missing-auth",
-        category: "security",
+        ruleId: "api-mutation-route-review-auth",
+        category: "api",
         severity: "warning",
-        confidence: analysis.confidence,
-        title: "Sensitive API route may be missing authentication",
-        message: "This route appears to handle user-specific or sensitive operations. Confirm it is protected before launch.",
+        confidence: handler.confidence,
+        title: "API mutation handler should be reviewed for authentication",
+        message: `The ${handler.method} handler mutates data or handles requests, but Qodfy could not determine whether authentication is required.`,
         file: analysis.relativeFile,
-        suggestion: "Review the existing project auth/session pattern and apply it if this route handles private data, uploads, payments, or account changes.",
-        fixPrompt: createApiAuthFixPrompt(analysis.relativeFile),
-        evidence: analysis.evidence
+        suggestion: "Confirm the handler is intentionally public, or add the existing project auth/session check before handling private data.",
+        fixPrompt: createApiAuthFixPrompt(analysis.relativeFile, handler.method, handler.intent),
+        evidence: handler.evidence,
+        context: handler.context
       });
     }
-    return;
-  }
-  if (analysis.authExpected === "review" && !analysis.hasAuth) {
-    addIssue({
-      ruleId: "api-mutation-route-review-auth",
-      category: "api",
-      severity: "warning",
-      confidence: analysis.confidence,
-      title: "API mutation route should be reviewed for authentication",
-      message: "This route mutates data or handles requests, but Qodfy could not determine whether authentication is required.",
-      file: analysis.relativeFile,
-      suggestion: "Confirm the route is intentionally public, or add the existing project auth/session check before handling private data.",
-      fixPrompt: createApiAuthFixPrompt(analysis.relativeFile),
-      evidence: analysis.evidence
-    });
   }
 }
 function analyzeApiRoute({
@@ -819,25 +844,44 @@ function analyzeApiRoute({
   relativeFile,
   content
 }) {
-  const normalizedFile = relativeFile.toLowerCase();
-  const methods = getRouteHttpMethods(content);
-  const evidence = [];
-  const webhookRouteInfo = getWebhookRouteInfo(relativeFile, content);
-  const hasAuth = hasAuthOrSessionCheck(content);
-  const hasSecretProtection = hasSecretProtectionSignal(content);
-  const hasRateLimit = hasRateLimitSignal(content);
-  const hasValidation = hasValidationSignal(content);
-  const hasCacheHeaders = hasCacheHeaderSignal(content);
-  const hasMethodBlocking = hasMethodBlockingSignal(content);
-  const webhookProvider = webhookRouteInfo?.provider ?? "unknown";
-  const hasWebhookVerification = hasWebhookSignatureVerification(content, webhookProvider);
-  if (methods.length > 0) {
-    for (const method of methods) {
-      evidence.push({ label: "exports", detail: method });
-    }
-  } else {
-    evidence.push({ label: "no exported HTTP method detected" });
+  const exportedHandlers = getExportedRouteHandlers(content);
+  const handlersToAnalyze = exportedHandlers.length > 0 ? exportedHandlers : getRouteHttpMethods(content).map((method) => ({
+    method,
+    body: content,
+    usedFallbackBody: true
+  }));
+  const handlers = handlersToAnalyze.map(
+    (handler) => analyzeApiHandler({
+      relativeFile,
+      content,
+      method: handler.method,
+      body: handler.body,
+      usedFallbackBody: handler.usedFallbackBody
+    })
+  );
+  for (const handler of handlers) {
+    handler.context = getHandlerContext(handler, handlers);
   }
+  const methods = handlers.map((handler) => handler.method);
+  const webhookProvider = getRouteWebhookProvider(handlers, relativeFile, content);
+  return {
+    file,
+    relativeFile,
+    methods,
+    handlers,
+    routeIntent: getRouteIntent(handlers),
+    evidence: methods.map((method) => ({ label: "exports", detail: method })),
+    webhookProvider
+  };
+}
+function analyzeApiHandler({
+  relativeFile,
+  content,
+  method,
+  body,
+  usedFallbackBody
+}) {
+  const normalizedFile = relativeFile.toLowerCase();
   const webhookPathMatch = getRoutePathMatch(normalizedFile, ["webhook", "webhooks", "callback"]);
   const internalPathMatch = getRoutePathMatch(normalizedFile, ["internal", "admin", "cron", "cleanup", "revalidate", "private"]);
   const formPathMatch = getRoutePathMatch(normalizedFile, ["contact", "subscribe", "newsletter", "lead", "inquiry"]);
@@ -871,7 +915,22 @@ function analyzeApiRoute({
     "sitemap",
     "rss"
   ]);
+  const handlerContent = body || content;
+  const webhookRouteInfo = getWebhookRouteInfo(relativeFile, handlerContent);
+  const webhookProvider = webhookRouteInfo?.provider ?? getWebhookProvider(`${normalizedFile}
+${handlerContent.toLowerCase()}`);
+  const hasAuth = hasAuthOrSessionCheck(handlerContent);
+  const hasSecretProtection = hasSecretProtectionSignal(handlerContent);
+  const hasRateLimit = hasRateLimitSignal(handlerContent);
+  const hasValidation = hasValidationSignal(handlerContent);
+  const hasCacheHeaders = hasCacheHeaderSignal(handlerContent);
+  const hasMethodBlocking = hasMethodBlockingSignal(handlerContent);
+  const hasWebhookVerification = hasWebhookSignatureVerification(handlerContent, webhookProvider);
+  const evidence = [{ label: "exports", detail: method }];
   let intent = "unknown";
+  if (usedFallbackBody) {
+    evidence.push({ label: "handler body extraction fallback", detail: "using full file" });
+  }
   if (webhookRouteInfo || webhookPathMatch) {
     intent = "webhook";
     evidence.push({
@@ -881,54 +940,59 @@ function analyzeApiRoute({
   } else if (internalPathMatch) {
     intent = "internal";
     evidence.push({ label: "path contains", detail: internalPathMatch });
-  } else if (formPathMatch) {
+  } else if (method === "POST" && formPathMatch) {
     intent = "public-form";
     evidence.push({ label: "path contains", detail: formPathMatch });
-  } else if (hasMutationMethod(methods) && sensitivePathMatch) {
+  } else if (method === "GET" && publicContentPathMatch && !sensitivePathMatch && !internalPathMatch) {
+    intent = "public-read";
+    evidence.push({ label: "public read path detected", detail: publicContentPathMatch });
+  } else if (isMutationMethod(method) && sensitivePathMatch && !hasMethodBlocking) {
     intent = "sensitive-mutation";
     evidence.push({ label: "path contains", detail: sensitivePathMatch });
-  } else if (methods.includes("GET") && publicContentPathMatch && !sensitivePathMatch && !internalPathMatch) {
-    intent = "public-read";
-    evidence.push({ label: "public content route detected", detail: publicContentPathMatch });
   }
   if (hasAuth) {
-    evidence.push({ label: "auth/session check detected" });
+    evidence.push({ label: `auth/session check detected in ${method} handler` });
   } else {
-    evidence.push({ label: "no auth/session check detected" });
+    evidence.push({ label: `no auth/session check detected in ${method} handler` });
   }
   if (hasSecretProtection) {
-    evidence.push({ label: "secret token check detected" });
-  }
-  if (hasRateLimit) {
-    evidence.push({ label: "rate limit detected" });
-  } else if (intent === "public-form") {
-    evidence.push({ label: "no rate limit detected" });
+    evidence.push({ label: `secret token check detected in ${method} handler` });
   }
-  if (hasValidation) {
-    evidence.push({ label: "validation detected" });
-  } else if (intent === "public-form") {
-    evidence.push({ label: "no validation detected" });
+  if (intent === "public-form") {
+    evidence.push({
+      label: hasRateLimit ? "rate limit detected" : "no rate limit detected",
+      detail: `${method} handler`
+    });
+    evidence.push({
+      label: hasValidation ? "validation detected" : "no validation detected",
+      detail: `${method} handler`
+    });
   }
-  if (hasCacheHeaders) {
-    evidence.push({ label: "cache/public-read safety signal detected" });
+  if (intent === "public-read") {
+    if (hasRateLimit) {
+      evidence.push({ label: "rate limit detected", detail: `${method} handler` });
+    }
+    if (hasValidation) {
+      evidence.push({ label: "validation detected", detail: `${method} handler` });
+    }
+    if (hasCacheHeaders) {
+      evidence.push({ label: "cache/public-read safety signal detected", detail: `${method} handler` });
+    }
   }
   if (hasMethodBlocking) {
-    evidence.push({ label: "method blocking detected" });
+    evidence.push({ label: "method blocking detected", detail: `${method} handler` });
   }
   if (intent === "webhook") {
-    if (hasWebhookVerification) {
-      evidence.push({ label: "webhook signature verification detected" });
-    } else {
-      evidence.push({ label: "no webhook signature verification detected" });
-    }
+    evidence.push({
+      label: hasWebhookVerification ? "webhook signature verification detected" : "no webhook signature verification detected",
+      detail: `${method} handler`
+    });
   }
   return {
-    file,
-    relativeFile,
-    methods,
+    method,
     intent,
-    authExpected: getAuthExpectation(intent, methods),
-    confidence: getApiRouteConfidence(intent, methods, webhookRouteInfo),
+    authExpected: getHandlerAuthExpectation(intent, method, hasMethodBlocking),
+    confidence: getApiHandlerConfidence(intent, method, webhookRouteInfo, hasMethodBlocking),
     evidence,
     hasAuth,
     hasSecretProtection,
@@ -936,31 +1000,89 @@ function analyzeApiRoute({
     hasValidation,
     hasCacheHeaders,
     hasMethodBlocking,
-    hasWebhookVerification,
-    webhookProvider
+    hasWebhookVerification
   };
 }
-function getAuthExpectation(intent, methods) {
+function getHandlerContext(handler, handlers) {
+  const context = [];
+  for (const otherHandler of handlers) {
+    if (otherHandler.method === handler.method) {
+      continue;
+    }
+    context.push({ label: "route also exports", detail: otherHandler.method });
+    if (otherHandler.intent === "public-read") {
+      context.push({ label: "public read handler detected", detail: otherHandler.method });
+    }
+    if (otherHandler.hasCacheHeaders) {
+      context.push({ label: "cache/public-read safety signal detected", detail: `${otherHandler.method} handler` });
+    }
+    if (otherHandler.hasMethodBlocking) {
+      context.push({ label: "method blocking detected", detail: `${otherHandler.method} handler` });
+    }
+  }
+  return context.length > 0 ? context : void 0;
+}
+function getRouteIntent(handlers) {
+  const intentPriority = [
+    "webhook",
+    "internal",
+    "sensitive-mutation",
+    "public-form",
+    "public-read",
+    "unknown"
+  ];
+  return intentPriority.find(
+    (intent) => handlers.some((handler) => handler.intent === intent)
+  ) ?? "unknown";
+}
+function getRouteWebhookProvider(handlers, relativeFile, content) {
+  const routeWebhookInfo = getWebhookRouteInfo(relativeFile, content);
+  if (routeWebhookInfo?.provider && routeWebhookInfo.provider !== "unknown") {
+    return routeWebhookInfo.provider;
+  }
+  const webhookHandler = handlers.find((handler) => handler.intent === "webhook");
+  if (!webhookHandler) {
+    return "unknown";
+  }
+  const providerFromEvidence = webhookHandler.evidence.find(
+    (item) => item.label === "webhook content detected" && item.detail && item.detail !== "unknown"
+  );
+  return providerFromEvidence?.detail ?? "unknown";
+}
+function getHandlerAuthExpectation(intent, method, hasMethodBlocking) {
+  if (hasMethodBlocking || intent === "public-read" || intent === "public-form" || intent === "webhook") {
+    return false;
+  }
   if (intent === "internal" || intent === "sensitive-mutation") {
     return true;
   }
-  if (intent === "unknown" && hasMutationMethod(methods)) {
+  if (isMutationMethod(method)) {
     return "review";
   }
   return false;
 }
-function getApiRouteConfidence(intent, methods, webhookRouteInfo) {
+function getApiHandlerConfidence(intent, method, webhookRouteInfo, hasMethodBlocking) {
+  if (hasMethodBlocking) {
+    return "low";
+  }
   if (intent === "sensitive-mutation" || intent === "internal") {
     return "high";
   }
   if (intent === "webhook") {
     return webhookRouteInfo?.confidence === "high" ? "high" : "medium";
   }
-  if (intent === "public-form" || intent === "unknown" && hasMutationMethod(methods)) {
+  if (intent === "public-form" || intent === "unknown" && isMutationMethod(method)) {
     return "medium";
   }
   return "low";
 }
+function getSensitiveHandlerTitle(handler) {
+  const pathSignal = handler.evidence.find((item) => item.label === "path contains")?.detail;
+  if (handler.method === "POST" && pathSignal === "upload") {
+    return "Upload POST handler may be missing authentication";
+  }
+  return `Sensitive ${handler.method} handler may be missing authentication`;
+}
 function getRoutePathMatch(normalizedFile, terms) {
   return terms.find((term) => {
     const escapedTerm = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -968,16 +1090,96 @@ function getRoutePathMatch(normalizedFile, terms) {
   });
 }
 function getExportedHttpMethods(content) {
-  const methods = /* @__PURE__ */ new Set();
-  const functionExportPattern = /\bexport\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
-  const constExportPattern = /\bexport\s+const\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
+  return getExportedRouteHandlers(content).map((handler) => handler.method);
+}
+function getExportedRouteHandlers(content) {
+  const handlers = [];
+  const functionExportPattern = /\bexport\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(/g;
+  const constExportPattern = /\bexport\s+const\s+(GET|POST|PUT|PATCH|DELETE)\s*=/g;
   for (const match of content.matchAll(functionExportPattern)) {
-    methods.add(match[1]);
+    handlers.push(extractRouteHandlerBody(content, match.index ?? 0, match[1], "function"));
   }
   for (const match of content.matchAll(constExportPattern)) {
-    methods.add(match[1]);
+    handlers.push(extractRouteHandlerBody(content, match.index ?? 0, match[1], "const"));
   }
-  return [...methods];
+  return handlers.sort(
+    (leftHandler, rightHandler) => getMethodRank(leftHandler.method) - getMethodRank(rightHandler.method)
+  );
+}
+function extractRouteHandlerBody(content, exportIndex, method, exportKind) {
+  const nextExportIndex = findNextRouteHandlerExport(content, exportIndex + 1);
+  const handlerEnd = nextExportIndex === -1 ? content.length : nextExportIndex;
+  const openBraceIndex = getRouteHandlerBodyOpenBrace(content, exportIndex, handlerEnd, exportKind);
+  if (openBraceIndex !== -1 && openBraceIndex < handlerEnd) {
+    const closeBraceIndex = findMatchingBrace(content, openBraceIndex);
+    if (closeBraceIndex !== -1) {
+      return {
+        method,
+        body: content.slice(openBraceIndex, closeBraceIndex + 1),
+        usedFallbackBody: false
+      };
+    }
+  }
+  return {
+    method,
+    body: content.slice(exportIndex, handlerEnd),
+    usedFallbackBody: true
+  };
+}
+function getRouteHandlerBodyOpenBrace(content, exportIndex, handlerEnd, exportKind) {
+  if (exportKind === "function") {
+    const openParenIndex = content.indexOf("(", exportIndex);
+    if (openParenIndex !== -1 && openParenIndex < handlerEnd) {
+      const closeParenIndex = findMatchingParen(content, openParenIndex);
+      if (closeParenIndex !== -1 && closeParenIndex < handlerEnd) {
+        return content.indexOf("{", closeParenIndex);
+      }
+    }
+  }
+  const equalsIndex = content.indexOf("=", exportIndex);
+  if (equalsIndex !== -1 && equalsIndex < handlerEnd) {
+    const arrowIndex = content.indexOf("=>", equalsIndex);
+    if (arrowIndex !== -1 && arrowIndex < handlerEnd) {
+      return content.indexOf("{", arrowIndex);
+    }
+  }
+  return content.indexOf("{", exportIndex);
+}
+function findNextRouteHandlerExport(content, startIndex) {
+  const nextExportPattern = /\bexport\s+(?:async\s+)?(?:function|const)\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
+  nextExportPattern.lastIndex = startIndex;
+  const match = nextExportPattern.exec(content);
+  return match?.index ?? -1;
+}
+function findMatchingParen(content, openParenIndex) {
+  let depth = 0;
+  for (let index = openParenIndex; index < content.length; index++) {
+    const character = content[index];
+    if (character === "(") {
+      depth++;
+    } else if (character === ")") {
+      depth--;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
+}
+function findMatchingBrace(content, openBraceIndex) {
+  let depth = 0;
+  for (let index = openBraceIndex; index < content.length; index++) {
+    const character = content[index];
+    if (character === "{") {
+      depth++;
+    } else if (character === "}") {
+      depth--;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
 }
 function getRouteHttpMethods(content) {
   const methods = new Set(getExportedHttpMethods(content));
@@ -991,10 +1193,12 @@ function getRouteHttpMethods(content) {
   }
   return [...methods];
 }
-function hasMutationMethod(methods) {
-  return ["POST", "PUT", "PATCH", "DELETE"].some(
-    (method) => methods.includes(method)
-  );
+function getMethodRank(method) {
+  const methodOrder = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+  return methodOrder.indexOf(method);
+}
+function isMutationMethod(method) {
+  return method !== "GET";
 }
 function hasAuthOrSessionCheck(content) {
   const normalizedContent = content.toLowerCase();
@@ -1014,7 +1218,7 @@ function hasValidationSignal(content) {
 }
 function hasCacheHeaderSignal(content) {
   const normalizedContent = content.toLowerCase();
-  return normalizedContent.includes("cache-control") || normalizedContent.includes("s-maxage") || normalizedContent.includes("stale-while-revalidate") || normalizedContent.includes("public") || normalizedContent.includes("published") || normalizedContent.includes("status");
+  return normalizedContent.includes("cache-control") || normalizedContent.includes("s-maxage") || normalizedContent.includes("stale-while-revalidate") || normalizedContent.includes("public") || normalizedContent.includes("published");
 }
 function hasMethodBlockingSignal(content) {
   const normalizedContent = content.toLowerCase();
@@ -1094,7 +1298,135 @@ function getWebhookSignatureSuggestion(provider) {
   }
   return "Verify the provider signature using the raw request body and signature header before trusting the event.";
 }
-function createApiAuthFixPrompt(file) {
+function getMaintainabilityFileKind(relativeFile) {
+  const normalizedFile = normalizePath(relativeFile).toLowerCase();
+  const fileName = path.basename(normalizedFile);
+  if (/(^|\/)app\/api\/.+\/route\.(?:ts|js)$/.test(normalizedFile) || /(^|\/)pages\/api\/.+\.(?:ts|js)$/.test(normalizedFile)) {
+    return "api-route";
+  }
+  if (fileName === "actions.ts" || fileName === "actions.tsx") {
+    return "server-action";
+  }
+  if (fileName === "schema.ts" || fileName === "schemas.ts" || fileName === "validation.ts" || fileName === "validator.ts") {
+    return "schema-or-validation";
+  }
+  if (fileName === "types.ts" || fileName === "type.ts" || fileName === "interfaces.ts") {
+    return "types";
+  }
+  if (fileName === "config.ts" || fileName === "config.js" || fileName === "next.config.ts" || fileName === "tailwind.config.ts") {
+    return "config";
+  }
+  if (normalizedFile.endsWith(".tsx") || normalizedFile.endsWith(".jsx")) {
+    return "react-component";
+  }
+  if (/\.(?:ts|js|mts|cts|mjs|cjs)$/.test(normalizedFile)) {
+    return "typescript-module";
+  }
+  return "unknown";
+}
+function getLargeFileIssueCopy(kind) {
+  if (kind === "react-component") {
+    return {
+      title: "Large React component detected",
+      message: "This component is larger than the recommended maintainability threshold. Large components can be harder to review, test, and safely modify.",
+      suggestion: "Review whether this component mixes UI, state, data fetching, validation, or business logic. If so, split it into smaller components, hooks, or utilities."
+    };
+  }
+  if (kind === "typescript-module") {
+    return {
+      title: "Large TypeScript module detected",
+      message: "This module is larger than the recommended maintainability threshold. Large modules can mix business logic, data access, transformations, constants, or helper functions in one place.",
+      suggestion: "Review whether this module mixes unrelated responsibilities such as data fetching, filtering, mapping, sorting, constants, types, or business rules. If so, split it into smaller modules while preserving public exports."
+    };
+  }
+  if (kind === "api-route") {
+    return {
+      title: "Large API route detected",
+      message: "This API route is larger than the recommended maintainability threshold. Large route handlers can mix validation, auth, business logic, and response formatting.",
+      suggestion: "Review whether this route mixes validation, authentication, business logic, and response formatting. If so, extract reusable helpers without changing route behavior."
+    };
+  }
+  if (kind === "server-action") {
+    return {
+      title: "Large server action file detected",
+      message: "This server action file is larger than the recommended maintainability threshold and may mix validation, data mutations, and business rules.",
+      suggestion: "Review whether this file mixes validation, permission checks, mutations, and formatting. If so, extract helpers while preserving action behavior."
+    };
+  }
+  if (kind === "schema-or-validation") {
+    return {
+      title: "Large schema or validation file detected",
+      message: "This schema or validation file is larger than the recommended maintainability threshold and may mix unrelated validation concerns.",
+      suggestion: "Review whether related schemas or validators can be grouped into smaller files while preserving exported names and validation behavior."
+    };
+  }
+  if (kind === "types") {
+    return {
+      title: "Large type definition file detected",
+      message: "This type file is larger than the recommended maintainability threshold and may be harder to navigate safely.",
+      suggestion: "Review whether types can be split by domain or feature while preserving public exports and imports."
+    };
+  }
+  if (kind === "config") {
+    return {
+      title: "Large config file detected",
+      message: "This config file is larger than the recommended maintainability threshold and may mix unrelated configuration concerns.",
+      suggestion: "Review whether configuration values or helper functions can be moved to smaller supporting modules without changing runtime behavior."
+    };
+  }
+  return {
+    title: "Large file detected",
+    message: "This file is larger than the recommended maintainability threshold. Large files can be harder to review, test, and safely modify.",
+    suggestion: "Review whether this file mixes unrelated responsibilities. If so, split it into smaller modules while preserving behavior."
+  };
+}
+function createApiAuthFixPrompt(file, method, intent = "unknown") {
+  if (method && intent === "sensitive-mutation") {
+    return `Review the API route at ${file}.
+
+Qodfy detected a possible issue in the ${method} handler.
+
+Goal:
+Determine whether the ${method} handler should be protected.
+
+Instructions:
+- Inspect each exported HTTP handler separately.
+- Do not add authentication to a GET handler if it is intentionally public.
+- If the ${method} handler handles file uploads, private data, storage writes, payments, account changes, or user-specific actions, add the existing project auth/session check to the ${method} handler.
+- Also verify protections such as input validation, file size limits for uploads, storage path safety, and rate limiting where relevant.
+- Do not introduce a new auth provider.
+- Do not refactor unrelated code.
+- Keep existing response formats unchanged.
+- If the ${method} handler is intentionally public, add a short comment explaining why and confirm abuse protection exists.
+
+Return:
+- Whether each handler is public or protected.
+- Whether the ${method} handler should be protected.
+- The safest code change.
+- Edge cases to test.`;
+  }
+  if (method && intent === "unknown") {
+    return `Review the API route at ${file}.
+
+Qodfy detected a mutation handler that should be reviewed: ${method}.
+
+Goal:
+Determine whether the ${method} handler should be public or protected.
+
+Instructions:
+- Inspect each exported HTTP handler separately.
+- Check what data the ${method} handler reads, writes, or returns.
+- If it handles private data, user-specific data, writes, uploads, or admin actions, add the existing project auth/session check.
+- If it is intentionally public, document why and confirm validation and abuse protection exist.
+- Do not introduce a new auth provider.
+- Do not refactor unrelated code.
+- Keep existing response formats unchanged.
+
+Return:
+- Whether the ${method} handler should be protected.
+- The safest code change, if any.
+- Edge cases to test.`;
+  }
   return `Review the API route at ${file}.
 
 Goal:
@@ -1113,34 +1445,40 @@ Return:
 - The updated code.
 - Any edge cases I should test.`;
 }
-function createPublicReadRouteFixPrompt(file) {
+function createPublicReadRouteFixPrompt(file, method = "GET") {
   return `Review the public read API route at ${file}.
 
+Qodfy detected this as a likely public ${method} handler.
+
 Goal:
-Verify that this route is safe to remain public.
+Verify that the ${method} handler is safe to remain public.
 
 Instructions:
-- Confirm it only exposes published, public, or non-sensitive data.
+- Inspect each exported HTTP handler separately.
+- Confirm the ${method} handler only exposes published, public, or non-sensitive data.
 - Check that route params and query values are validated or sanitized.
 - Check for appropriate cache headers where useful.
 - Check for abuse protection if the route can be called heavily.
-- Do not add user authentication unless the route should be private.
+- Do not add user authentication to the ${method} handler unless it should be private.
 - Do not refactor unrelated code.
 
 Return:
-- Whether this route appears intentionally public.
+- Whether the ${method} handler appears intentionally public.
 - Any low-risk safety improvements.
 - Any edge cases I should test.`;
 }
-function createPublicFormProtectionFixPrompt(file) {
+function createPublicFormProtectionFixPrompt(file, method = "POST") {
   return `Review the public form API route at ${file}.
 
+Qodfy detected this as a likely public ${method} handler.
+
 Goal:
 Verify validation, rate limiting, and spam protection.
 
 Instructions:
-- Confirm submitted input is validated before it is used.
-- Check for rate limiting or another abuse protection pattern.
+- Inspect each exported HTTP handler separately.
+- Confirm submitted input in the ${method} handler is validated before it is used.
+- Check for rate limiting or another abuse protection pattern on the ${method} handler.
 - Check whether captcha, Turnstile, reCAPTCHA, or hCaptcha is appropriate.
 - Do not add user authentication unless the form should be private.
 - Do not introduce a new service unless necessary.
@@ -1151,18 +1489,24 @@ Return:
 - The safest minimal change if protection is missing.
 - Any edge cases I should test.`;
 }
-function createInternalRouteProtectionFixPrompt(file) {
+function createInternalRouteProtectionFixPrompt(file, method) {
+  const handlerLine = method ? `
+Qodfy detected this as a likely internal ${method} handler.
+` : "";
+  const handlerReference = method ? `the ${method} handler` : "the route";
   return `Review the internal API route at ${file}.
+${handlerLine}
 
 Goal:
 Confirm this operational route is protected before launch.
 
 Instructions:
-- Check whether the route is protected by existing auth, a secret token, or server-only access.
+- Inspect each exported HTTP handler separately.
+- Check whether ${handlerReference} is protected by existing auth, a secret token, or server-only access.
 - For cron, cleanup, revalidation, or admin routes, prefer the existing project protection pattern.
 - Do not introduce a new auth provider.
 - Do not change route behavior unless protection is missing.
-- If the route is intentionally reachable, add a short comment explaining the protection boundary.
+- If ${handlerReference} is intentionally reachable, add a short comment explaining the protection boundary.
 
 Return:
 - Whether protection already exists.
@@ -1184,16 +1528,17 @@ Return:
 - The updated .env.example lines.
 - A short explanation.`;
 }
-function createLargeFileFixPrompt(file) {
-  return `Review ${file}.
+function createLargeFileFixPrompt(file, kind = getMaintainabilityFileKind(file)) {
+  if (kind === "react-component") {
+    return `Review ${file}.
 
-Qodfy detected this as a large file.
+Qodfy detected this as a large React component.
 
 Goal:
 Suggest a safe refactor plan without changing behavior.
 
 Instructions:
-- Identify the main responsibilities inside the file.
+- Identify the main responsibilities inside the component.
 - Suggest smaller components, hooks, or utility files that can be extracted.
 - Do not rewrite the whole file at once.
 - Do not change UI behavior.
@@ -1204,6 +1549,163 @@ Return:
 - A short responsibility breakdown.
 - A step-by-step refactor plan.
 - The safest first extraction.`;
+  }
+  if (kind === "typescript-module") {
+    return `Review ${file}.
+
+Qodfy detected this as a large TypeScript module.
+
+Goal:
+Create a safe refactor plan without changing behavior.
+
+Instructions:
+- Identify the main responsibilities inside this module.
+- Check whether the module mixes unrelated concerns such as data access, filtering, mapping, sorting, constants, types, validation, or business rules.
+- Suggest smaller TypeScript modules that could be extracted safely.
+- Do not rewrite the whole file at once.
+- Do not change business logic.
+- Do not change public exports unless you also update all imports safely.
+- Preserve existing function behavior, return types, and error handling.
+- Prioritize the lowest-risk extraction first.
+
+Return:
+- Responsibility breakdown.
+- Suggested new file/module structure.
+- Step-by-step refactor plan.
+- The safest first extraction.
+- Tests or manual checks to run.`;
+  }
+  if (kind === "api-route") {
+    return `Review the API route at ${file}.
+
+Qodfy detected this as a large API route file.
+
+Goal:
+Create a safe refactor plan without changing HTTP behavior.
+
+Instructions:
+- Identify where validation, authentication, business logic, and response formatting happen.
+- Suggest helper modules that can be extracted without changing the route contract.
+- Preserve HTTP methods, status codes, headers, auth checks, validation behavior, and response shape.
+- Do not rewrite the whole route at once.
+- Do not introduce a new auth provider or validation library.
+- Prioritize the lowest-risk extraction first.
+
+Return:
+- Responsibility breakdown.
+- Suggested helper/module structure.
+- Step-by-step refactor plan.
+- The safest first extraction.
+- Tests or manual checks to run.`;
+  }
+  if (kind === "server-action") {
+    return `Review the server action file at ${file}.
+
+Qodfy detected this as a large server action file.
+
+Goal:
+Create a safe refactor plan without changing action behavior.
+
+Instructions:
+- Identify validation, permission checks, mutations, cache invalidation, formatting, and error handling.
+- Suggest helper modules that can be extracted safely.
+- Preserve permissions, validation behavior, data mutations, cache invalidation, return shape, and error handling.
+- Do not rewrite the whole file at once.
+- Do not change public action names unless you also update every import safely.
+- Prioritize the lowest-risk extraction first.
+
+Return:
+- Responsibility breakdown.
+- Suggested helper/module structure.
+- Step-by-step refactor plan.
+- The safest first extraction.
+- Tests or manual checks to run.`;
+  }
+  if (kind === "schema-or-validation") {
+    return `Review the schema or validation file at ${file}.
+
+Qodfy detected this as a large validation-focused file.
+
+Goal:
+Create a safe refactor plan without changing validation behavior.
+
+Instructions:
+- Identify related schemas, validators, shared constants, and inferred types.
+- Suggest smaller validation modules grouped by feature or domain.
+- Do not change validation rules, error messages, inferred types, or public exports unless you also update all imports safely.
+- Prioritize the lowest-risk extraction first.
+
+Return:
+- Responsibility breakdown.
+- Suggested file/module structure.
+- Step-by-step refactor plan.
+- The safest first extraction.
+- Tests or manual checks to run.`;
+  }
+  if (kind === "types") {
+    return `Review the type definition file at ${file}.
+
+Qodfy detected this as a large type file.
+
+Goal:
+Create a safe organization plan without changing runtime behavior.
+
+Instructions:
+- Identify groups of related types, interfaces, enums, and exported utility types.
+- Suggest smaller type modules grouped by domain or feature.
+- Do not change type names, public exports, or imports unless you also update all references safely.
+- Prioritize the lowest-risk extraction first.
+
+Return:
+- Type responsibility breakdown.
+- Suggested file/module structure.
+- Step-by-step refactor plan.
+- The safest first extraction.
+- Type-check command to run.`;
+  }
+  if (kind === "config") {
+    return `Review the config file at ${file}.
+
+Qodfy detected this as a large config file.
+
+Goal:
+Create a safe simplification plan without changing runtime configuration.
+
+Instructions:
+- Identify config sections, constants, plugin setup, and helper functions.
+- Suggest supporting modules only if extraction reduces complexity.
+- Preserve all existing config values, plugin order, environment behavior, and exports.
+- Do not upgrade dependencies or change framework behavior.
+- Prioritize the lowest-risk extraction first.
+
+Return:
+- Config responsibility breakdown.
+- Suggested supporting module structure.
+- Step-by-step refactor plan.
+- The safest first extraction.
+- Build or validation command to run.`;
+  }
+  return `Review ${file}.
+
+Qodfy detected this as a large file.
+
+Goal:
+Create a safe refactor plan without changing behavior.
+
+Instructions:
+- Identify the main responsibilities inside the file.
+- Suggest smaller files or modules that can be extracted safely.
+- Do not rewrite the whole file at once.
+- Do not change public exports unless you also update all imports safely.
+- Preserve existing behavior, return values, and error handling.
+- Prioritize the lowest-risk extraction first.
+
+Return:
+- Responsibility breakdown.
+- Suggested file/module structure.
+- Step-by-step refactor plan.
+- The safest first extraction.
+- Tests or manual checks to run.`;
 }
 function createAiRateLimitFixPrompt(file) {
   return `Review the AI-related API route at ${file}.
@@ -1224,8 +1726,13 @@ Return:
 - The updated code.
 - Any environment variables required.`;
 }
-function createWebhookSignatureFixPrompt(file) {
+function createWebhookSignatureFixPrompt(file, method) {
+  const handlerLine = method ? `
+Qodfy detected a possible issue in the ${method} webhook handler.
+` : "";
+  const handlerReference = method ? `the ${method} handler` : "the webhook route";
   return `Review the webhook API route at ${file}.
+${handlerLine}
 
 Goal:
 Verify that webhook signature validation happens before the event is handled.
@@ -1233,7 +1740,8 @@ Verify that webhook signature validation happens before the event is handled.
 Instructions:
 - Detect which provider this webhook belongs to based on imports, headers, and environment variables.
 - Use the provider's existing verification pattern if already present.
-- Do not process the webhook event before verification unless required by the provider.
+- Verify that ${handlerReference} validates the provider signature before processing the event unless the provider requires a different order.
+- Do not add user authentication unless the webhook provider requires it.
 - Do not introduce unrelated changes.
 - If verification already exists, explain where it happens.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodfy/core",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Scanner engine for Qodfy, an open-source launch readiness scanner for AI-built apps.",
   "keywords": [
     "qodfy",