regula-wasi 3.2.4 → 3.2.5

package/README.md

@@ -89,6 +89,16 @@ if (result.summary.rule_results.FAIL > 0) {
   console.error('Security violations found!');
   process.exit(1);
 }
+
+// Error handling with detailed error information
+try {
+  const result = await runRegula('./main.tf');
+} catch (error) {
+  // RegulaError includes stdout, stderr, exitCode, and command
+  console.error('Error:', error.message);
+  console.error('Stderr:', error.stderr);
+  console.error('Exit code:', error.exitCode);
+}
 ```
 
 #### API Options
@@ -103,6 +113,16 @@ if (result.summary.rule_results.FAIL > 0) {
 | `noIgnore` | boolean | Disable .gitignore filtering |
 | `varFiles` | string[] | Terraform variable files (.tfvars) to use |
 
+#### Error Handling
+
+When an error occurs, a `RegulaError` is thrown with the following properties:
+
+- `message` - Error description
+- `stdout` - Standard output from regula command
+- `stderr` - Standard error output (includes OPA errors and warnings)
+- `exitCode` - Exit code from regula process
+- `command` - The command that was executed
+
 ### Prebuilt Binary
 
 Download from [Releases](https://github.com/nonfx/regula/releases) for your platform.

package/index.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Custom error class for Regula execution errors
+ */
+export class RegulaError extends Error {
+  /** Standard output from regula command */
+  stdout: string;
+  /** Standard error output from regula command */
+  stderr: string;
+  /** Exit code from regula process */
+  exitCode: number;
+  /** The command that was executed */
+  command: string;
+
+  constructor(
+    message: string,
+    details: {
+      stdout: string;
+      stderr: string;
+      exitCode: number;
+      command: string;
+    }
+  );
+}
+
 export interface RegulaOptions {
   /** Input type: auto, tf, tf-plan, cfn, k8s, arm */
   inputType?: "auto" | "tf" | "tf-plan" | "cfn" | "k8s" | "arm";
@@ -89,6 +113,7 @@ export function validate(
 declare const _default: {
   runRegula: typeof runRegula;
   validate: typeof validate;
+  RegulaError: typeof RegulaError;
 };
 
 export default _default;

package/index.js

@@ -5,6 +5,20 @@ import { dirname, join } from "path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+/**
+ * Custom error class for Regula execution errors
+ */
+export class RegulaError extends Error {
+  constructor(message, { stdout, stderr, exitCode, command }) {
+    super(message);
+    this.name = "RegulaError";
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.exitCode = exitCode;
+    this.command = command;
+  }
+}
+
 /**
  * Run regula on the specified path(s) and return parsed JSON results.
  * @param {string|string[]} paths - Path(s) to IaC files or directories
@@ -17,6 +31,7 @@ const __dirname = dirname(__filename);
  * @param {boolean} options.noIgnore - Disable .gitignore filtering
  * @param {string[]} options.varFiles - Terraform variable files to use
  * @returns {Promise<Object>} - Parsed regula output with rule_results and summary
+ * @throws {RegulaError} - Throws RegulaError with stdout, stderr, exitCode, and command properties
  */
 export async function runRegula(paths, options = {}) {
   const pathArray = Array.isArray(paths) ? paths : [paths];
@@ -68,21 +83,38 @@ export async function runRegula(paths, options = {}) {
 
   return new Promise((resolve, reject) => {
     const cliPath = join(__dirname, "cli.js");
+    const command = `node ${cliPath} ${args.join(" ")}`;
 
     execFile("node", [cliPath, ...args], { maxBuffer: 50 * 1024 * 1024 }, (error, stdout, stderr) => {
-      if (stderr) {
-        console.error(stderr);
+      const exitCode = error?.code || 0;
+
+      // If there was an execution error (not just a non-zero exit), reject with details
+      if (error && error.code !== 1) {
+        // Exit code 1 is expected for security violations, so we don't treat it as an error
+        reject(
+          new RegulaError(`Regula execution failed: ${error.message}`, {
+            stdout,
+            stderr,
+            exitCode,
+            command,
+          })
+        );
+        return;
       }
 
+      // Try to parse the output
       try {
         const result = JSON.parse(stdout);
         resolve(result);
       } catch (parseError) {
-        if (error) {
-          reject(new Error(`Regula failed: ${error.message}\nOutput: ${stdout}`));
-        } else {
-          reject(new Error(`Failed to parse regula output: ${stdout}`));
-        }
+        reject(
+          new RegulaError(`Failed to parse regula output: ${parseError.message}`, {
+            stdout,
+            stderr,
+            exitCode,
+            command,
+          })
+        );
       }
     });
   });
@@ -94,9 +126,10 @@ export async function runRegula(paths, options = {}) {
  * @param {string|string[]} paths - Path(s) to IaC files or directories
  * @param {Object} options - Optional configuration
  * @returns {Promise<Object>} - Object with rule_results and summary
+ * @throws {RegulaError} - Throws RegulaError with stdout, stderr, exitCode, and command properties
  */
 export async function validate(paths, options = {}) {
   return runRegula(paths, options);
 }
 
-export default { runRegula, validate };
+export default { runRegula, validate, RegulaError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regula-wasi",
-  "version": "3.2.4",
+  "version": "3.2.5",
   "description": "Infrastructure as Code security and compliance evaluation tool (WASI build). Fork of fugue/regula with security patches.",
   "type": "module",
   "main": "index.js",