regula-wasi 3.2.3 → 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

@@ -0,0 +1,119 @@
+/**
+ * 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";
+  /** Additional rego rule files/directories to include */
+  include?: string | string[];
+  /** Only run these specific rule IDs */
+  only?: string | string[];
+  /** Exclude these specific rule IDs */
+  exclude?: string | string[];
+  /** Disable built-in rules (use only custom rules from include) */
+  noBuiltIns?: boolean;
+  /** Disable .gitignore filtering */
+  noIgnore?: boolean;
+  /** Terraform variable files (.tfvars) to use */
+  varFiles?: string | string[];
+}
+
+export interface SourceLocation {
+  path: string;
+  line: number;
+  column: number;
+}
+
+export interface RuleResult {
+  controls: string[];
+  families: string[];
+  filepath: string;
+  input_type: string;
+  provider: string;
+  resource_id: string;
+  resource_type: string;
+  resource_tags: Record<string, unknown>;
+  rule_description: string;
+  rule_id: string;
+  rule_message: string;
+  rule_name: string;
+  rule_raw_result: boolean;
+  rule_remediation_doc?: string;
+  rule_result: "PASS" | "FAIL" | "WAIVED";
+  rule_severity: "Unknown" | "Informational" | "Low" | "Medium" | "High" | "Critical";
+  rule_summary: string;
+  source_location?: SourceLocation[];
+  active_waivers?: string[];
+}
+
+export interface RegulaResult {
+  rule_results: RuleResult[];
+  summary: {
+    filepaths: string[];
+    rule_results: {
+      PASS: number;
+      FAIL: number;
+      WAIVED: number;
+    };
+    severities: {
+      Unknown: number;
+      Informational: number;
+      Low: number;
+      Medium: number;
+      High: number;
+      Critical: number;
+    };
+  };
+}
+
+/**
+ * Run regula on the specified path(s) and return parsed JSON results.
+ * @param paths - Path(s) to IaC files or directories
+ * @param options - Optional configuration
+ * @returns Parsed regula output with rule_results and summary
+ */
+export function runRegula(
+  paths: string | string[],
+  options?: RegulaOptions
+): Promise<RegulaResult>;
+
+/**
+ * Validate IaC files and return rule results.
+ * Alias for runRegula().
+ * @param paths - Path(s) to IaC files or directories
+ * @param options - Optional configuration
+ * @returns Object with rule_results and summary
+ */
+export function validate(
+  paths: string | string[],
+  options?: RegulaOptions
+): Promise<RegulaResult>;
+
+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,9 +1,10 @@
 {
   "name": "regula-wasi",
-  "version": "3.2.3",
+  "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",
+  "types": "index.d.ts",
   "bin": {
     "regula": "cli.js"
   },
@@ -15,6 +16,7 @@
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "cli.js",
     "regula.wasm",
     "README.md",