predeploy-check 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# predeploy-check
+
+> Catch deployment failures **before** you push. Scans your project for known Render & Vercel pitfalls.
+
+```bash
+npx predeploy-check
+```
+
+No install required — just run it in your project directory.
+
+## What it checks
+
+| # | Check | Targets | Status |
+|---|-------|---------|--------|
+| 1 | **Python + Render** | Rust-compiled deps (pydantic, fastapi, orjson…) on Python ≥ 3.13 | ⚠️ Warn |
+| 2 | **ESLint + Vercel** | Mismatched eslint / eslint-config-next versions; deprecated `ignoreDuringBuilds` on Next 16+ | ❌ Fail / ⚠️ Warn |
+| 3 | **Case Sensitivity** | Import paths that differ in casing from actual filenames (breaks on Linux) | ⚠️ Warn |
+| 4 | **Missing Engines** | No `"engines"` field in package.json | ⚠️ Warn |
+| 5 | **Env Var Check** | `process.env.X` references not declared in `.env` / `.env.example` | ⚠️ Warn |
+| 6 | **Render Start Cmd** | No Procfile, no `"start"` script, no render.yaml start command | ❌ Fail |
+
+## Output
+
+Clean, colored terminal output with:
+- ✅ / ⚠️ / ❌ per check
+- File and line context
+- One-line suggested fix
+
+Exit code `1` if any ❌ failures, `0` otherwise.
+
+## Usage
+
+```bash
+# Scan current directory
+npx predeploy-check
+
+# Scan a specific project
+npx predeploy-check ./my-project
+
+# Show help
+npx predeploy-check --help
+```
+
+## Adding custom checks
+
+Create a new file in the `checks/` folder:
+
+```js
+// checks/07-my-check.js
+'use strict';
+
+const name = 'My Custom Check';
+
+async function run(projectRoot) {
+  // Your check logic here
+  return {
+    status: 'pass',  // 'pass' | 'warn' | 'fail' | 'skip'
+    message: 'Everything looks good',
+    fix: 'Suggested fix if status is warn or fail',
+    details: [
+      { file: 'some-file.js', line: 42, message: 'Detail about the issue' }
+    ],
+  };
+}
+
+module.exports = { name, run };
+```
+
+Checks are loaded alphabetically, so prefix with a number to control order.
+
+## License
+
+MIT
+"# predeploy_check" 

