@qodfy/core 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 type IssueSeverity = "critical" | "warning" | "info";
+type IssueConfidence = "high" | "medium" | "low";
 type IssueCategory = "security" | "environment" | "api" | "webhook" | "ai" | "maintainability" | "project";
 declare const validScanChecks: readonly ["project", "api", "environment", "ai", "webhook", "maintainability", "security"];
 type ScanCheck = typeof validScanChecks[number];
@@ -8,6 +9,7 @@ type Issue = {
     ruleId: string;
     category: IssueCategory;
     severity: IssueSeverity;
+    confidence: IssueConfidence;
     title: string;
     message: string;
     file?: string;
@@ -30,7 +32,8 @@ type ScanReport = {
 type ScanOptions = {
     projectPath: string;
     checks?: ScanCheck[];
+    includeLowConfidence?: boolean;
 };
 declare function scanProject(input: string | ScanOptions): Promise<ScanReport>;
 
-export { type Issue, type IssueCategory, type IssueSeverity, type ScanCheck, type ScanOptions, type ScanReport, recommendedScanChecks, scanProject, validScanChecks };
+export { type Issue, type IssueCategory, type IssueConfidence, type IssueSeverity, type ScanCheck, type ScanOptions, type ScanReport, recommendedScanChecks, scanProject, validScanChecks };

package/dist/index.js

@@ -115,6 +115,9 @@ var issueIdPrefixes = {
   "security-client-side-secret": "security-client-side-secret",
   "security-hardcoded-secret": "security-hardcoded-secret",
   "api-route-missing-auth": "security-api-auth",
+  "api-public-read-route": "api-public-read-route",
+  "api-public-form-abuse-protection": "api-public-form-protection",
+  "api-internal-route-protection": "api-internal-route-protection",
   "ai-route-missing-rate-limit": "ai-route-rate-limit",
   "maintainability-large-file": "maintainability-large-file",
   "maintainability-large-file-skipped": "maintainability-large-file-skipped",
@@ -125,6 +128,7 @@ var issueIdPrefixes = {
 async function scanProject(input) {
   const startTime = Date.now();
   const projectPath = typeof input === "string" ? input : input.projectPath;
+  const includeLowConfidence = typeof input === "string" ? false : Boolean(input.includeLowConfidence);
   const enabledChecks = getEnabledChecks(
     typeof input === "string" ? void 0 : input.checks
   );
@@ -148,6 +152,7 @@ async function scanProject(input) {
       ruleId: "project-missing-package-json",
       category: "project",
       severity: "critical",
+      confidence: "high",
       title: "Missing package.json",
       message: "Qodfy could not find a package.json file in this project.",
       suggestion: "Run Qodfy from the project root or pass --path to the app folder.",
@@ -160,6 +165,7 @@ async function scanProject(input) {
         ruleId: "project-invalid-package-json",
         category: "project",
         severity: "critical",
+        confidence: "high",
         title: "Could not read package.json",
         message: packageJsonResult.reason,
         file: "package.json",
@@ -171,6 +177,7 @@ async function scanProject(input) {
         ruleId: "project-invalid-package-json",
         category: "project",
         severity: "critical",
+        confidence: "high",
         title: "Invalid package.json",
         message: "package.json must contain a JSON object at the top level.",
         file: "package.json",
@@ -188,6 +195,7 @@ async function scanProject(input) {
           ruleId: "project-next-not-detected",
           category: "project",
           severity: "warning",
+          confidence: "low",
           title: "Next.js not detected",
           message: "This first version of Qodfy is optimized for Next.js projects.",
           suggestion: "If this is a monorepo, scan the Next.js app folder directly.",
@@ -204,6 +212,7 @@ async function scanProject(input) {
       ruleId: "environment-missing-env-example",
       category: "environment",
       severity: "warning",
+      confidence: "medium",
       title: "Missing .env.example",
       message: "Add a .env.example file so future developers know which environment variables are required.",
       suggestion: "Document required variable names only, never real secret values.",
@@ -216,6 +225,7 @@ async function scanProject(input) {
         ruleId: "environment-missing-env-example",
         category: "environment",
         severity: "warning",
+        confidence: "medium",
         title: "Could not read .env.example",
         message: envExampleResult.reason,
         file: ".env.example",
@@ -232,6 +242,7 @@ async function scanProject(input) {
       ruleId: "project-missing-readme",
       category: "project",
       severity: "info",
+      confidence: "low",
       title: "Missing README.md",
       message: "A README helps other developers understand how to run and maintain the project.",
       fixPrompt: createReadmeFixPrompt()
@@ -257,6 +268,7 @@ async function scanProject(input) {
           ruleId: "maintainability-file-unreadable",
           category: "maintainability",
           severity: "info",
+          confidence: "low",
           title: "File could not be checked",
           message: statResult.reason,
           file: relativeFile,
@@ -272,6 +284,7 @@ async function scanProject(input) {
           ruleId: "maintainability-large-file-skipped",
           category: "maintainability",
           severity: "info",
+          confidence: "low",
           title: "Large file skipped from deep scan",
           message: "This file is larger than 500KB and was skipped from deep content checks.",
           file: relativeFile,
@@ -298,6 +311,7 @@ async function scanProject(input) {
           ruleId: "maintainability-file-unreadable",
           category: "maintainability",
           severity: "info",
+          confidence: "low",
           title: "File could not be read",
           message: fileResult.reason,
           file: relativeFile,
@@ -318,6 +332,7 @@ async function scanProject(input) {
           ruleId: "ai-route-missing-rate-limit",
           category: "ai",
           severity: "critical",
+          confidence: "high",
           title: "AI route may be missing rate limiting",
           message: "AI routes can create real API costs. Add rate limiting or usage limits before launch.",
           file: relativeFile,
@@ -326,12 +341,13 @@ async function scanProject(input) {
         });
       }
     }
-    const webhookRouteInfo = runWebhookChecks && apiRouteSet.has(file) ? getWebhookRouteInfo(relativeFile, content) : null;
+    const webhookRouteInfo = (runWebhookChecks || runApiChecks) && apiRouteSet.has(file) ? getWebhookRouteInfo(relativeFile, content) : null;
     if (webhookRouteInfo && !hasWebhookSignatureVerification(content, webhookRouteInfo.provider)) {
       addIssue({
         ruleId: "webhook-missing-signature-verification",
         category: "webhook",
         severity: webhookRouteInfo.confidence === "high" ? "critical" : "warning",
+        confidence: webhookRouteInfo.confidence === "high" ? "high" : "medium",
         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,
@@ -350,6 +366,7 @@ async function scanProject(input) {
           ruleId: "security-hardcoded-secret",
           category: "security",
           severity: "critical",
+          confidence: "high",
           title: "Possible hardcoded secret",
           message: `A string literal in ${relativeFile} matches the pattern for ${secretMatch.label}. Qodfy does not print possible secret values.`,
           file: relativeFile,
@@ -359,19 +376,13 @@ async function scanProject(input) {
       }
     }
     if (runApiChecks && apiRouteSet.has(file)) {
-      const hasAuth = content.includes("auth(") || content.includes("getServerSession") || content.includes("currentUser") || content.includes("clerkClient") || content.includes("session");
-      if (!hasAuth && !webhookRouteInfo) {
-        addIssue({
-          ruleId: "api-route-missing-auth",
-          category: "api",
-          severity: "warning",
-          title: "API route may be missing authentication",
-          message: "This API route does not appear to contain an auth/session check.",
-          file: relativeFile,
-          suggestion: "Confirm the route is public, or add an auth/session check before handling user data.",
-          fixPrompt: createApiAuthFixPrompt(relativeFile)
-        });
-      }
+      addApiRouteProtectionIssues({
+        addIssue,
+        content,
+        includeLowConfidence,
+        relativeFile,
+        webhookRouteInfo
+      });
     }
     const usedEnvVariables = runEnvironmentChecks || runSecurityChecks ? getUsedEnvVariables(content) : /* @__PURE__ */ new Set();
     if (runEnvironmentChecks && envExampleVariables) {
@@ -396,6 +407,7 @@ async function scanProject(input) {
             ruleId: "security-client-side-secret",
             category: "security",
             severity: "warning",
+            confidence: "medium",
             title: "Possible server secret used in client-side code",
             message: `${variableName} appears in a client-side file. Server secrets should not be exposed to the browser.`,
             file: relativeFile,
@@ -411,6 +423,7 @@ async function scanProject(input) {
       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.",
       file: largeFile.relativeFile,
@@ -424,6 +437,7 @@ async function scanProject(input) {
       ruleId: "environment-variable-missing-from-example",
       category: "environment",
       severity: "warning",
+      confidence: "medium",
       title: "Environment variable missing from .env.example",
       message: getMissingEnvMessage(variableName, files2),
       file: files2.length === 1 ? files2[0] : void 0,
@@ -455,8 +469,9 @@ function createIssueFactory(issues) {
     const currentCount = (issueCounts.get(issue.ruleId) ?? 0) + 1;
     issueCounts.set(issue.ruleId, currentCount);
     issues.push({
+      ...issue,
       id: `${getIssueIdPrefix(issue.ruleId, issue.category)}-${currentCount}`,
-      ...issue
+      confidence: issue.confidence ?? "medium"
     });
   };
 }
@@ -574,6 +589,7 @@ async function getSourceFiles(projectPath, addIssue) {
       ruleId: "project-source-files-unreadable",
       category: "project",
       severity: "critical",
+      confidence: "high",
       title: "Could not scan source files",
       message: "Qodfy could not list source files in this project.",
       suggestion: "Check that the project path exists and is readable.",
@@ -668,6 +684,191 @@ 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 addApiRouteProtectionIssues({
+  addIssue,
+  content,
+  includeLowConfidence,
+  relativeFile,
+  webhookRouteInfo
+}) {
+  const intent = classifyApiRouteIntent(relativeFile, content, webhookRouteInfo);
+  const hasAuth = hasAuthOrSessionCheck(content);
+  const methods = getHttpMethods(content);
+  if (intent === "webhook") {
+    return;
+  }
+  if (intent === "public-read") {
+    if (includeLowConfidence) {
+      addIssue({
+        ruleId: "api-public-read-route",
+        category: "api",
+        severity: "info",
+        confidence: "low",
+        title: "Public read API route detected",
+        message: "This route appears intentionally public. Authentication may not be required.",
+        file: relativeFile,
+        suggestion: "Verify that it only exposes public or published data and has appropriate validation, caching, and abuse protection.",
+        fixPrompt: createPublicReadRouteFixPrompt(relativeFile)
+      });
+    }
+    return;
+  }
+  if (intent === "public-form") {
+    if (!hasAbuseProtection(content)) {
+      addIssue({
+        ruleId: "api-public-form-abuse-protection",
+        category: "api",
+        severity: "warning",
+        confidence: "medium",
+        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: relativeFile,
+        suggestion: "Check for rate limiting, validation, captcha, Turnstile, reCAPTCHA, hCaptcha, or another spam protection pattern.",
+        fixPrompt: createPublicFormProtectionFixPrompt(relativeFile)
+      });
+    }
+    return;
+  }
+  if (intent === "internal") {
+    if (!hasInternalRouteProtection(content)) {
+      addIssue({
+        ruleId: "api-internal-route-protection",
+        category: "api",
+        severity: "warning",
+        confidence: "high",
+        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: 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(relativeFile)
+      });
+    }
+    return;
+  }
+  if (intent === "sensitive-mutation") {
+    if (!hasAuth) {
+      addIssue({
+        ruleId: "api-route-missing-auth",
+        category: "api",
+        severity: "warning",
+        confidence: "high",
+        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.",
+        file: 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(relativeFile)
+      });
+    }
+    return;
+  }
+  if (hasMutationMethod(methods) && !hasAuth) {
+    addIssue({
+      ruleId: "api-route-missing-auth",
+      category: "api",
+      severity: "warning",
+      confidence: "medium",
+      title: "API mutation route should be reviewed for authentication",
+      message: "This route appears to handle a mutation, but Qodfy could not find an auth/session check.",
+      file: relativeFile,
+      suggestion: "Confirm the route is intentionally public, or add the existing project auth/session check before handling private data.",
+      fixPrompt: createApiAuthFixPrompt(relativeFile)
+    });
+  }
+}
+function classifyApiRouteIntent(relativeFile, content, webhookRouteInfo) {
+  const normalizedFile = relativeFile.toLowerCase();
+  const methods = getHttpMethods(content);
+  if (webhookRouteInfo || routePathHasAny(normalizedFile, ["webhook", "webhooks", "callback"])) {
+    return "webhook";
+  }
+  if (routePathHasAny(normalizedFile, ["internal", "admin", "cron", "cleanup", "revalidate", "private"])) {
+    return "internal";
+  }
+  if (routePathHasAny(normalizedFile, ["contact", "subscribe", "newsletter", "lead", "inquiry"])) {
+    return "public-form";
+  }
+  if (routePathHasAny(normalizedFile, [
+    "upload",
+    "checkout",
+    "order",
+    "orders",
+    "invoice",
+    "invoices",
+    "account",
+    "user",
+    "users",
+    "payment",
+    "billing",
+    "cart",
+    "profile",
+    "settings"
+  ])) {
+    return "sensitive-mutation";
+  }
+  if (routePathHasAny(normalizedFile, [
+    "blog",
+    "blogs",
+    "post",
+    "posts",
+    "product",
+    "products",
+    "search",
+    "i18n",
+    "category",
+    "categories",
+    "sitemap",
+    "rss"
+  ])) {
+    return "public-read";
+  }
+  if (hasMutationMethod(methods)) {
+    return "unknown";
+  }
+  if (methods.size === 0 || isReadOnlyRoute(methods)) {
+    return "unknown";
+  }
+  return "unknown";
+}
+function routePathHasAny(normalizedFile, terms) {
+  return terms.some((term) => {
+    const escapedTerm = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[\\/._\\[\\]-])${escapedTerm}([\\/._\\[\\]-]|$)`).test(normalizedFile);
+  });
+}
+function getHttpMethods(content) {
+  const methods = /* @__PURE__ */ new Set();
+  const exportedMethodPattern = /\bexport\s+(?:async\s+)?(?:function|const)\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/g;
+  const requestMethodPattern = /\b(?:request|req)\.method\s*(?:={2,3}|!={1,2})\s*["'](GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)["']/g;
+  const methodCasePattern = /\bcase\s+["'](GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)["']/g;
+  for (const match of content.matchAll(exportedMethodPattern)) {
+    methods.add(match[1]);
+  }
+  for (const match of content.matchAll(requestMethodPattern)) {
+    methods.add(match[1]);
+  }
+  for (const match of content.matchAll(methodCasePattern)) {
+    methods.add(match[1]);
+  }
+  return methods;
+}
+function hasMutationMethod(methods) {
+  return ["POST", "PUT", "PATCH", "DELETE"].some((method) => methods.has(method));
+}
+function isReadOnlyRoute(methods) {
+  return [...methods].every((method) => method === "GET" || method === "HEAD" || method === "OPTIONS");
+}
+function hasAuthOrSessionCheck(content) {
+  const normalizedContent = content.toLowerCase();
+  return normalizedContent.includes("auth(") || normalizedContent.includes("getserversession") || normalizedContent.includes("currentuser") || normalizedContent.includes("clerkclient") || normalizedContent.includes("session") || normalizedContent.includes("requireauth") || normalizedContent.includes("requireuser") || normalizedContent.includes("requireadmin") || normalizedContent.includes("verifysession") || normalizedContent.includes("getuser") || normalizedContent.includes("jwt") || normalizedContent.includes("authorization") || normalizedContent.includes("bearer") || normalizedContent.includes("cookies()") || normalizedContent.includes("request.cookies") || normalizedContent.includes("middleware");
+}
+function hasInternalRouteProtection(content) {
+  const normalizedContent = content.toLowerCase();
+  return hasAuthOrSessionCheck(content) || /\bprocess\.env\.[A-Za-z0-9_]*SECRET\b/.test(content) || /\bprocess\.env\[['"`][A-Za-z0-9_]*SECRET['"`]\]/.test(content) || normalizedContent.includes("cron_secret") || normalizedContent.includes("revalidate_secret") || normalizedContent.includes("authorization") || normalizedContent.includes("bearer") || normalizedContent.includes("token");
+}
+function hasAbuseProtection(content) {
+  const normalizedContent = content.toLowerCase();
+  return normalizedContent.includes("ratelimit") || normalizedContent.includes("rate limit") || normalizedContent.includes("limiter") || normalizedContent.includes("captcha") || normalizedContent.includes("turnstile") || normalizedContent.includes("recaptcha") || normalizedContent.includes("hcaptcha") || normalizedContent.includes("validation") || normalizedContent.includes("validate") || normalizedContent.includes("zod") || normalizedContent.includes("safeparse");
+}
 function getWebhookRouteInfo(relativeFile, content) {
   const normalizedFile = relativeFile.toLowerCase();
   const normalizedContent = content.toLowerCase();
@@ -761,6 +962,62 @@ Return:
 - The updated code.
 - Any edge cases I should test.`;
 }
+function createPublicReadRouteFixPrompt(file) {
+  return `Review the public read API route at ${file}.
+
+Goal:
+Verify that this route is safe to remain public.
+
+Instructions:
+- Confirm it 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 refactor unrelated code.
+
+Return:
+- Whether this route appears intentionally public.
+- Any low-risk safety improvements.
+- Any edge cases I should test.`;
+}
+function createPublicFormProtectionFixPrompt(file) {
+  return `Review the public form API route at ${file}.
+
+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.
+- 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.
+- Keep existing behavior unchanged.
+
+Return:
+- Whether abuse protection already exists.
+- The safest minimal change if protection is missing.
+- Any edge cases I should test.`;
+}
+function createInternalRouteProtectionFixPrompt(file) {
+  return `Review the internal API route at ${file}.
+
+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.
+- 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.
+
+Return:
+- Whether protection already exists.
+- The safest minimal change if protection is missing.
+- Any edge cases I should test.`;
+}
 function createMissingEnvVariableFixPrompt(variableName, files) {
   return `Update the environment documentation for this project.
 

package/package.json

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