predeploy-check 1.0.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alok Kushwaha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,74 +1,105 @@
-# 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" 
+# 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 — add `--live` to verify against PyPI instead of guessing | ⚠️ Warn / ❌ Fail (live) |
+| 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
+
+# Verify Python wheel availability live against PyPI, instead of
+# relying on the built-in known-package list (slower, needs internet)
+npx predeploy-check --live
+
+# Show help
+npx predeploy-check --help
+```
+
+By default, the Python + Render check warns based on a built-in list of
+packages known to have Rust-compiled components — it's instant and works
+offline, but the list can go stale as packages ship new wheels over time.
+Pass `--live` to query PyPI directly for the exact pinned version in your
+`requirements.txt`, which turns a "might be missing" warning into a
+confirmed pass or fail.
+
+## 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.
+
+## Testing
+
+The project has a full test suite (49 tests covering all 6 checks) built
+on Node's built-in test runner — no extra dependencies needed.
+
+```bash
+npm test
+```
+
+## Contributing
+
+Found a deploy-only failure that isn't on this list? Open an issue or a
+PR — the project is intentionally narrow right now (six checks), and it
+gets more useful with every real-world gotcha someone adds.
+
+## Author
+
+Built by [Alok Kushwaha](https://github.com/Alok-Fusion) — NLP/ML
+engineer, born out of a real afternoon lost to a deploy failure that
+had nothing to do with the actual code.
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

package/bin/cli.js

@@ -1,48 +1,50 @@
-#!/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);
-});
+#!/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
+    --live          Verify Python wheel availability against PyPI (slower, needs internet)
+
+  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.find((a) => !a.startsWith('-')) || process.cwd());
+const options = { live: args.includes('--live') };
+
+runAllChecks(projectRoot, options).then((exitCode) => {
+  process.exit(exitCode);
+}).catch((err) => {
+  console.error('Fatal error:', err.message);
+  process.exit(2);
+});

package/checks/01-python-render.js

@@ -1,123 +1,207 @@
-'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 };
+'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 { name, version } where
+ * version is the pinned version if one was specified with "==", else null.
+ */
+function parseRequirements(content) {
+  return content
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#') && !line.startsWith('-'))
+    .map((line) => {
+      const beforeSemicolon = line.split(';')[0].trim(); // strip env markers
+      const name = beforeSemicolon.split(/[>=<!~\[\s]/)[0].toLowerCase().replace(/_/g, '-');
+      const pinMatch = beforeSemicolon.match(/==\s*([\d][\w.]*)/);
+      return { name, version: pinMatch ? pinMatch[1] : null };
+    })
+    .filter((pkg) => pkg.name);
+}
+
+/**
+ * Query PyPI's JSON API to check whether a prebuilt wheel exists for the
+ * given package, version, and CPython minor version (e.g. "313" for 3.13).
+ * Returns true/false/null (null = couldn't determine, e.g. network error
+ * or unpinned version — caller should fall back to the static warning).
+ */
+async function checkWheelAvailability(pkgName, pkgVersion, major, minor) {
+  if (!pkgVersion) return null; // no pinned version, can't query a specific release
+
+  if (typeof fetch !== 'function') {
+    // Node < 18 has no global fetch. Treat as unknown rather than crashing,
+    // so --live degrades to the same "unverified" warn path as a network failure.
+    return null;
+  }
+
+  const cpTag = `cp${major}${minor}`;
+
+  try {
+    const res = await fetch(`https://pypi.org/pypi/${pkgName}/${pkgVersion}/json`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return null;
+
+    const data = await res.json();
+    const urls = data.urls || [];
+
+    const hasMatchingWheel = urls.some(
+      (u) => u.packagetype === 'bdist_wheel' && u.filename.includes(`-${cpTag}-`)
+    );
+    return hasMatchingWheel;
+  } catch {
+    return null; // network error, timeout, bad JSON, etc. — treat as unknown
+  }
+}
+
+async function run(projectRoot, options = {}) {
+  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.name));
+
+  if (flagged.length === 0) {
+    return {
+      status: 'pass',
+      message: `${name} — Python ${version.major}.${version.minor} with no known Rust-compiled deps`,
+    };
+  }
+
+  // ── Static mode (default): warn based on the known-package list alone ──
+  if (!options.live) {
+    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 re-run with --live to verify wheel availability for ${version.major}.${version.minor}`,
+      details: flagged.map((pkg) => ({
+        file: 'requirements.txt',
+        message: `"${pkg.name}" has Rust-compiled components — prebuilt wheels may not exist for Python ${version.major}.${version.minor}`,
+      })),
+    };
+  }
+
+  // ── Live mode: actually query PyPI to confirm wheel availability ──
+  const liveResults = await Promise.all(
+    flagged.map(async (pkg) => {
+      const available = await checkWheelAvailability(pkg.name, pkg.version, version.major, version.minor);
+      return { ...pkg, available };
+    })
+  );
+
+  const confirmedMissing = liveResults.filter((r) => r.available === false);
+  const unknown = liveResults.filter((r) => r.available === null);
+  const confirmedOk = liveResults.filter((r) => r.available === true);
+
+  if (confirmedMissing.length === 0 && unknown.length === 0) {
+    return {
+      status: 'pass',
+      message: `${name} — verified wheels exist on PyPI for Python ${version.major}.${version.minor}`,
+      details: confirmedOk.map((pkg) => ({
+        file: 'requirements.txt',
+        message: `"${pkg.name}${pkg.version ? `==${pkg.version}` : ''}" has a confirmed cp${version.major}${version.minor} wheel`,
+      })),
+    };
+  }
+
+  const details = [];
+  for (const pkg of confirmedMissing) {
+    details.push({
+      file: 'requirements.txt',
+      message: `"${pkg.name}${pkg.version ? `==${pkg.version}` : ''}" — confirmed: no wheel for Python ${version.major}.${version.minor}`,
+    });
+  }
+  for (const pkg of unknown) {
+    details.push({
+      file: 'requirements.txt',
+      message: `"${pkg.name}" — could not verify (unpinned version or PyPI lookup failed); treat as at-risk`,
+    });
+  }
+
+  return {
+    status: confirmedMissing.length > 0 ? 'fail' : 'warn',
+    message: `${name} — wheel availability ${confirmedMissing.length > 0 ? 'confirmed missing' : 'unverified'} for Python ${version.major}.${version.minor}`,
+    fix: `Pin to Python 3.12 in runtime.txt ("python-3.12.7"), or upgrade the affected package(s) to a version with a cp${version.major}${version.minor} wheel`,
+    details,
+  };
+}
+
+module.exports = { name, run };