package/bin/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const path = require('path');
+const { runAllChecks } = require('../index');
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+  predeploy-check — catch deployment failures before they happen
+
+  Usage:
+    npx predeploy-check [directory]
+
+  Arguments:
+    directory   Path to the project to scan (defaults to current directory)
+
+  Options:
+    -h, --help      Show this help message
+    -v, --version   Show version number
+
+  Checks:
+    1. Python + Render:    Rust-compiled deps on unsupported Python versions
+    2. ESLint + Vercel:    Peer-dependency mismatches in Next.js projects
+    3. Case Sensitivity:   Import paths that differ from actual filenames
+    4. Missing Engines:    No "engines" field in package.json
+    5. Env Var Check:      process.env references missing from .env files
+    6. Render Start Cmd:   Missing start command for Render deployments
+`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const projectRoot = path.resolve(args[0] || process.cwd());
+
+runAllChecks(projectRoot).then((exitCode) => {
+  process.exit(exitCode);
+}).catch((err) => {
+  console.error('Fatal error:', err.message);
+  process.exit(2);
+});

package/checks/01-python-render.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const name = 'Python + Render: Rust-compiled dependencies';
+
+// Packages known to have Rust-compiled components that may lack
+// prebuilt wheels for bleeding-edge Python versions.
+const RUST_DEP_PACKAGES = [
+  'pydantic',
+  'pydantic-core',
+  'fastapi',
+  'orjson',
+  'cryptography',
+  'tiktoken',
+  'tokenizers',
+  'safetensors',
+  'polars',
+  'ruff',
+  'rpds-py',
+  'jiter',
+];
+
+/**
+ * Parse a Python version string like "python-3.13.2" or "3.13" into
+ * { major, minor } or null if unparseable.
+ */
+function parsePythonVersion(raw) {
+  const match = raw.match(/(\d+)\.(\d+)/);
+  if (!match) return null;
+  return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10) };
+}
+
+/**
+ * Parse requirements.txt and return an array of lowercase package names.
+ */
+function parseRequirements(content) {
+  return content
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#') && !line.startsWith('-'))
+    .map((line) => {
+      // Strip version specifiers, extras, etc.
+      const name = line.split(/[>=<!~\[;@\s]/)[0];
+      return name.toLowerCase().replace(/_/g, '-');
+    })
+    .filter(Boolean);
+}
+
+async function run(projectRoot) {
+  const runtimePath = path.join(projectRoot, 'runtime.txt');
+  const requirementsPath = path.join(projectRoot, 'requirements.txt');
+
+  // Check if this is a Python project at all
+  if (!fs.existsSync(runtimePath) && !fs.existsSync(requirementsPath)) {
+    return {
+      status: 'skip',
+      message: `${name} — no Python project detected`,
+    };
+  }
+
+  // If there's no runtime.txt, we can't check the version
+  if (!fs.existsSync(runtimePath)) {
+    return {
+      status: 'skip',
+      message: `${name} — no runtime.txt found, skipping version check`,
+    };
+  }
+
+  const runtimeContent = fs.readFileSync(runtimePath, 'utf-8').trim();
+  const version = parsePythonVersion(runtimeContent);
+
+  if (!version) {
+    return {
+      status: 'warn',
+      message: `${name} — could not parse Python version from runtime.txt`,
+      fix: 'Ensure runtime.txt contains a valid version like "python-3.12.3"',
+      details: [{ file: 'runtime.txt', message: `Content: "${runtimeContent}"` }],
+    };
+  }
+
+  // Only flag Python >= 3.13
+  if (version.major < 3 || (version.major === 3 && version.minor < 13)) {
+    return {
+      status: 'pass',
+      message: `${name} — Python ${version.major}.${version.minor} is well-supported`,
+    };
+  }
+
+  // Now check requirements.txt for Rust-compiled deps
+  if (!fs.existsSync(requirementsPath)) {
+    return {
+      status: 'warn',
+      message: `${name} — Python ${version.major}.${version.minor} detected but no requirements.txt found`,
+      fix: 'Add a requirements.txt or pin Python to 3.12 in runtime.txt',
+      details: [{ file: 'runtime.txt' }],
+    };
+  }
+
+  const reqContent = fs.readFileSync(requirementsPath, 'utf-8');
+  const packages = parseRequirements(reqContent);
+  const flagged = packages.filter((pkg) => RUST_DEP_PACKAGES.includes(pkg));
+
+  if (flagged.length === 0) {
+    return {
+      status: 'pass',
+      message: `${name} — Python ${version.major}.${version.minor} with no known Rust-compiled deps`,
+    };
+  }
+
+  return {
+    status: 'warn',
+    message: `${name} — Python ${version.major}.${version.minor} with Rust-compiled dependencies`,
+    fix: `Pin to Python 3.12 in runtime.txt ("python-3.12.7") or verify wheel availability for ${version.major}.${version.minor}`,
+    details: flagged.map((pkg) => ({
+      file: 'requirements.txt',
+      message: `"${pkg}" has Rust-compiled components — prebuilt wheels may not exist for Python ${version.major}.${version.minor}`,
+    })),
+  };
+}
+
+module.exports = { name, run };

package/checks/02-eslint-vercel.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const name = 'ESLint + Vercel: Next.js peer-dependency conflicts';
+
+/**
+ * Parse a semver-like version string and return the major version number.
+ * Handles ranges like "^9.0.0", "~8.2.0", ">=9.0.0", "9.x", etc.
+ */
+function extractMajor(versionRange) {
+  if (!versionRange) return null;
+  const match = versionRange.match(/(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Normalize a version range to a comparable string by stripping
+ * range prefixes like ^, ~, >=, etc.
+ */
+function normalizeRange(versionRange) {
+  if (!versionRange) return '';
+  return versionRange.replace(/^[\^~>=<\s]+/, '').trim();
+}
+
+async function run(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    return {
+      status: 'skip',
+      message: `${name} — no package.json found`,
+    };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return {
+      status: 'fail',
+      message: `${name} — could not parse package.json`,
+      fix: 'Fix JSON syntax errors in package.json',
+      details: [{ file: 'package.json' }],
+    };
+  }
+
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const results = [];
+
+  // Check if this is a Next.js project
+  const hasNext = !!allDeps['next'];
+  const hasEslint = !!allDeps['eslint'];
+  const hasEslintConfigNext = !!allDeps['eslint-config-next'];
+
+  if (!hasNext) {
+    return {
+      status: 'skip',
+      message: `${name} — not a Next.js project`,
+    };
+  }
+
+  // ── Check 1: ESLint / eslint-config-next version mismatch ──
+
+  if (hasEslint && hasEslintConfigNext) {
+    const eslintMajor = extractMajor(allDeps['eslint']);
+    const configNextMajor = extractMajor(allDeps['eslint-config-next']);
+    const nextMajor = extractMajor(allDeps['next']);
+
+    // eslint-config-next should typically match the Next.js major version
+    if (configNextMajor !== null && nextMajor !== null && configNextMajor !== nextMajor) {
+      results.push({
+        status: 'fail',
+        message: `${name} — eslint-config-next@${allDeps['eslint-config-next']} does not match next@${allDeps['next']}`,
+        fix: `Run: npm install eslint-config-next@${nextMajor} to align with your Next.js version`,
+        details: [
+          { file: 'package.json', message: `eslint-config-next: ${allDeps['eslint-config-next']}` },
+          { file: 'package.json', message: `next: ${allDeps['next']}` },
+        ],
+      });
+    }
+
+    // ESLint 9+ flat config vs older eslint-config-next
+    if (eslintMajor !== null && eslintMajor >= 9 && configNextMajor !== null && configNextMajor < 15) {
+      results.push({
+        status: 'warn',
+        message: `${name} — ESLint ${eslintMajor}.x may have peer-dep conflicts with eslint-config-next@${allDeps['eslint-config-next']}`,
+        fix: 'Upgrade eslint-config-next to a version compatible with ESLint 9+ flat config, or downgrade ESLint to 8.x',
+        details: [
+          { file: 'package.json', message: `eslint: ${allDeps['eslint']}` },
+          { file: 'package.json', message: `eslint-config-next: ${allDeps['eslint-config-next']}` },
+        ],
+      });
+    }
+  }
+
+  // ── Check 2: Deprecated eslint.ignoreDuringBuilds for Next 16+ ──
+
+  const nextMajor = extractMajor(allDeps['next']);
+
+  if (nextMajor !== null && nextMajor >= 16) {
+    // Check multiple possible config file names
+    const configNames = [
+      'next.config.js',
+      'next.config.mjs',
+      'next.config.ts',
+    ];
+
+    for (const configName of configNames) {
+      const configPath = path.join(projectRoot, configName);
+      if (fs.existsSync(configPath)) {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        if (content.includes('ignoreDuringBuilds')) {
+          results.push({
+            status: 'warn',
+            message: `${name} — deprecated eslint.ignoreDuringBuilds in ${configName}`,
+            fix: 'Next.js 16+ removed built-in ESLint integration. Remove eslint.ignoreDuringBuilds from your config and use a separate ESLint step.',
+            details: [{ file: configName, message: 'Contains deprecated "ignoreDuringBuilds" setting' }],
+          });
+        }
+      }
+    }
+  }
+
+  if (results.length === 0) {
+    return {
+      status: 'pass',
+      message: `${name} — ESLint configuration looks correct`,
+    };
+  }
+
+  return results;
+}
+
+module.exports = { name, run };

package/checks/03-case-sensitivity.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const name = 'Case Sensitivity: import path mismatches';
+
+// File extensions to scan for import statements
+const SCAN_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.mts']);
+
+// Directories to skip
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', '.vercel',
+  '.output', 'coverage', '__pycache__', '.cache',
+]);
+
+/**
+ * Recursively collect all scannable files.
+ */
+function collectFiles(dir, files = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) {
+        collectFiles(path.join(dir, entry.name), files);
+      }
+    } else if (entry.isFile() && SCAN_EXTENSIONS.has(path.extname(entry.name))) {
+      files.push(path.join(dir, entry.name));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract relative import paths from a file's content.
+ * Returns array of { line, importPath } objects.
+ */
+function extractImports(content) {
+  const imports = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Match: import ... from './path' or import ... from "../path"
+    // Match: require('./path') or require("../path")
+    // Match: import('./path') dynamic imports
+    const patterns = [
+      /(?:from|require|import)\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g,
+      /from\s+['"](\.[^'"]+)['"]/g,
+    ];
+
+    for (const pattern of patterns) {
+      let match;
+      while ((match = pattern.exec(line)) !== null) {
+        imports.push({
+          line: i + 1,
+          importPath: match[1],
+        });
+      }
+    }
+  }
+
+  return imports;
+}
+
+/**
+ * Build a map of directory → Set of actual filenames (preserving case).
+ */
+function buildFilenameCache(projectRoot) {
+  const cache = new Map();
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    const names = new Set();
+    for (const entry of entries) {
+      names.add(entry.name);
+      if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+        walk(path.join(dir, entry.name));
+      }
+    }
+    cache.set(dir, names);
+  }
+
+  walk(projectRoot);
+  return cache;
+}
+
+/**
+ * Resolve an import path to an actual file, trying common extensions.
+ * Returns { resolved, actual } where:
+ *   - resolved is the expected filename from the import
+ *   - actual is the real filename on disk (may differ in case)
+ *   - null if the file doesn't exist at all
+ */
+function resolveImport(importPath, fromFile, filenameCache) {
+  const fromDir = path.dirname(fromFile);
+  const resolved = path.resolve(fromDir, importPath);
+  const dir = path.dirname(resolved);
+  const basename = path.basename(resolved);
+
+  const dirFiles = filenameCache.get(dir);
+  if (!dirFiles) return null;
+
+  // Extensions to try if the import has no extension
+  const ext = path.extname(basename);
+  const candidates = ext
+    ? [basename]
+    : [
+        `${basename}.js`, `${basename}.ts`, `${basename}.jsx`, `${basename}.tsx`,
+        `${basename}.mjs`, `${basename}.mts`,
+        // index files
+        `${basename}/index.js`, `${basename}/index.ts`,
+        `${basename}/index.jsx`, `${basename}/index.tsx`,
+      ];
+
+  for (const candidate of candidates) {
+    // Handle directory/index patterns
+    if (candidate.includes('/')) {
+      const [subDir, indexFile] = candidate.split('/');
+      const subDirPath = path.join(dir, subDir);
+      const subFiles = filenameCache.get(subDirPath);
+
+      if (subFiles) {
+        // Check if directory name itself has a case mismatch
+        if (dirFiles) {
+          for (const actual of dirFiles) {
+            if (actual.toLowerCase() === subDir.toLowerCase() && actual !== subDir) {
+              return { expected: subDir, actual, type: 'directory' };
+            }
+          }
+        }
+        // Check index file inside the directory
+        for (const actual of subFiles) {
+          if (actual.toLowerCase() === indexFile.toLowerCase() && actual !== indexFile) {
+            return { expected: indexFile, actual, type: 'file' };
+          }
+        }
+      }
+      continue;
+    }
+
+    // Direct file match
+    for (const actual of dirFiles) {
+      if (actual.toLowerCase() === candidate.toLowerCase()) {
+        if (actual !== candidate) {
+          return { expected: candidate, actual, type: 'file' };
+        }
+        // Exact match — no case issue
+        return null;
+      }
+    }
+  }
+
+  return null; // File not found at all — not a case issue, just a missing file
+}
+
+async function run(projectRoot) {
+  const files = collectFiles(projectRoot);
+
+  if (files.length === 0) {
+    return {
+      status: 'skip',
+      message: `${name} — no JS/TS files found to scan`,
+    };
+  }
+
+  const filenameCache = buildFilenameCache(projectRoot);
+  const mismatches = [];
+
+  for (const file of files) {
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const imports = extractImports(content);
+
+    for (const imp of imports) {
+      const result = resolveImport(imp.importPath, file, filenameCache);
+      if (result) {
+        const relFile = path.relative(projectRoot, file);
+        mismatches.push({
+          file: relFile,
+          line: imp.line,
+          importPath: imp.importPath,
+          expected: result.expected,
+          actual: result.actual,
+        });
+      }
+    }
+  }
+
+  if (mismatches.length === 0) {
+    return {
+      status: 'pass',
+      message: `${name} — all ${files.length} files checked, no case mismatches found`,
+    };
+  }
+
+  return {
+    status: 'warn',
+    message: `${name} — ${mismatches.length} case mismatch(es) found (will fail on Vercel's Linux filesystem)`,
+    fix: 'Rename the import paths to exactly match the filename casing on disk',
+    details: mismatches.map((m) => ({
+      file: m.file,
+      line: m.line,
+      message: `Import "${m.importPath}" references "${m.expected}" but file on disk is "${m.actual}"`,
+    })),
+  };
+}
+
+module.exports = { name, run };

