@qodfy/core 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 type IssueSeverity = "critical" | "warning" | "info";
 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];
+declare const recommendedScanChecks: ScanCheck[];
 type Issue = {
     id: string;
     ruleId: string;
@@ -24,6 +27,10 @@ type ScanReport = {
         durationMs: number;
     };
 };
-declare function scanProject(projectPath: string): Promise<ScanReport>;
+type ScanOptions = {
+    projectPath: string;
+    checks?: ScanCheck[];
+};
+declare function scanProject(input: string | ScanOptions): Promise<ScanReport>;
 
-export { type Issue, type IssueCategory, type IssueSeverity, type ScanReport, scanProject };
+export { type Issue, type IssueCategory, type IssueSeverity, type ScanCheck, type ScanOptions, type ScanReport, recommendedScanChecks, scanProject, validScanChecks };

package/dist/index.js

@@ -2,6 +2,23 @@
 import fs from "fs/promises";
 import path from "path";
 import fg from "fast-glob";
+var validScanChecks = [
+  "project",
+  "api",
+  "environment",
+  "ai",
+  "webhook",
+  "maintainability",
+  "security"
+];
+var recommendedScanChecks = [
+  "project",
+  "api",
+  "environment",
+  "ai",
+  "webhook",
+  "maintainability"
+];
 var sourceFilePatterns = ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"];
 var ignoredPaths = [
   "node_modules/**",
@@ -105,15 +122,28 @@ var issueIdPrefixes = {
   "project-source-files-unreadable": "project-source-files-unreadable",
   "webhook-missing-signature-verification": "webhook-signature-verification"
 };
-async function scanProject(projectPath) {
+async function scanProject(input) {
   const startTime = Date.now();
+  const projectPath = typeof input === "string" ? input : input.projectPath;
+  const enabledChecks = getEnabledChecks(
+    typeof input === "string" ? void 0 : input.checks
+  );
   const resolvedProjectPath = path.resolve(projectPath);
   const issues = [];
   const addIssue = createIssueFactory(issues);
+  const runProjectChecks = hasCheck(enabledChecks, "project");
+  const runEnvironmentChecks = hasCheck(enabledChecks, "environment");
+  const runApiChecks = hasCheck(enabledChecks, "api") || hasCheck(enabledChecks, "security");
+  const runAiChecks = hasCheck(enabledChecks, "ai");
+  const runWebhookChecks = hasCheck(enabledChecks, "webhook") || hasCheck(enabledChecks, "security");
+  const runMaintainabilityChecks = hasCheck(enabledChecks, "maintainability");
+  const runSecurityChecks = hasCheck(enabledChecks, "security");
+  const shouldScanSourceFiles = enabledChecks.size > 0 && !onlyHasCheck(enabledChecks, "project");
+  const shouldReadSourceContent = runEnvironmentChecks || runApiChecks || runAiChecks || runWebhookChecks || runSecurityChecks;
   const packageJsonPath = path.join(resolvedProjectPath, "package.json");
   const hasPackageJson = await fileExists(packageJsonPath);
   let isNextProject = false;
-  if (!hasPackageJson) {
+  if (runProjectChecks && !hasPackageJson) {
     addIssue({
       ruleId: "project-missing-package-json",
       category: "project",
@@ -123,7 +153,7 @@ async function scanProject(projectPath) {
       suggestion: "Run Qodfy from the project root or pass --path to the app folder.",
       fixPrompt: createProjectRootFixPrompt()
     });
-  } else {
+  } else if (runProjectChecks) {
     const packageJsonResult = await safeReadJson(packageJsonPath);
     if (!packageJsonResult.ok) {
       addIssue({
@@ -167,9 +197,9 @@ async function scanProject(projectPath) {
     }
   }
   const envExamplePath = path.join(resolvedProjectPath, ".env.example");
-  const hasEnvExample = await fileExists(envExamplePath);
+  const hasEnvExample = runEnvironmentChecks ? await fileExists(envExamplePath) : false;
   let envExampleVariables = null;
-  if (!hasEnvExample) {
+  if (runEnvironmentChecks && !hasEnvExample) {
     addIssue({
       ruleId: "environment-missing-env-example",
       category: "environment",
@@ -179,7 +209,7 @@ async function scanProject(projectPath) {
       suggestion: "Document required variable names only, never real secret values.",
       fixPrompt: createMissingEnvExampleFixPrompt()
     });
-  } else {
+  } else if (runEnvironmentChecks) {
     const envExampleResult = await safeReadFile(envExamplePath);
     if (!envExampleResult.ok) {
       addIssue({
@@ -196,8 +226,8 @@ async function scanProject(projectPath) {
       envExampleVariables = getEnvExampleVariables(envExampleResult.content);
     }
   }
-  const hasReadme = await fileExists(path.join(resolvedProjectPath, "README.md"));
-  if (!hasReadme) {
+  const hasReadme = runProjectChecks ? await fileExists(path.join(resolvedProjectPath, "README.md")) : true;
+  if (runProjectChecks && !hasReadme) {
     addIssue({
       ruleId: "project-missing-readme",
       category: "project",
@@ -207,7 +237,7 @@ async function scanProject(projectPath) {
       fixPrompt: createReadmeFixPrompt()
     });
   }
-  const files = await getSourceFiles(resolvedProjectPath, addIssue);
+  const files = shouldScanSourceFiles ? await getSourceFiles(resolvedProjectPath, addIssue) : [];
   const apiRoutes = files.filter((file) => {
     return isApiRoute(file);
   });
@@ -222,56 +252,65 @@ async function scanProject(projectPath) {
     const relativeFile = normalizePath(path.relative(resolvedProjectPath, file));
     const statResult = await safeStatFile(file);
     if (!statResult.ok) {
-      addIssue({
-        ruleId: "maintainability-file-unreadable",
-        category: "maintainability",
-        severity: "info",
-        title: "File could not be checked",
-        message: statResult.reason,
-        file: relativeFile,
-        suggestion: "Check file permissions if this file should be included in launch-readiness scans."
-      });
+      if (runMaintainabilityChecks) {
+        addIssue({
+          ruleId: "maintainability-file-unreadable",
+          category: "maintainability",
+          severity: "info",
+          title: "File could not be checked",
+          message: statResult.reason,
+          file: relativeFile,
+          suggestion: "Check file permissions if this file should be included in launch-readiness scans."
+        });
+      }
       continue;
     }
     if (statResult.size > MAX_FILE_SIZE_BYTES) {
+      if (runMaintainabilityChecks) {
+        largeFiles++;
+        addIssue({
+          ruleId: "maintainability-large-file-skipped",
+          category: "maintainability",
+          severity: "info",
+          title: "Large file skipped from deep scan",
+          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)
+        });
+      }
+      continue;
+    }
+    if (runMaintainabilityChecks && statResult.size > LARGE_FILE_WARNING_BYTES) {
       largeFiles++;
-      addIssue({
-        ruleId: "maintainability-large-file-skipped",
-        category: "maintainability",
-        severity: "info",
-        title: "Large file skipped from deep scan",
-        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)
+      largeFileCandidates.push({
+        relativeFile,
+        size: statResult.size
       });
+    }
+    if (!shouldReadSourceContent) {
       continue;
     }
     const fileResult = await safeReadFile(file);
     if (!fileResult.ok) {
-      addIssue({
-        ruleId: "maintainability-file-unreadable",
-        category: "maintainability",
-        severity: "info",
-        title: "File could not be read",
-        message: fileResult.reason,
-        file: relativeFile,
-        suggestion: "Check file permissions if this file should be included in launch-readiness scans."
-      });
+      if (runMaintainabilityChecks) {
+        addIssue({
+          ruleId: "maintainability-file-unreadable",
+          category: "maintainability",
+          severity: "info",
+          title: "File could not be read",
+          message: fileResult.reason,
+          file: relativeFile,
+          suggestion: "Check file permissions if this file should be included in launch-readiness scans."
+        });
+      }
       continue;
     }
     const content = fileResult.content;
-    if (statResult.size > LARGE_FILE_WARNING_BYTES) {
-      largeFiles++;
-      largeFileCandidates.push({
-        relativeFile,
-        size: statResult.size
-      });
-    }
     const usesAI = aiKeywords.some(
       (keyword) => content.toLowerCase().includes(keyword.toLowerCase())
     );
-    if (usesAI) {
+    if (runAiChecks && usesAI) {
       aiFiles++;
       const hasRateLimit = content.includes("rateLimit") || content.includes("ratelimit") || content.includes("upstash") || content.includes("limiter");
       if (apiRouteSet.has(file) && !hasRateLimit) {
@@ -287,7 +326,7 @@ async function scanProject(projectPath) {
         });
       }
     }
-    const webhookRouteInfo = apiRouteSet.has(file) ? getWebhookRouteInfo(relativeFile, content) : null;
+    const webhookRouteInfo = runWebhookChecks && apiRouteSet.has(file) ? getWebhookRouteInfo(relativeFile, content) : null;
     if (webhookRouteInfo && !hasWebhookSignatureVerification(content, webhookRouteInfo.provider)) {
       addIssue({
         ruleId: "webhook-missing-signature-verification",
@@ -300,24 +339,26 @@ async function scanProject(projectPath) {
         fixPrompt: createWebhookSignatureFixPrompt(relativeFile)
       });
     }
-    for (const secretMatch of getHardcodedSecretMatches(content)) {
-      const warningKey = `${relativeFile}:${secretMatch.label}`;
-      if (hardcodedSecretWarningKeys.has(warningKey)) {
-        continue;
+    if (runSecurityChecks) {
+      for (const secretMatch of getHardcodedSecretMatches(content)) {
+        const warningKey = `${relativeFile}:${secretMatch.label}`;
+        if (hardcodedSecretWarningKeys.has(warningKey)) {
+          continue;
+        }
+        hardcodedSecretWarningKeys.add(warningKey);
+        addIssue({
+          ruleId: "security-hardcoded-secret",
+          category: "security",
+          severity: "critical",
+          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,
+          suggestion: "Move secrets into environment variables and rotate the value if this is a real secret.",
+          fixPrompt: createHardcodedSecretFixPrompt(relativeFile, secretMatch.label)
+        });
       }
-      hardcodedSecretWarningKeys.add(warningKey);
-      addIssue({
-        ruleId: "security-hardcoded-secret",
-        category: "security",
-        severity: "critical",
-        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,
-        suggestion: "Move secrets into environment variables and rotate the value if this is a real secret.",
-        fixPrompt: createHardcodedSecretFixPrompt(relativeFile, secretMatch.label)
-      });
     }
-    if (apiRouteSet.has(file)) {
+    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({
@@ -332,8 +373,8 @@ async function scanProject(projectPath) {
         });
       }
     }
-    const usedEnvVariables = getUsedEnvVariables(content);
-    if (envExampleVariables) {
+    const usedEnvVariables = runEnvironmentChecks || runSecurityChecks ? getUsedEnvVariables(content) : /* @__PURE__ */ new Set();
+    if (runEnvironmentChecks && envExampleVariables) {
       for (const variableName of usedEnvVariables) {
         if (shouldIgnoreEnvVariable(variableName) || envExampleVariables.has(variableName)) {
           continue;
@@ -343,7 +384,7 @@ async function scanProject(projectPath) {
         missingEnvUsages.set(variableName, filesUsingVariable);
       }
     }
-    if (isClientSideFile(relativeFile, content)) {
+    if (runSecurityChecks && isClientSideFile(relativeFile, content)) {
       for (const variableName of usedEnvVariables) {
         if (!variableName.startsWith("NEXT_PUBLIC_") && !shouldIgnoreEnvVariable(variableName)) {
           const warningKey = `${relativeFile}:${variableName}`;
@@ -422,6 +463,16 @@ function createIssueFactory(issues) {
 function getIssueIdPrefix(ruleId, category) {
   return issueIdPrefixes[ruleId] ?? `${category}-${ruleId}`;
 }
+function getEnabledChecks(checks) {
+  const checksToEnable = checks && checks.length > 0 ? checks : recommendedScanChecks;
+  return new Set(checksToEnable);
+}
+function hasCheck(enabledChecks, check) {
+  return enabledChecks.has(check);
+}
+function onlyHasCheck(enabledChecks, check) {
+  return enabledChecks.size === 1 && enabledChecks.has(check);
+}
 async function fileExists(filePath) {
   try {
     await fs.access(filePath);
@@ -508,13 +559,16 @@ async function safeReadJson(filePath) {
 }
 async function getSourceFiles(projectPath, addIssue) {
   try {
-    return await fg(sourceFilePatterns, {
+    const files = await fg(sourceFilePatterns, {
       cwd: projectPath,
       ignore: ignoredPaths,
       absolute: true,
       onlyFiles: true,
       dot: false
     });
+    return files.sort(
+      (leftFile, rightFile) => normalizePath(leftFile).localeCompare(normalizePath(rightFile))
+    );
   } catch {
     addIssue({
       ruleId: "project-source-files-unreadable",
@@ -619,8 +673,8 @@ function getWebhookRouteInfo(relativeFile, content) {
   const normalizedContent = content.toLowerCase();
   const normalizedRouteContext = `${normalizedFile}
 ${normalizedContent}`;
-  const pathLooksLikeWebhook = normalizedFile.includes("webhook") || normalizedFile.includes("callback");
-  const contentStronglySuggestsWebhook = normalizedContent.includes("stripe.webhooks") || normalizedContent.includes("constructevent(") || normalizedContent.includes("stripe-signature") || normalizedContent.includes("stripe_webhook_secret") || normalizedContent.includes("clerk_webhook_secret") || normalizedContent.includes("svix") || normalizedContent.includes("x-github-event") || normalizedContent.includes("x-hub-signature") || normalizedContent.includes("x-shopify-hmac-sha256") || normalizedContent.includes("resend") && normalizedContent.includes("webhook") || normalizedContent.includes("webhook_secret") || normalizedContent.includes("webhooksecret") || normalizedContent.includes("webhook") && (normalizedContent.includes("signature") || normalizedContent.includes("secret") || normalizedContent.includes("event"));
+  const pathLooksLikeWebhook = /(^|[\/._-])(webhook|webhooks|callback)([\/._-]|$)/.test(normalizedFile);
+  const contentStronglySuggestsWebhook = normalizedContent.includes("stripe.webhooks") || normalizedContent.includes("constructevent(") || normalizedContent.includes("stripe-signature") || normalizedContent.includes("stripe_webhook_secret") || normalizedContent.includes("clerk_webhook_secret") || normalizedContent.includes("svix") || normalizedContent.includes("x-github-event") || normalizedContent.includes("x-hub-signature") || normalizedContent.includes("x-shopify-hmac-sha256") || /\bresend\b/.test(normalizedContent) && /\bwebhook\b/.test(normalizedContent) || /\bwebhook_secret\b/.test(normalizedContent) || /\bwebhooksecret\b/.test(normalizedContent) || /\bwebhook\b/.test(normalizedContent) && /\b(signature|secret|event|payload)\b/.test(normalizedContent);
   if (!pathLooksLikeWebhook && !contentStronglySuggestsWebhook) {
     return null;
   }
@@ -631,13 +685,13 @@ ${normalizedContent}`;
   };
 }
 function getWebhookProvider(normalizedRouteContext) {
-  if (normalizedRouteContext.includes("stripe-signature") || normalizedRouteContext.includes("stripe_webhook_secret") || normalizedRouteContext.includes("stripe.webhooks") || normalizedRouteContext.includes("constructevent(") || normalizedRouteContext.includes("stripe") && normalizedRouteContext.includes("webhook")) {
+  if (normalizedRouteContext.includes("stripe-signature") || normalizedRouteContext.includes("stripe_webhook_secret") || normalizedRouteContext.includes("stripe.webhooks") || normalizedRouteContext.includes("constructevent(") || /\bstripe\b/.test(normalizedRouteContext) && /\bwebhook\b/.test(normalizedRouteContext)) {
     return "stripe";
   }
-  if (normalizedRouteContext.includes("resend") && normalizedRouteContext.includes("webhook")) {
+  if (/\bresend\b/.test(normalizedRouteContext) && /\bwebhook\b/.test(normalizedRouteContext)) {
     return "resend";
   }
-  if (normalizedRouteContext.includes("clerk_webhook_secret") || normalizedRouteContext.includes("clerk") && normalizedRouteContext.includes("webhook")) {
+  if (normalizedRouteContext.includes("clerk_webhook_secret") || /\bclerk\b/.test(normalizedRouteContext) && /\bwebhook\b/.test(normalizedRouteContext)) {
     return "clerk";
   }
   if (normalizedRouteContext.includes("x-github-event") || normalizedRouteContext.includes("x-hub-signature")) {
@@ -918,5 +972,7 @@ function getErrorCode(error) {
   return void 0;
 }
 export {
-  scanProject
+  recommendedScanChecks,
+  scanProject,
+  validScanChecks
 };

package/package.json

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