predeploy-check 1.1.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # predeploy-check
 
-> Catch deployment failures **before** you push. Scans your project for known Render & Vercel pitfalls.
+> Stop deployment failures before they happen. `predeploy-check` scans your project for the most common deployment mistakes across Vercel and Render, including missing environment variables, case-sensitive imports, Python wheel compatibility, start command issues, and more — before you push your code.
 
 ```bash
 npx predeploy-check
@@ -21,12 +21,19 @@ No install required — just run it in your project directory.
 
 ## Output
 
-Clean, colored terminal output with:
+Two output modes, same underlying checks:
+
+**Terminal (default)** — clean, colored output with:
 - ✅ / ⚠️ / ❌ per check
 - File and line context
 - One-line suggested fix
 
-Exit code `1` if any ❌ failures, `0` otherwise.
+**JSON** (`--json`) — a single structured JSON object on stdout, with no
+colors or decoration, designed for CI dashboards, GitHub bots, editor
+extensions, or any tool that needs to parse the results programmatically
+rather than read them. See [JSON output](#json-output) below for the shape.
+
+Exit code `1` if any ❌ failures, `0` otherwise — in both output modes.
 
 ## Usage
 
@@ -41,6 +48,12 @@ npx predeploy-check ./my-project
 # relying on the built-in known-package list (slower, needs internet)
 npx predeploy-check --live
 
+# Output machine-readable JSON instead of colored terminal text
+npx predeploy-check --json
+
+# Combine flags freely
+npx predeploy-check --live --json ./my-project
+
 # Show help
 npx predeploy-check --help
 ```
@@ -52,6 +65,41 @@ 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.
 
+## JSON output
+
+`--json` prints a single JSON object to stdout, with nothing else mixed
+in — safe to pipe directly into `JSON.parse()`, `jq`, or any tool that
+expects clean machine-readable output:
+
+```bash
+npx predeploy-check --json | jq '.summary'
+```
+
+Shape:
+
+```json
+{
+  "tool": "predeploy-check",
+  "version": "1.2.0",
+  "projectRoot": "/path/to/project",
+  "live": false,
+  "summary": { "passed": 4, "warnings": 1, "failed": 1, "skipped": 0 },
+  "willLikelyFail": true,
+  "checks": [
+    {
+      "check": "Render Start Command: missing start configuration",
+      "status": "fail",
+      "message": "...",
+      "fix": "Add a \"start\" script to package.json...",
+      "details": [ { "file": "package.json", "message": "..." } ]
+    }
+  ]
+}
+```
+
+`--help --json` and `--version --json` also return structured JSON
+instead of plain text, for tools that want to introspect the CLI itself.
+
 ## Adding custom checks
 
 Create a new file in the `checks/` folder:

package/bin/cli.js

@@ -6,8 +6,31 @@ const path = require('path');
 const { runAllChecks } = require('../index');
 
 const args = process.argv.slice(2);