package/checks/04-missing-engines.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const name = 'Missing Engines Field: Node.js version';
+
+async function run(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    return {
+      status: 'skip',
+      message: `${name} — no package.json found`,
+    };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return {
+      status: 'fail',
+      message: `${name} — could not parse package.json`,
+      fix: 'Fix JSON syntax errors in package.json',
+      details: [{ file: 'package.json' }],
+    };
+  }
+
+  if (!pkg.engines) {
+    return {
+      status: 'warn',
+      message: `${name} — no "engines" field in package.json`,
+      fix: 'Add "engines": { "node": ">=18.0.0" } to package.json to lock the Node.js version on your platform',
+      details: [{ file: 'package.json', message: 'Missing "engines" field — platform may default to an unexpected Node.js version' }],
+    };
+  }
+
+  if (!pkg.engines.node) {
+    return {
+      status: 'warn',
+      message: `${name} — "engines" exists but no "node" version specified`,
+      fix: 'Add "node": ">=18.0.0" inside the "engines" field in package.json',
+      details: [{ file: 'package.json', message: 'engines field exists but does not specify a node version' }],
+    };
+  }
+
+  return {
+    status: 'pass',
+    message: `${name} — Node.js engine specified: ${pkg.engines.node}`,
+  };
+}
+
+module.exports = { name, run };

