errlens 1.0.5 → 1.0.7

package/README.md

@@ -84,6 +84,53 @@ Get machine-readable results for your own tooling or automated reports:
 errlens "is not a function" --json
 ```
 
+Run a script and write the JSON report directly to a file in CI:
+
+```bash
+errlens run test.js --json > ci-report.json
+```
+
+In `--json` mode, ErrLens prints only JSON (no spinner, colors, or terminal boxes).
+
+Example response from `run`:
+
+```json
+{
+  "code": 0,
+  "count": 0,
+  "matches": []
+}
+```
+
+Example response from `analyze <errorString>` (match found):
+
+```json
+{
+  "code": 1,
+  "count": 1,
+  "matches": [
+    {
+      "name": "TypeError: Cannot read properties of undefined",
+      "match": "Cannot read properties of undefined",
+      "explanation": "You are trying to access a property on a variable that is currently empty.",
+      "why": "The variable wasn't initialized, or an API call hasn't finished yet.",
+      "fixes": [
+        "Use optional chaining: user?.name",
+        "Set a default value: data || []"
+      ],
+      "example": "const name = user?.name || 'Guest';"
+    }
+  ]
+}
+```
+
+Exit codes (useful for CI):
+
+- `run <file>` exits with the child process exit code.
+- `analyze <errorString>` exits with `1` when matches are found (intentional, so CI can fail when known errors are detected), otherwise `0`.
+
+This follows Unix conventions where `0` means success and non-zero means failure. If you prefer success-on-detection in CI, invert the check in your pipeline logic (for example, treat exit code `1` from `analyze <errorString>` as a pass condition).
+
 ---
 
 ## 🧠 System Architecture

package/bin/index.js

@@ -1,75 +1,127 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { Command } = require("commander");
 const { spawn } = require("child_process");
-const ora = require("ora");
+
 const chalk = require("chalk");
 const path = require("path");
 const { findError } = require("../lib/matcher");
 const { formatError } = require("../lib/formatter");
 
+const { version } = require("../package.json");
 const program = new Command();
 
 program
   .name("errlens")
   .description("Professional JS Error Analytics")
-  .version("1.3.1");
+  .version(version);
 
+// ----------------- RUN COMMAND -----------------
 program
   .command("run <file>")
+  .option('--json', 'Output JSON instead of pretty UI')
   .description("Run a Javascript file and analyze crashes")
-  .action((file) => {
+  .action(async (file, options) => {
+    const { default: ora } = await import("ora");
     const filePath = path.resolve(process.cwd(), file);
-    const spinner = ora(`Running ${chalk.yellow(file)}...`).start();
-    
-    // stdio: ['inherit', 'pipe', 'pipe'] 
-    // This allows us to pipe stdout and stderr while keeping the process interactive
+    const isJson = Boolean(options.json);
+    const spinner = isJson ? null : ora(`Running ${chalk.yellow(file)}...`).start();
+
     const child = spawn(process.execPath, [filePath], { stdio: ["inherit", "pipe", "pipe"] });
 
     let errorOutput = "";
 
-    // Stream logs to terminal in REAL-TIME
+    // Stream logs to terminal in real-time
     child.stdout.on("data", (data) => {
-      // Clear spinner temporarily to print log, then restart (better UX)
-      spinner.stop();
-      process.stdout.write(data);
-      spinner.start();
+      if (!isJson) {
+        spinner.stop();
+        process.stdout.write(data);
+        spinner.start();
+      }
     });
 
     // Capture stderr for analysis
     child.stderr.on("data", (data) => {
       errorOutput += data.toString();
+
+      if (!isJson) {
+        process.stderr.write(data);
+      }
     });
 
     child.on("close", (code, signal) => {
-      spinner.stop();
+      if (!isJson) {
+        spinner.stop();
+      }
+
+      const { count, matches } = findError(errorOutput);
 
       if (code === null) {
-        console.log(chalk.red.bold(`\n⚠️ Process killed by signal: ${signal}`));
+        if (isJson) {
+          const result = { code: 1, count, matches };
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(chalk.red.bold(`\n⚠️ Process killed by signal: ${signal}`));
+        }
         process.exit(1);
         return;
       }
 
-      if (code === 0) {
-        console.log(chalk.green.bold("\n✨ Process finished successfully."));
+      if (isJson) {
+        const result = { code, count, matches };
+        console.log(JSON.stringify(result, null, 2));
+      } else if (code === 0) {
+          console.log(chalk.green.bold("\n✨ Process finished successfully."));
       } else {
-        const { count, matches } = findError(errorOutput);
-
         if (count > 0) {
           console.log(chalk.bold.cyan(`\n🚀 ErrLens Analysis (${count} Issue(s)):`));
-          matches.forEach(m => console.log(formatError(m)));
+          matches.forEach(m => { console.log(formatError(m)); }); // Pretty UI only here
         } else {
           console.log(chalk.red.bold("\n❌ Crash detected (No known fix in database):"));
           console.log(chalk.gray(errorOutput));
         }
       }
+
       process.exit(code ?? 1);
     });
 
     child.on("error", (err) => {
-      spinner.fail(chalk.red(`System Error: ${err.message}`));
+      if (isJson) {
+        const result = { code: 1, count: 0, matches: [] };
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        spinner.fail(chalk.red(`System Error: ${err.message}`));
+      }
       process.exit(1);
     });
   });
 
+// ----------------- ANALYZE COMMAND -----------------
+program
+  .arguments("<errorString>") // default command if no "run"
+  .description("Analyze a specific error string")
+  .option('--json', 'Output result in JSON format')
+  .action((errorString, options) => {
+    const { count, matches } = findError(errorString);
+    const exitCode = count > 0 ? 1 : 0;
+    const isJson = Boolean(options.json);
+
+    if (isJson) {
+      console.log(JSON.stringify({ code: exitCode, count, matches }, null, 2));
+      process.exit(exitCode);
+      return;
+    }
+
+    if (count > 0) {
+      console.log(chalk.bold.cyan(`\n🚀 ErrLens Analysis (${count} Issue(s)):`));
+      matches.forEach(m => { console.log(formatError(m)); }); // Pretty UI
+    } else {
+      console.log(chalk.red.bold("\n❌ Crash detected (No known fix in database):"));
+      console.log(chalk.gray(errorString));
+    }
+
+    process.exit(exitCode);
+  });
+
+// ----------------- PARSE ARGUMENTS -----------------
 program.parse(process.argv);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "errlens",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Professional CLI tool that explains JavaScript and Node.js errors in plain English with actionable fixes directly in your terminal.",
   "main": "./bin/index.js",
   "bin": {
-    "errlens": "./bin/index.js"
+    "errlens": "bin/index.js"
   },
   "author": "BeyteFlow (https://github.com/BeyteFlow)",
   "license": "MIT",
@@ -36,7 +36,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/BeyteFlow/errlens.git"
+    "url": "git+https://github.com/BeyteFlow/errlens.git"
   },
   "bugs": {
     "url": "https://github.com/BeyteFlow/errlens/issues"