+const wantsJson = args.includes('--json');
 
 if (args.includes('--help') || args.includes('-h')) {
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      tool: 'predeploy-check',
+      usage: 'npx predeploy-check [directory] [options]',
+      options: {
+        '-h, --help': 'Show this help message',
+        '-v, --version': 'Show version number',
+        '--live': 'Verify Python wheel availability against PyPI (slower, needs internet)',
+        '--json': 'Output machine-readable JSON instead of colored terminal output',
+      },
+      checks: [
+        { id: 1, name: 'Python + Render', description: 'Rust-compiled deps on unsupported Python versions' },
+        { id: 2, name: 'ESLint + Vercel', description: 'Peer-dependency mismatches in Next.js projects' },
+        { id: 3, name: 'Case Sensitivity', description: 'Import paths that differ from actual filenames' },
+        { id: 4, name: 'Missing Engines', description: 'No "engines" field in package.json' },
+        { id: 5, name: 'Env Var Check', description: 'process.env references missing from .env files' },
+        { id: 6, name: 'Render Start Cmd', description: 'Missing start command for Render deployments' },
+      ],
+    }, null, 2));
+    process.exit(0);
+  }
+
   console.log(`
   predeploy-check — catch deployment failures before they happen
 
@@ -21,6 +44,7 @@ if (args.includes('--help') || args.includes('-h')) {
     -h, --help      Show this help message
     -v, --version   Show version number
     --live          Verify Python wheel availability against PyPI (slower, needs internet)
+    --json          Output machine-readable JSON instead of colored terminal output
 
   Checks:
     1. Python + Render:    Rust-compiled deps on unsupported Python versions
@@ -35,12 +59,16 @@ if (args.includes('--help') || args.includes('-h')) {
 
 if (args.includes('--version') || args.includes('-v')) {
   const pkg = require('../package.json');
-  console.log(pkg.version);
+  if (wantsJson) {
+    console.log(JSON.stringify({ tool: 'predeploy-check', version: pkg.version }, null, 2));
+  } else {
+    console.log(pkg.version);
+  }
   process.exit(0);
 }
 
 const projectRoot = path.resolve(args.find((a) => !a.startsWith('-')) || process.cwd());
-const options = { live: args.includes('--live') };
+const options = { live: args.includes('--live'), json: wantsJson };
 
 runAllChecks(projectRoot, options).then((exitCode) => {
   process.exit(exitCode);

package/index.js

@@ -60,10 +60,53 @@ function formatResult(result) {
 }
 
 /**
- * Run all checks against the given project root.
- * Returns exit code: 1 if any ❌, 0 otherwise.
+ * Run all checks against the given project root and collect their raw
+ * results, without printing anything. This is the single source of truth
+ * that both the terminal formatter and the JSON formatter consume, so the
+ * two output modes can never drift out of sync with each other.
  */
-async function runAllChecks(projectRoot, options = {}) {
+async function collectResults(projectRoot, options = {}) {
+  const allResults = [];
+
+  for (const check of checks) {
+    try {
+      const results = await check.run(projectRoot, options);
+      const resultArray = Array.isArray(results) ? results : [results];
+
+      for (const result of resultArray) {
+        allResults.push({ checkName: check.name, ...result });
+      }
+    } catch (err) {
+      allResults.push({
+        checkName: check.name,
+        status: 'error',
+        message: `${check.name}: internal error — ${err.message}`,
+      });
+    }
+  }
+
+  return allResults;
+}
+
+/**
+ * Compute summary counts and the overall exit code from a results array.
+ * Both output modes (terminal and JSON) use this so the numbers always
+ * match regardless of how they're displayed.
+ */
+function summarize(allResults) {
+  const counts = { pass: 0, warn: 0, fail: 0, skip: 0, error: 0 };
+  for (const result of allResults) {
+    counts[result.status] = (counts[result.status] || 0) + 1;
+  }
+  const hasFail = counts.fail > 0 || counts.error > 0;
+  return { counts, hasFail, exitCode: hasFail ? 1 : 0 };
+}
+
+/**
+ * Print results to the terminal with colors, icons, and a summary —
+ * the original human-readable output format.
+ */
+function printTerminalOutput(projectRoot, options, allResults, summary) {
   console.log('');
   console.log(chalk.bold.underline(`  predeploy-check`) + chalk.dim(`  scanning ${projectRoot}`));
   if (options.live) {
@@ -76,62 +119,81 @@ async function runAllChecks(projectRoot, options = {}) {
   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, options);
-
-      // 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++;
+  for (const result of allResults) {
+    if (result.status === 'error') {
+      console.log(chalk.red(`❌ ${result.message}`));
+    } else {
+      console.log(formatResult(result));
     }
+    console.log('');
   }
 
-  // Summary bar
   console.log(chalk.dim('  ─'.repeat(30)));
 
+  const { counts, hasFail } = summary;
   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`));
+  if (counts.pass > 0) parts.push(chalk.green(`${counts.pass} passed`));
+  if (counts.warn > 0) parts.push(chalk.yellow(`${counts.warn} warnings`));
+  if (counts.fail + counts.error > 0) parts.push(chalk.red(`${counts.fail + counts.error} failed`));
+  if (counts.skip > 0) parts.push(chalk.gray(`${counts.skip} 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) {
+  } else if (counts.warn > 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'));
   }
+}
+
+/**
+ * Print results as a single machine-readable JSON object to stdout.
+ * No colors, no decoration — designed for CI dashboards, GitHub bots,
+ * editor extensions, or anything else that needs to parse the output
+ * programmatically rather than read it.
+ */
+function printJsonOutput(projectRoot, options, allResults, summary) {
+  const output = {
+    tool: 'predeploy-check',
+    version: require('./package.json').version,
+    projectRoot,
+    live: Boolean(options.live),
+    summary: {
+      passed: summary.counts.pass,
+      warnings: summary.counts.warn,
+      failed: summary.counts.fail + summary.counts.error,
+      skipped: summary.counts.skip,
+    },
+    willLikelyFail: summary.hasFail,
+    checks: allResults.map((r) => ({
+      check: r.checkName,
+      status: r.status,
+      message: r.message,
+      fix: r.fix || null,
+      details: r.details || [],
+    })),
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * Run all checks against the given project root.
+ * Returns exit code: 1 if any ❌, 0 otherwise.
+ */
+async function runAllChecks(projectRoot, options = {}) {
+  const allResults = await collectResults(projectRoot, options);
+  const summary = summarize(allResults);
+
+  if (options.json) {
+    printJsonOutput(projectRoot, options, allResults, summary);
+  } else {
+    printTerminalOutput(projectRoot, options, allResults, summary);
+  }
 
-  return hasFail ? 1 : 0;
+  return summary.exitCode;
 }
 
-module.exports = { runAllChecks };
+module.exports = { runAllChecks, collectResults, summarize };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "predeploy-check",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Scan a project folder and flag known deployment-failure patterns for Render and Vercel before you push.",
   "main": "index.js",
   "bin": {
@@ -31,7 +31,8 @@
     "url": "https://github.com/Alok-Fusion/predeploy_check/issues"
   },
   "dependencies": {
-    "chalk": "^4.1.2"
+    "chalk": "^4.1.2",
+    "predeploy-check": "^1.1.1"
   },
   "engines": {
     "node": ">=14.0.0"