package/checks/05-env-vars.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const name = 'Env Var Check: undeclared environment variables';
+
+// File extensions to scan
+const SCAN_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.mts']);
+
+// Directories to skip
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', '.vercel',
+  '.output', 'coverage', '__pycache__', '.cache',
+]);
+
+// Common built-in env vars to ignore
+const BUILTIN_VARS = new Set([
+  'NODE_ENV', 'PORT', 'HOME', 'PATH', 'PWD', 'USER', 'HOSTNAME',
+  'CI', 'VERCEL', 'VERCEL_ENV', 'VERCEL_URL', 'VERCEL_REGION',
+  'RENDER', 'RENDER_EXTERNAL_URL', 'RENDER_SERVICE_NAME',
+  'IS_PULL_REQUEST', 'RENDER_GIT_COMMIT', 'RENDER_GIT_BRANCH',
+  'NEXT_RUNTIME', 'npm_lifecycle_event', 'npm_package_name',
+]);
+
+/**
+ * Recursively collect all scannable files.
+ */
+function collectFiles(dir, files = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) {
+        collectFiles(path.join(dir, entry.name), files);
+      }
+    } else if (entry.isFile() && SCAN_EXTENSIONS.has(path.extname(entry.name))) {
+      files.push(path.join(dir, entry.name));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Parse a .env file and return a Set of variable names.
+ */
+function parseEnvFile(filePath) {
+  const vars = new Set();
+  if (!fs.existsSync(filePath)) return vars;
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (match) {
+      vars.add(match[1]);
+    }
+  }
+
+  return vars;
+}
+
+/**
+ * Scan a file for process.env.VAR_NAME references.
+ * Returns array of { line, varName }.
+ */
+function extractEnvReferences(content) {
+  const refs = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Skip comment-only lines
+    const trimmed = line.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+      continue;
+    }
+
+    // Match process.env.VARIABLE_NAME
+    const pattern = /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      refs.push({
+        line: i + 1,
+        varName: match[1],
+      });
+    }
+
+    // Match process.env['VAR_NAME'] or process.env["VAR_NAME"]
+    const bracketPattern = /process\.env\[['"]([A-Za-z_][A-Za-z0-9_]*)['"]\]/g;
+    while ((match = bracketPattern.exec(line)) !== null) {
+      refs.push({
+        line: i + 1,
+        varName: match[1],
+      });
+    }
+  }
+
+  return refs;
+}
+
+async function run(projectRoot) {
+  // Gather declared env vars from .env files
+  const envFiles = ['.env.example', '.env.local', '.env'];
+  const declaredVars = new Set();
+  let foundEnvFile = false;
+
+  for (const envFile of envFiles) {
+    const envPath = path.join(projectRoot, envFile);
+    if (fs.existsSync(envPath)) {
+      foundEnvFile = true;
+      const vars = parseEnvFile(envPath);
+      for (const v of vars) declaredVars.add(v);
+    }
+  }
+
+  // Scan source files
+  const files = collectFiles(projectRoot);
+
+  if (files.length === 0) {
+    return {
+      status: 'skip',
+      message: `${name} — no JS/TS files found to scan`,
+    };
+  }
+
+  // Collect all env var references
+  const allRefs = new Map(); // varName → [{ file, line }]
+
+  for (const file of files) {
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const refs = extractEnvReferences(content);
+    for (const ref of refs) {
+      if (BUILTIN_VARS.has(ref.varName)) continue;
+
+      if (!allRefs.has(ref.varName)) {
+        allRefs.set(ref.varName, []);
+      }
+      allRefs.get(ref.varName).push({
+        file: path.relative(projectRoot, file),
+        line: ref.line,
+      });
+    }
+  }
+
+  if (allRefs.size === 0) {
+    return {
+      status: 'pass',
+      message: `${name} — no custom environment variables referenced in code`,
+    };
+  }
+
+  if (!foundEnvFile) {
+    // All referenced vars are undeclared since there's no env file
+    const varNames = [...allRefs.keys()];
+    return {
+      status: 'warn',
+      message: `${name} — ${varNames.length} env var(s) referenced but no .env / .env.example file found`,
+      fix: 'Create a .env.example file listing all required environment variables',
+      details: varNames.slice(0, 15).map((v) => {
+        const locs = allRefs.get(v);
+        return {
+          file: locs[0].file,
+          line: locs[0].line,
+          message: `process.env.${v} — not declared in any .env file`,
+        };
+      }),
+    };
+  }
+
+  // Find undeclared vars
+  const undeclared = [];
+  for (const [varName, locations] of allRefs) {
+    if (!declaredVars.has(varName)) {
+      undeclared.push({ varName, locations });
+    }
+  }
+
+  if (undeclared.length === 0) {
+    return {
+      status: 'pass',
+      message: `${name} — all ${allRefs.size} referenced env vars are declared`,
+    };
+  }
+
+  return {
+    status: 'warn',
+    message: `${name} — ${undeclared.length} env var(s) referenced in code but not declared in .env files`,
+    fix: 'Add the missing variables to .env.example and configure them in your deployment platform\'s env settings',
+    details: undeclared.slice(0, 15).map((u) => ({
+      file: u.locations[0].file,
+      line: u.locations[0].line,
+      message: `process.env.${u.varName} — used in ${u.locations.length} file(s) but not declared`,
+    })),
+  };
+}
+
+module.exports = { name, run };

