@qodfy/core 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,52 @@
+# @qodfy/core
+
+Scanner engine for Qodfy.
+
+Most developers should use the CLI:
+
+```bash
+npx qodfy scan
+```
+
+This package contains the deterministic local scanner used by the `qodfy` CLI. It is published separately so Qodfy can later support more report formats, integrations, and programmatic usage without coupling everything to terminal output.
+
+## Install
+
+```bash
+npm install @qodfy/core
+```
+
+## Usage
+
+```ts
+import { scanProject } from "@qodfy/core";
+
+const report = await scanProject(process.cwd());
+
+console.log(report.score);
+console.log(report.issues);
+```
+
+## What It Returns
+
+`scanProject(projectPath)` returns a launch-readiness report with:
+
+- project path
+- Next.js detection result
+- score from `0` to `100`
+- issues with severity, title, message, and optional file path
+- stats for scanned files, API routes, AI-related files, and large files
+
+## Local-Only
+
+`@qodfy/core` reads files from the local project path you provide. It does not call AI APIs, upload code, require login, or contact an external Qodfy server.
+
+## Repository
+
+GitHub: https://github.com/yassinifguisse1/qodfy
+
+Issues and feedback: https://github.com/yassinifguisse1/qodfy/issues
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -4,6 +4,7 @@ type Issue = {
     title: string;
     message: string;
     file?: string;
+    suggestion?: string;
 };
 type ScanReport = {
     projectPath: string;

package/dist/index.js

@@ -1,56 +1,98 @@
 // src/index.ts
-import path from "path";
 import fs from "fs/promises";
+import path from "path";
 import fg from "fast-glob";
-async function fileExists(filePath) {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function readJson(filePath) {
-  const content = await fs.readFile(filePath, "utf-8");
-  return JSON.parse(content);
-}
+var sourceFilePatterns = ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"];
+var ignoredPaths = [
+  "node_modules/**",
+  ".next/**",
+  "dist/**",
+  "build/**",
+  ".turbo/**",
+  ".vercel/**"
+];
+var aiKeywords = [
+  "openai",
+  "@ai-sdk",
+  "ai/react",
+  "anthropic",
+  "gemini",
+  "generateText",
+  "streamText",
+  "useChat"
+];
 async function scanProject(projectPath) {
+  const resolvedProjectPath = path.resolve(projectPath);
   const issues = [];
-  const packageJsonPath = path.join(projectPath, "package.json");
+  const packageJsonPath = path.join(resolvedProjectPath, "package.json");
   const hasPackageJson = await fileExists(packageJsonPath);
+  let isNextProject = false;
   if (!hasPackageJson) {
     issues.push({
       severity: "critical",
       title: "Missing package.json",
-      message: "Qodfy could not find a package.json file in this project."
+      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."
     });
-  }
-  let isNextProject = false;
-  if (hasPackageJson) {
-    const packageJson = await readJson(packageJsonPath);
-    const deps = {
-      ...packageJson.dependencies,
-      ...packageJson.devDependencies
-    };
-    isNextProject = Boolean(deps.next);
-    if (!isNextProject) {
+  } else {
+    const packageJsonResult = await safeReadJson(packageJsonPath);
+    if (!packageJsonResult.ok) {
       issues.push({
-        severity: "warning",
-        title: "Next.js not detected",
-        message: "This first version of Qodfy is optimized for Next.js projects."
+        severity: "critical",
+        title: "Could not read package.json",
+        message: packageJsonResult.reason,
+        file: "package.json",
+        suggestion: "Fix package.json so Qodfy can detect the framework and dependencies."
+      });
+    } else if (!isPackageJsonObject(packageJsonResult.data)) {
+      issues.push({
+        severity: "critical",
+        title: "Invalid package.json",
+        message: "package.json must contain a JSON object at the top level.",
+        file: "package.json",
+        suggestion: "Fix package.json so Qodfy can detect the framework and dependencies."
       });
+    } else {
+      const deps = {
+        ...packageJsonResult.data.dependencies,
+        ...packageJsonResult.data.devDependencies
+      };
+      isNextProject = Boolean(deps.next);
+      if (!isNextProject) {
+        issues.push({
+          severity: "warning",
+          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."
+        });
+      }
     }
   }
-  const envExamplePath = path.join(projectPath, ".env.example");
+  const envExamplePath = path.join(resolvedProjectPath, ".env.example");
   const hasEnvExample = await fileExists(envExamplePath);
+  let envExampleVariables = null;
   if (!hasEnvExample) {
     issues.push({
       severity: "warning",
       title: "Missing .env.example",
-      message: "Add a .env.example file so future developers know which environment variables are required."
+      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."
     });
+  } else {
+    const envExampleResult = await safeReadFile(envExamplePath);
+    if (!envExampleResult.ok) {
+      issues.push({
+        severity: "warning",
+        title: "Could not read .env.example",
+        message: envExampleResult.reason,
+        file: ".env.example",
+        suggestion: "Make sure .env.example is readable and contains variable names without real secret values."
+      });
+    } else {
+      envExampleVariables = getEnvExampleVariables(envExampleResult.content);
+    }
   }
-  const hasReadme = await fileExists(path.join(projectPath, "README.md"));
+  const hasReadme = await fileExists(path.join(resolvedProjectPath, "README.md"));
   if (!hasReadme) {
     issues.push({
       severity: "info",
@@ -58,35 +100,38 @@ async function scanProject(projectPath) {
       message: "A README helps other developers understand how to run and maintain the project."
     });
   }
-  const files = await fg(["**/*.{ts,tsx,js,jsx}"], {
-    cwd: projectPath,
-    ignore: ["node_modules/**", ".next/**", "dist/**", "build/**"],
-    absolute: true
-  });
+  const files = await getSourceFiles(resolvedProjectPath, issues);
   const apiRoutes = files.filter((file) => {
     return file.includes(`${path.sep}app${path.sep}api${path.sep}`) || file.includes(`${path.sep}pages${path.sep}api${path.sep}`);
   });
-  const aiKeywords = [
-    "openai",
-    "@ai-sdk",
-    "ai/react",
-    "anthropic",
-    "gemini",
-    "generateText",
-    "streamText"
-  ];
+  const apiRouteSet = new Set(apiRoutes);
+  const readableFiles = /* @__PURE__ */ new Map();
+  const envExampleWarningKeys = /* @__PURE__ */ new Set();
+  const clientSecretWarningKeys = /* @__PURE__ */ new Set();
   let aiFiles = 0;
   let largeFiles = 0;
   for (const file of files) {
-    const content = await fs.readFile(file, "utf-8");
-    const relativeFile = path.relative(projectPath, file);
+    const fileResult = await safeReadFile(file);
+    const relativeFile = normalizePath(path.relative(resolvedProjectPath, file));
+    if (!fileResult.ok) {
+      issues.push({
+        severity: "info",
+        title: "File could not be read",
+        message: fileResult.reason,
+        file: relativeFile
+      });
+      continue;
+    }
+    const content = fileResult.content;
+    readableFiles.set(file, content);
     if (content.length > 15e3) {
       largeFiles++;
       issues.push({
         severity: "info",
         title: "Large file detected",
         message: "Large files are harder to maintain and often appear in AI-generated codebases.",
-        file: relativeFile
+        file: relativeFile,
+        suggestion: "Consider splitting this file into smaller modules if it mixes unrelated responsibilities."
       });
     }
     const usesAI = aiKeywords.some(
@@ -95,26 +140,68 @@ async function scanProject(projectPath) {
     if (usesAI) {
       aiFiles++;
       const hasRateLimit = content.includes("rateLimit") || content.includes("ratelimit") || content.includes("upstash") || content.includes("limiter");
-      if (!hasRateLimit) {
+      if (apiRouteSet.has(file) && !hasRateLimit) {
         issues.push({
           severity: "critical",
           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
+          file: relativeFile,
+          suggestion: "Add rate limiting, usage limits, or per-user quotas before launch."
         });
       }
     }
+    const usedEnvVariables = getUsedEnvVariables(content);
+    if (envExampleVariables) {
+      for (const variableName of usedEnvVariables) {
+        if (!envExampleVariables.has(variableName)) {
+          const warningKey = `${relativeFile}:${variableName}`;
+          if (envExampleWarningKeys.has(warningKey)) {
+            continue;
+          }
+          envExampleWarningKeys.add(warningKey);
+          issues.push({
+            severity: "warning",
+            title: "Environment variable missing from .env.example",
+            message: `${variableName} is used in ${relativeFile} but is not documented in .env.example.`,
+            file: relativeFile,
+            suggestion: `Add ${variableName}= to .env.example without including a real value.`
+          });
+        }
+      }
+    }
+    if (isClientSideFile(relativeFile, content)) {
+      for (const variableName of usedEnvVariables) {
+        if (!variableName.startsWith("NEXT_PUBLIC_")) {
+          const warningKey = `${relativeFile}:${variableName}`;
+          if (clientSecretWarningKeys.has(warningKey)) {
+            continue;
+          }
+          clientSecretWarningKeys.add(warningKey);
+          issues.push({
+            severity: "warning",
+            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,
+            suggestion: "Move server-only environment variable access to a server component, API route, or server action."
+          });
+        }
+      }
+    }
   }
   for (const route of apiRoutes) {
-    const content = await fs.readFile(route, "utf-8");
-    const relativeFile = path.relative(projectPath, route);
+    const content = readableFiles.get(route);
+    if (!content) {
+      continue;
+    }
+    const relativeFile = normalizePath(path.relative(resolvedProjectPath, route));
     const hasAuth = content.includes("auth(") || content.includes("getServerSession") || content.includes("currentUser") || content.includes("clerkClient") || content.includes("session");
     if (!hasAuth) {
       issues.push({
         severity: "warning",
         title: "API route may be missing authentication",
         message: "This API route does not appear to contain an auth/session check.",
-        file: relativeFile
+        file: relativeFile,
+        suggestion: "Confirm the route is public, or add an auth/session check before handling user data."
       });
     }
   }
@@ -122,7 +209,7 @@ async function scanProject(projectPath) {
   const warningCount = issues.filter((issue) => issue.severity === "warning").length;
   const score = Math.max(0, 100 - criticalCount * 20 - warningCount * 8);
   return {
-    projectPath,
+    projectPath: resolvedProjectPath,
     isNextProject,
     score,
     issues,
@@ -134,6 +221,121 @@ async function scanProject(projectPath) {
     }
   };
 }
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function safeReadFile(filePath) {
+  try {
+    return {
+      ok: true,
+      content: await fs.readFile(filePath, "utf-8")
+    };
+  } catch (error) {
+    const code = getErrorCode(error);
+    if (code === "ENOENT") {
+      return {
+        ok: false,
+        code,
+        reason: "The file disappeared while Qodfy was scanning it."
+      };
+    }
+    if (code === "EACCES" || code === "EPERM") {
+      return {
+        ok: false,
+        code,
+        reason: "Qodfy does not have permission to read this file."
+      };
+    }
+    return {
+      ok: false,
+      code,
+      reason: "Qodfy could not read this file."
+    };
+  }
+}
+async function safeReadJson(filePath) {
+  const fileResult = await safeReadFile(filePath);
+  if (!fileResult.ok) {
+    return fileResult;
+  }
+  try {
+    return {
+      ok: true,
+      data: JSON.parse(fileResult.content)
+    };
+  } catch {
+    return {
+      ok: false,
+      reason: "package.json is not valid JSON."
+    };
+  }
+}
+async function getSourceFiles(projectPath, issues) {
+  try {
+    return await fg(sourceFilePatterns, {
+      cwd: projectPath,
+      ignore: ignoredPaths,
+      absolute: true,
+      onlyFiles: true,
+      dot: false
+    });
+  } catch {
+    issues.push({
+      severity: "critical",
+      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."
+    });
+    return [];
+  }
+}
+function getEnvExampleVariables(content) {
+  const variables = /* @__PURE__ */ new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine || trimmedLine.startsWith("#")) {
+      continue;
+    }
+    const match = trimmedLine.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*(?:=|$)/);
+    if (match) {
+      variables.add(match[1]);
+    }
+  }
+  return variables;
+}
+function getUsedEnvVariables(content) {
+  const variables = /* @__PURE__ */ new Set();
+  const dotAccessPattern = /\bprocess\.env\.([A-Za-z_][A-Za-z0-9_]*)/g;
+  const bracketAccessPattern = /\bprocess\.env\[['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\]/g;
+  for (const match of content.matchAll(dotAccessPattern)) {
+    variables.add(match[1]);
+  }
+  for (const match of content.matchAll(bracketAccessPattern)) {
+    variables.add(match[1]);
+  }
+  return variables;
+}
+function isClientSideFile(relativeFile, content) {
+  const fileName = path.basename(relativeFile);
+  return fileName.includes(".client.") || /(^|\n)\s*["']use client["'];?/.test(content);
+}
+function isPackageJsonObject(data) {
+  return typeof data === "object" && data !== null && !Array.isArray(data);
+}
+function normalizePath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+function getErrorCode(error) {
+  if (error && typeof error === "object" && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  return void 0;
+}
 export {
   scanProject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodfy/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scanner engine for Qodfy, an open-source launch readiness scanner for AI-built apps.",
   "keywords": [
     "qodfy",
@@ -33,7 +33,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "license": "MIT",
   "engines": {