package/checks/06-render-start.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const name = 'Render Start Command: missing start configuration';
+
+async function run(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  const procfilePath = path.join(projectRoot, 'Procfile');
+  const renderYamlPath = path.join(projectRoot, 'render.yaml');
+
+  const hasPkg = fs.existsSync(pkgPath);
+  const hasProcfile = fs.existsSync(procfilePath);
+  const hasRenderYaml = fs.existsSync(renderYamlPath);
+
+  // Check for Python project (has requirements.txt but no package.json)
+  const hasRequirements = fs.existsSync(path.join(projectRoot, 'requirements.txt'));
+  const isPython = hasRequirements && !hasPkg;
+
+  // ── Python project checks ──
+  if (isPython) {
+    if (hasProcfile) {
+      const procContent = fs.readFileSync(procfilePath, 'utf-8').trim();
+      if (procContent.match(/^web:/m)) {
+        return {
+          status: 'pass',
+          message: `${name} — Procfile found with web process`,
+        };
+      }
+    }
+
+    // Check for common Python entry points
+    const commonEntries = ['app.py', 'main.py', 'wsgi.py', 'asgi.py', 'manage.py'];
+    const foundEntries = commonEntries.filter((f) => fs.existsSync(path.join(projectRoot, f)));
+
+    if (hasProcfile) {
+      return {
+        status: 'pass',
+        message: `${name} — Procfile found`,
+      };
+    }
+
+    if (hasRenderYaml) {
+      return {
+        status: 'pass',
+        message: `${name} — render.yaml found with start command`,
+      };
+    }
+
+    return {
+      status: 'fail',
+      message: `${name} — no Procfile or render.yaml for Python project`,
+      fix: 'Create a Procfile with: web: gunicorn app:app (or your appropriate start command)',
+      details: foundEntries.length > 0
+        ? [{ file: foundEntries[0], message: `Found "${foundEntries[0]}" — add a Procfile to specify how to start it` }]
+        : [{ message: 'No common Python entry point found (app.py, main.py, etc.)' }],
+    };
+  }
+
+  // ── Node.js project checks ──
+  if (!hasPkg) {
+    return {
+      status: 'skip',
+      message: `${name} — no package.json found, not a Node.js project`,
+    };
+  }
+
+  // If there's a Procfile, that takes precedence
+  if (hasProcfile) {
+    return {
+      status: 'pass',
+      message: `${name} — Procfile found`,
+    };
+  }
+
+  // If there's a render.yaml, that takes precedence
+  if (hasRenderYaml) {
+    const content = fs.readFileSync(renderYamlPath, 'utf-8');
+    if (content.includes('startCommand')) {
+      return {
+        status: 'pass',
+        message: `${name} — render.yaml with startCommand found`,
+      };
+    }
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return {
+      status: 'fail',
+      message: `${name} — could not parse package.json`,
+      fix: 'Fix JSON syntax errors in package.json',
+      details: [{ file: 'package.json' }],
+    };
+  }
+
+  // Check for "start" script
+  if (pkg.scripts && pkg.scripts.start) {
+    return {
+      status: 'pass',
+      message: `${name} — "start" script found: "${pkg.scripts.start}"`,
+    };
+  }
+
+  // Check if "main" field points to a file
+  if (pkg.main && fs.existsSync(path.join(projectRoot, pkg.main))) {
+    return {
+      status: 'warn',
+      message: `${name} — no "start" script, but "main" field points to "${pkg.main}"`,
+      fix: 'Add a "start" script to package.json, e.g.: "start": "node ' + pkg.main + '"',
+      details: [{ file: 'package.json', message: 'Render needs an explicit start command; "main" alone may not be used' }],
+    };
+  }
+
+  return {
+    status: 'fail',
+    message: `${name} — no start command found`,
+    fix: 'Add a "start" script to package.json (e.g. "start": "node server.js") or create a Procfile',
+    details: [
+      { file: 'package.json', message: 'No "start" script in "scripts"' },
+      { message: 'No Procfile found' },
+      hasRenderYaml
+        ? { file: 'render.yaml', message: 'render.yaml exists but has no "startCommand"' }
+        : { message: 'No render.yaml found' },
+    ],
+  };
+}
+
+module.exports = { name, run };

package/index.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs');
+
+// Dynamically load all check modules from /checks/
+const checksDir = path.join(__dirname, 'checks');
+const checkFiles = fs.readdirSync(checksDir)
+  .filter((f) => f.endsWith('.js'))
+  .sort();
+
+const checks = checkFiles.map((f) => {
+  const mod = require(path.join(checksDir, f));
+  return {
+    name: mod.name || f.replace('.js', ''),
+    run: mod.run,
+  };
+});
+
+const STATUS_ICONS = {
+  pass: chalk.green('✅'),
+  warn: chalk.yellow('⚠️ '),
+  fail: chalk.red('❌'),
+  skip: chalk.gray('⏭️ '),
+};
+
+const STATUS_COLORS = {
+  pass: chalk.green,
+  warn: chalk.yellow,
+  fail: chalk.red,
+  skip: chalk.gray,
+};
+
+/**
+ * Format a single result line.
+ */
+function formatResult(result) {
+  const icon = STATUS_ICONS[result.status] || '?';
+  const color = STATUS_COLORS[result.status] || chalk.white;
+  const lines = [];
+
+  lines.push(`${icon} ${color.bold(result.message)}`);
+
+  if (result.details && result.details.length > 0) {
+    for (const detail of result.details) {
+      const loc = detail.file
+        ? chalk.dim(`  ${detail.file}${detail.line ? `:${detail.line}` : ''}`)
+        : '';
+      if (loc) lines.push(loc);
+      if (detail.message) lines.push(chalk.dim(`    → ${detail.message}`));
+    }
+  }
+
+  if (result.fix && result.status !== 'pass') {
+    lines.push(chalk.cyan(`  💡 Fix: ${result.fix}`));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Run all checks against the given project root.
+ * Returns exit code: 1 if any ❌, 0 otherwise.
+ */
+async function runAllChecks(projectRoot) {
+  console.log('');
+  console.log(chalk.bold.underline(`  predeploy-check`) + chalk.dim(`  scanning ${projectRoot}`));
+  console.log(chalk.dim('  ─'.repeat(30)));
+  console.log('');
+
+  let hasFail = false;
+  let passCount = 0;
+  let warnCount = 0;
+  let failCount = 0;
+  let skipCount = 0;
+
+  for (const check of checks) {
+    try {
+      const results = await check.run(projectRoot);
+
+      // A check can return a single result or an array of results
+      const resultArray = Array.isArray(results) ? results : [results];
+
+      for (const result of resultArray) {
+        console.log(formatResult(result));
+        console.log('');
+
+        if (result.status === 'fail') {
+          hasFail = true;
+          failCount++;
+        } else if (result.status === 'warn') {
+          warnCount++;
+        } else if (result.status === 'skip') {
+          skipCount++;
+        } else {
+          passCount++;
+        }
+      }
+    } catch (err) {
+      console.log(chalk.red(`❌ ${check.name}: internal error — ${err.message}`));
+      console.log('');
+      hasFail = true;
+      failCount++;
+    }
+  }
+
+  // Summary bar
+  console.log(chalk.dim('  ─'.repeat(30)));
+
+  const parts = [];
+  if (passCount > 0) parts.push(chalk.green(`${passCount} passed`));
+  if (warnCount > 0) parts.push(chalk.yellow(`${warnCount} warnings`));
+  if (failCount > 0) parts.push(chalk.red(`${failCount} failed`));
+  if (skipCount > 0) parts.push(chalk.gray(`${skipCount} skipped`));
+
+  console.log(`\n  ${chalk.bold('Summary:')} ${parts.join(chalk.dim(' · '))}`);
+
+  if (hasFail) {
+    console.log(chalk.red.bold('\n  Deploy will likely fail. Fix ❌ issues above.\n'));
+  } else if (warnCount > 0) {
+    console.log(chalk.yellow('\n  Some warnings detected. Review ⚠️  items above.\n'));
+  } else {
+    console.log(chalk.green.bold('\n  All checks passed! You\'re good to deploy. 🚀\n'));
+  }
+
+  return hasFail ? 1 : 0;
+}
+
+module.exports = { runAllChecks };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "predeploy-check",
+  "version": "1.0.0",
+  "description": "Scan a project folder and flag known deployment-failure patterns for Render and Vercel before you push.",
+  "main": "index.js",
+  "bin": {
+    "predeploy-check": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node bin/cli.js"
+  },
+  "keywords": [
+    "deploy",
+    "vercel",
+    "render",
+    "lint",
+    "pre-deploy",
+    "ci",
+    "deployment",
+    "check"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "checks/",
+    "index.js",
+    "README.md"
+  ]
+}