@nolans01/agent-validator 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import chalk2 from "chalk";
-import fs5 from "fs";
-import path6 from "path";
+import fs10 from "fs";
+import path11 from "path";
 
 // src/resolver.ts
 import path2 from "path";
@@ -105,11 +105,20 @@ async function resolveFileList(options) {
   }
   return resolved;
 }
+var DEFAULT_EXCLUDE = [
+  "**/node_modules/**",
+  "**/vendor/**",
+  "**/venv/**",
+  "**/.venv/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/coverage/**",
+  "**/.git/**"
+];
 async function resolveDirectory(options) {
   const dirs = options.targets ?? ["."];
   const patterns = dirs.map((d) => `${d}/**/*`);
-  const defaultExclude = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
-  const ignore = [...defaultExclude, ...options.exclude ?? []];
+  const ignore = [...DEFAULT_EXCLUDE, ...options.exclude ?? []];
   return glob(patterns, {
     cwd: options.workdir,
     nodir: true,
@@ -265,6 +274,101 @@ function buildMypyWhy(severity, code) {
   return parts.join(" ");
 }
 
+// src/adapters/ruby-syntax.ts
+import { execa as execa5 } from "execa";
+
+// src/utils.ts
+function chunk(arr, size) {
+  if (size <= 0) return [arr];
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+
+// src/adapters/ruby-syntax.ts
+var RUBY_SYNTAX_LINE = /^(.*?):(\d+):.*(?:syntax error|unterminated|unexpected)/i;
+var RubySyntaxAdapter = class {
+  name = "ruby";
+  supportedLanguages = ["ruby"];
+  async isAvailable() {
+    return isBinaryAvailable("ruby");
+  }
+  async run(files, config) {
+    const findings = [];
+    for (const batch of chunk(files, 8)) {
+      const results = await Promise.all(batch.map(async (file) => ({
+        file,
+        result: await execa5("ruby", ["-c", file], {
+          cwd: config.workdir,
+          reject: false
+        })
+      })));
+      for (const { file, result } of results) {
+        if (result.exitCode === 0) continue;
+        findings.push(buildSyntaxFinding(file, `${result.stderr}
+${result.stdout}`));
+      }
+    }
+    return { findings };
+  }
+};
+function buildSyntaxFinding(file, output) {
+  const relevantLine = output.split("\n").find((line) => RUBY_SYNTAX_LINE.test(line));
+  const match = relevantLine ? RUBY_SYNTAX_LINE.exec(relevantLine) : null;
+  return {
+    file: match?.[1] || file,
+    line: match ? Number.parseInt(match[2], 10) : 0,
+    severity: "blocker",
+    metric: "ruby_syntax",
+    message: relevantLine?.trim() || `Ruby could not parse ${file}`,
+    why: "Ruby files must parse successfully before Rails can load the application.",
+    suggestion: "Fix the reported Ruby syntax error.",
+    metadata: { source: "ruby" }
+  };
+}
+
+// src/adapters/zeitwerk.ts
+import fs3 from "fs";
+import path4 from "path";
+import { execa as execa6 } from "execa";
+var ZeitwerkAdapter = class {
+  name = "zeitwerk";
+  supportedLanguages = ["ruby"];
+  isRailsProject(workdir) {
+    return fs3.existsSync(path4.join(workdir, "Gemfile")) && fs3.existsSync(path4.join(workdir, "config", "application.rb"));
+  }
+  async isAvailable() {
+    return isBinaryAvailable("bundle");
+  }
+  async run(_files, config) {
+    const result = await execa6("bundle", ["exec", "rails", "zeitwerk:check"], {
+      cwd: config.workdir,
+      env: { RAILS_ENV: "test" },
+      reject: false
+    });
+    if (result.exitCode === 0) return { findings: [] };
+    const detail = lastOutputLine(`${result.stderr}
+${result.stdout}`);
+    return {
+      findings: [{
+        file: "config/application.rb",
+        line: 0,
+        severity: "blocker",
+        metric: "rails_zeitwerk",
+        message: detail ? `Rails Zeitwerk check failed: ${detail}` : "Rails Zeitwerk check failed",
+        why: "Rails must boot and autoload application constants consistently.",
+        suggestion: "Run RAILS_ENV=test bundle exec rails zeitwerk:check in the project environment.",
+        metadata: { source: "zeitwerk", exitCode: result.exitCode }
+      }]
+    };
+  }
+};
+function lastOutputLine(output) {
+  return output.split("\n").map((line) => line.trim()).filter(Boolean).at(-1)?.slice(0, 500);
+}
+
 // src/scorer.ts
 function calculateComplexityScore(input) {
   if (input.totalFunctions === 0) return 100;
@@ -335,7 +439,7 @@ function calculateTestQualityScore(input) {
 }
 function overallStatus(results) {
   if (results.some((r) => r.status === "fail")) return "fail";
-  if (results.some((r) => r.status === "warn")) return "warn";
+  if (results.some((r) => r.status === "warn" || r.status === "skip")) return "warn";
   return "pass";
 }
 
@@ -348,11 +452,14 @@ var DEFAULT_COMPLEXITY = {
 };
 var DEFAULT_SECURITY = {
   semgrepRules: ["p/security-audit", "p/secrets"],
-  gitleaksEnabled: true
+  gitleaksEnabled: true,
+  brakemanEnabled: true
 };
 var DEFAULT_TYPE_SAFETY = {
   strict: false,
-  mypyEnabled: true
+  mypyEnabled: true,
+  rubySyntaxEnabled: true,
+  railsZeitwerkEnabled: true
 };
 var DEFAULT_JSCPD_EXCLUDE = [
   "**/test/**",
@@ -408,6 +515,8 @@ var TypeSafetyGate = class {
   name = "type_safety";
   tsc = new TscAdapter();
   mypy = new MypyAdapter();
+  ruby = new RubySyntaxAdapter();
+  zeitwerk = new ZeitwerkAdapter();
   async run(ctx) {
     const start = Date.now();
     const config = ctx.config.typeSafety ?? DEFAULT_TYPE_SAFETY;
@@ -417,6 +526,9 @@ var TypeSafetyGate = class {
     if (ctx.language === "python" && config.mypyEnabled) {
       return this.runMypy(ctx, config, start);
     }
+    if (ctx.language === "ruby" && config.rubySyntaxEnabled !== false) {
+      return this.runRuby(ctx, config, start);
+    }
     const suggestion = ctx.language === "python" ? "Enable mypyEnabled in profile or install mypy: pip install mypy" : "No type checker supported for this language yet.";
     return toolMissingResult(this.name, start, `No type checker available for language: ${ctx.language}`, suggestion);
   }
@@ -457,6 +569,44 @@ var TypeSafetyGate = class {
     const result = await this.mypy.run(files, adapterConfig);
     return this.buildResult(result.findings, start);
   }
+  async runRuby(ctx, config, start) {
+    if (!await this.ruby.isAvailable()) {
+      return toolMissingResult(
+        this.name,
+        start,
+        "Ruby is not installed in the validation environment",
+        "Run the validator from the project Ruby/Docker environment."
+      );
+    }
+    const files = this.getFiles(ctx, this.ruby);
+    if (files.length === 0) return this.emptyResult(start);
+    const adapterConfig = { workdir: ctx.workdir, thresholds: {} };
+    const syntaxResult = await this.ruby.run(files, adapterConfig);
+    const findings = [...syntaxResult.findings];
+    if (findings.length > 0) return this.buildResult(findings, start);
+    if (config.railsZeitwerkEnabled !== false && this.zeitwerk.isRailsProject(ctx.workdir)) {
+      if (await this.zeitwerk.isAvailable()) {
+        const zeitwerkResult = await this.zeitwerk.run(files, adapterConfig);
+        findings.push(...zeitwerkResult.findings);
+      } else {
+        findings.push({
+          file: "Gemfile",
+          line: 0,
+          severity: "warning",
+          metric: "rails_check_skipped",
+          message: "Rails Zeitwerk check was skipped because Bundler is unavailable",
+          why: "Ruby syntax alone does not verify that Rails can boot and autoload constants.",
+          suggestion: "Run the validator inside the project Docker image with Bundler available.",
+          metadata: { source: "zeitwerk" }
+        });
+      }
+    }
+    const result = this.buildResult(findings, start);
+    if (findings.some((finding) => finding.metric === "rails_check_skipped") && result.status === "pass") {
+      result.status = "warn";
+    }
+    return result;
+  }
   buildResult(findings, start) {
     const score = calculateTypeSafetyScore({ findings });
     const status = deriveStatus(score, findings);
@@ -465,19 +615,7 @@ var TypeSafetyGate = class {
 };
 
 // src/adapters/lizard.ts
-import { execa as execa5 } from "execa";
-
-// src/utils.ts
-function chunk(arr, size) {
-  if (size <= 0) return [arr];
-  const chunks = [];
-  for (let i = 0; i < arr.length; i += size) {
-    chunks.push(arr.slice(i, i + size));
-  }
-  return chunks;
-}
-
-// src/adapters/lizard.ts
+import { execa as execa7 } from "execa";
 var LizardAdapter = class {
   name = "lizard";
   supportedLanguages = [
@@ -498,7 +636,7 @@ var LizardAdapter = class {
     const allFindings = [];
     let totalFunctions = 0;
     for (const batch of chunk(files, 50)) {
-      const result = await execa5("lizard", [...batch, "--csv"], {
+      const result = await execa7("lizard", [...batch, "--csv"], {
         cwd: config.workdir,
         reject: false
       });
@@ -658,7 +796,7 @@ var ComplexityGate = class {
 };
 
 // src/adapters/semgrep.ts
-import { execa as execa6 } from "execa";
+import { execa as execa8 } from "execa";
 var SemgrepAdapter = class {
   name = "semgrep";
   supportedLanguages = [
@@ -680,15 +818,17 @@ var SemgrepAdapter = class {
     const allFindings = [];
     for (const batch of chunk(files, 50)) {
       const configArgs = rules.flatMap((r) => ["--config", r]);
-      const result = await execa6(
+      const result = await execa8(
         "semgrep",
         [...configArgs, "--json", ...batch],
         { cwd: config.workdir, reject: false }
       );
-      if (result.stdout) {
-        const parsed = parseSemgrepJson(result.stdout);
-        allFindings.push(...parsed);
+      const parsed = parseSemgrepJson(result.stdout || "");
+      if (!parsed || ![0, 1].includes(result.exitCode ?? -1) || parsed.errors.length > 0) {
+        allFindings.push(toolErrorFinding(result.exitCode));
+        continue;
       }
+      allFindings.push(...parsed.findings);
     }
     return { findings: allFindings };
   }
@@ -698,12 +838,12 @@ function parseSemgrepJson(json) {
   try {
     output = JSON.parse(json);
   } catch {
-    return [];
+    return null;
   }
   if (!output.results || !Array.isArray(output.results)) {
-    return [];
+    return null;
   }
-  return output.results.map((r) => ({
+  const findings = output.results.map((r) => ({
     file: r.path,
     line: r.start.line,
     end_line: r.end.line,
@@ -720,6 +860,19 @@ function parseSemgrepJson(json) {
       source: "semgrep"
     }
   }));
+  return { findings, errors: Array.isArray(output.errors) ? output.errors : [] };
+}
+function toolErrorFinding(exitCode) {
+  return {
+    file: "",
+    line: 0,
+    severity: "blocker",
+    metric: "security_tool_error",
+    message: "Semgrep failed or produced an invalid report",
+    why: "A failed security scan cannot be interpreted as having no vulnerabilities.",
+    suggestion: "Run Semgrep directly and verify network access, rules, and JSON output.",
+    metadata: { source: "semgrep", exitCode }
+  };
 }
 function mapSeverity(severity) {
   switch (severity) {
@@ -748,7 +901,10 @@ function buildWhy2(result) {
 }
 
 // src/adapters/gitleaks.ts
-import { execa as execa7 } from "execa";
+import { execa as execa9 } from "execa";
+import fs4 from "fs";
+import os from "os";
+import path5 from "path";
 var GitleaksAdapter = class {
   name = "gitleaks";
   supportedLanguages = [
@@ -763,19 +919,32 @@ var GitleaksAdapter = class {
   async isAvailable() {
     return isBinaryAvailable("gitleaks");
   }
-  async run(files, config) {
-    const result = await execa7(
-      "gitleaks",
-      ["detect", "--source", config.workdir, "--no-git", "-f", "json", "--report-path", "/dev/stdout"],
-      { cwd: config.workdir, reject: false }
-    );
-    if (!result.stdout || result.stdout.trim() === "") {
-      return { findings: [] };
+  async run(_files, config) {
+    const reportDirectory = fs4.mkdtempSync(path5.join(os.tmpdir(), "validator-gitleaks-"));
+    const reportPath = path5.join(reportDirectory, "report.json");
+    try {
+      const result = await execa9(
+        "gitleaks",
+        ["detect", "--source", config.workdir, "--no-git", "-f", "json", "--report-path", reportPath],
+        { cwd: config.workdir, reject: false }
+      );
+      const output = fs4.existsSync(reportPath) ? fs4.readFileSync(reportPath, "utf8") : result.stdout;
+      if ((!output || output.trim() === "") && result.exitCode === 0) {
+        return { findings: [] };
+      }
+      const allLeaks = parseGitleaksJson(output);
+      if (!allLeaks || ![0, 1].includes(result.exitCode ?? -1)) {
+        return { findings: [toolErrorFinding2(result.exitCode)] };
+      }
+      return {
+        findings: allLeaks.map((finding) => ({
+          ...finding,
+          file: path5.isAbsolute(finding.file) ? path5.relative(config.workdir, finding.file) : finding.file
+        }))
+      };
+    } finally {
+      fs4.rmSync(reportDirectory, { recursive: true, force: true });
     }
-    const allLeaks = parseGitleaksJson(result.stdout);
-    const fileSet = new Set(files);
-    const filtered = allLeaks.filter((f) => fileSet.has(f.file));
-    return { findings: filtered };
   }
 };
 function parseGitleaksJson(json) {
@@ -783,10 +952,10 @@ function parseGitleaksJson(json) {
   try {
     leaks = JSON.parse(json);
   } catch {
-    return [];
+    return null;
   }
   if (!Array.isArray(leaks)) {
-    return [];
+    return null;
   }
   return leaks.map((leak) => ({
     file: leak.File,
@@ -805,21 +974,112 @@ function parseGitleaksJson(json) {
     }
   }));
 }
+function toolErrorFinding2(exitCode) {
+  return {
+    file: "",
+    line: 0,
+    severity: "blocker",
+    metric: "security_tool_error",
+    message: "Gitleaks failed or produced an invalid report",
+    why: "A failed secret scan cannot be interpreted as having no exposed credentials.",
+    suggestion: "Run Gitleaks directly and verify its configuration and JSON output.",
+    metadata: { source: "gitleaks", exitCode }
+  };
+}
+
+// src/adapters/brakeman.ts
+import fs5 from "fs";
+import path6 from "path";
+import { execa as execa10 } from "execa";
+var BrakemanAdapter = class {
+  name = "brakeman";
+  supportedLanguages = ["ruby"];
+  isRailsProject(workdir) {
+    return fs5.existsSync(path6.join(workdir, "Gemfile")) && fs5.existsSync(path6.join(workdir, "config", "application.rb"));
+  }
+  async isAvailable() {
+    return isBinaryAvailable("brakeman");
+  }
+  async run(_files, config) {
+    const result = await execa10(
+      "brakeman",
+      ["--format", "json", "--quiet", "--no-exit-on-warn"],
+      { cwd: config.workdir, reject: false }
+    );
+    const report = parseReport(result.stdout || "");
+    if (!report || result.exitCode !== 0 || report.errors?.length) {
+      return { findings: [toolErrorFinding3(result.exitCode)] };
+    }
+    return { findings: report.warnings.map(toFinding) };
+  }
+};
+function parseReport(output) {
+  try {
+    const report = JSON.parse(output);
+    return Array.isArray(report.warnings) ? report : null;
+  } catch {
+    return null;
+  }
+}
+function toFinding(warning) {
+  return {
+    file: warning.file,
+    line: warning.line ?? 0,
+    severity: warning.confidence === "High" ? "blocker" : warning.confidence === "Medium" ? "warning" : "info",
+    metric: "rails_security",
+    message: warning.message,
+    why: `${warning.warning_type} detected by Brakeman's ${warning.check_name} check.`,
+    suggestion: "Review the affected Rails code and apply the mitigation recommended by Brakeman.",
+    metadata: {
+      source: "brakeman",
+      warningCode: warning.warning_code,
+      fingerprint: warning.fingerprint,
+      confidence: warning.confidence
+    }
+  };
+}
+function toolErrorFinding3(exitCode) {
+  return {
+    file: "",
+    line: 0,
+    severity: "blocker",
+    metric: "security_tool_error",
+    message: "Brakeman failed or produced an invalid report",
+    why: "A failed Rails security scan cannot be interpreted as having no vulnerabilities.",
+    suggestion: "Run brakeman --format json --no-exit-on-warn directly and fix the reported execution error.",
+    metadata: { source: "brakeman", exitCode }
+  };
+}
 
 // src/gates/security.ts
 var SecurityGate = class {
   name = "security";
   semgrep = new SemgrepAdapter();
   gitleaks = new GitleaksAdapter();
+  brakeman = new BrakemanAdapter();
   async run(ctx) {
     const start = Date.now();
     const securityConfig = ctx.config.security ?? DEFAULT_SECURITY;
     const semgrepAvailable = await this.semgrep.isAvailable();
     const gitleaksAvailable = securityConfig.gitleaksEnabled ? await this.gitleaks.isAvailable() : false;
-    if (!semgrepAvailable && !gitleaksAvailable) {
-      return toolMissingResult(this.name, start, "Neither semgrep nor gitleaks is installed", "Install with: pip install semgrep OR brew install gitleaks");
+    const brakemanApplicable = ctx.language === "ruby" && securityConfig.brakemanEnabled !== false && this.brakeman.isRailsProject(ctx.workdir);
+    const brakemanAvailable = brakemanApplicable ? await this.brakeman.isAvailable() : false;
+    if (!semgrepAvailable && !gitleaksAvailable && !brakemanAvailable) {
+      return toolMissingResult(this.name, start, "No security tools are installed", "Install Semgrep, Gitleaks, or Brakeman.");
     }
     const allFindings = [];
+    if (brakemanApplicable && !brakemanAvailable) {
+      allFindings.push({
+        file: "Gemfile",
+        line: 0,
+        severity: "info",
+        metric: "rails_security_skipped",
+        message: "Brakeman is not installed; Rails-specific security checks were skipped",
+        why: "Generic security rules do not cover all Rails-specific vulnerability patterns.",
+        suggestion: "Install Brakeman or use the Rails validator image.",
+        metadata: { source: "brakeman" }
+      });
+    }
     if (semgrepAvailable) {
       const supportedFiles = ctx.files.filter((f) => this.semgrep.supportedLanguages.includes(f.language)).map((f) => f.relativePath);
       if (supportedFiles.length > 0) {
@@ -840,15 +1100,23 @@ var SecurityGate = class {
       });
       allFindings.push(...result.findings);
     }
+    if (brakemanAvailable) {
+      const result = await this.brakeman.run([], {
+        workdir: ctx.workdir,
+        thresholds: {}
+      });
+      allFindings.push(...result.findings);
+    }
     const score = calculateSecurityScore({ findings: allFindings });
-    const status = deriveStatus(score, allFindings);
+    const derivedStatus = deriveStatus(score, allFindings);
+    const status = allFindings.some((finding) => finding.metric === "rails_security_skipped") && derivedStatus === "pass" ? "warn" : derivedStatus;
     const duration_ms = Date.now() - start;
     return { gate: this.name, score, status, duration_ms, findings: allFindings };
   }
 };
 
 // src/adapters/madge.ts
-import { execa as execa8 } from "execa";
+import { execa as execa11 } from "execa";
 function parseCycles(stdout) {
   if (!stdout.trim()) return null;
   try {
@@ -880,7 +1148,7 @@ var MadgeAdapter = class {
   }
   async run(files, config) {
     if (files.length === 0) return { findings: [] };
-    const result = await execa8("madge", ["--circular", "--json", config.workdir], {
+    const result = await execa11("madge", ["--circular", "--json", config.workdir], {
       cwd: config.workdir,
       reject: false
     });
@@ -893,10 +1161,10 @@ var MadgeAdapter = class {
 };
 
 // src/adapters/jscpd.ts
-import { execa as execa9 } from "execa";
-import fs3 from "fs";
-import os from "os";
-import path4 from "path";
+import { execa as execa12 } from "execa";
+import fs6 from "fs";
+import os2 from "os";
+import path7 from "path";
 function buildArgs(config, tmpDir) {
   const minLines = config.minLines ?? 5;
   const minTokens = config.minTokens ?? 50;
@@ -918,9 +1186,9 @@ function buildArgs(config, tmpDir) {
   args.push(config.workdir);
   return args;
 }
-function parseReport(reportPath) {
-  if (!fs3.existsSync(reportPath)) return null;
-  const raw = fs3.readFileSync(reportPath, "utf-8");
+function parseReport2(reportPath) {
+  if (!fs6.existsSync(reportPath)) return null;
+  const raw = fs6.readFileSync(reportPath, "utf-8");
   try {
     const report = JSON.parse(raw);
     if (!report.duplicates || !Array.isArray(report.duplicates)) return null;
@@ -930,8 +1198,8 @@ function parseReport(reportPath) {
   }
 }
 function cloneToFinding(clone, workdir) {
-  const firstRel = path4.relative(workdir, clone.firstFile.name);
-  const secondRel = path4.relative(workdir, clone.secondFile.name);
+  const firstRel = path7.relative(workdir, clone.firstFile.name);
+  const secondRel = path7.relative(workdir, clone.secondFile.name);
   return {
     file: firstRel,
     line: clone.firstFile.startLoc.line,
@@ -959,28 +1227,28 @@ var JscpdAdapter = class {
   async run(files, config) {
     if (files.length === 0) return { findings: [] };
     const jscpdConfig = config;
-    const tmpDir = fs3.mkdtempSync(path4.join(os.tmpdir(), "jscpd-"));
+    const tmpDir = fs6.mkdtempSync(path7.join(os2.tmpdir(), "jscpd-"));
     try {
       const args = buildArgs(jscpdConfig, tmpDir);
-      await execa9("jscpd", args, { cwd: config.workdir, reject: false });
-      const report = parseReport(path4.join(tmpDir, "jscpd-report.json"));
+      await execa12("jscpd", args, { cwd: config.workdir, reject: false });
+      const report = parseReport2(path7.join(tmpDir, "jscpd-report.json"));
       if (!report) return { findings: [] };
       const fileSet = new Set(files);
       return {
         findings: report.duplicates.filter((clone) => {
-          const firstRel = path4.relative(config.workdir, clone.firstFile.name);
-          const secondRel = path4.relative(config.workdir, clone.secondFile.name);
+          const firstRel = path7.relative(config.workdir, clone.firstFile.name);
+          const secondRel = path7.relative(config.workdir, clone.secondFile.name);
           return fileSet.has(firstRel) || fileSet.has(secondRel);
         }).map((clone) => cloneToFinding(clone, config.workdir))
       };
     } finally {
-      fs3.rmSync(tmpDir, { recursive: true, force: true });
+      fs6.rmSync(tmpDir, { recursive: true, force: true });
     }
   }
 };
 
 // src/adapters/knip.ts
-import { execa as execa10 } from "execa";
+import { execa as execa13 } from "execa";
 function collectUnusedFiles(report, fileSet) {
   if (!report.files || !Array.isArray(report.files)) return [];
   return report.files.filter((file) => fileSet.has(file)).map((file) => ({
@@ -1036,7 +1304,7 @@ var KnipAdapter = class {
   }
   async run(files, config) {
     if (files.length === 0) return { findings: [] };
-    const result = await execa10("knip", ["--reporter", "json"], {
+    const result = await execa13("knip", ["--reporter", "json"], {
       cwd: config.workdir,
       reject: false
     });
@@ -1118,9 +1386,9 @@ var ArchitectureGate = class {
 };
 
 // src/adapters/stryker.ts
-import { execa as execa11 } from "execa";
-import fs4 from "fs";
-import path5 from "path";
+import { execa as execa14 } from "execa";
+import fs7 from "fs";
+import path8 from "path";
 
 // src/adapters/mutation-shared.ts
 function scoreSeverity(score) {
@@ -1136,7 +1404,7 @@ function timeoutResult(tool, timeout) {
     findings: [{
       file: "",
       line: 0,
-      severity: "info",
+      severity: "blocker",
       metric: "mutation_timeout",
       message: tool + " timed out after " + timeout + "ms",
       why: "Mutation testing exceeded the configured timeout.",
@@ -1234,16 +1502,16 @@ function survivorToFinding(file, mutant) {
 }
 function findReportPath(workdir) {
   const candidates = [
-    path5.join(workdir, "reports", "mutation", "mutation.json"),
-    path5.join(workdir, "reports", "mutation.json")
+    path8.join(workdir, "reports", "mutation", "mutation.json"),
+    path8.join(workdir, "reports", "mutation.json")
   ];
-  return candidates.find((p) => fs4.existsSync(p));
+  return candidates.find((p) => fs7.existsSync(p));
 }
 function readReport(workdir) {
   const reportPath = findReportPath(workdir);
   if (!reportPath) return null;
   try {
-    const raw = fs4.readFileSync(reportPath, "utf-8");
+    const raw = fs7.readFileSync(reportPath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -1274,8 +1542,8 @@ var StrykerAdapter = class {
   supportedLanguages = ["typescript", "javascript"];
   async isAvailable(workdir) {
     if (workdir) {
-      const localBin = path5.join(workdir, "node_modules", ".bin", "stryker");
-      if (fs4.existsSync(localBin)) return true;
+      const localBin = path8.join(workdir, "node_modules", ".bin", "stryker");
+      if (fs7.existsSync(localBin)) return true;
     }
     return await isBinaryAvailable("stryker");
   }
@@ -1291,10 +1559,10 @@ var StrykerAdapter = class {
   async executeStryker(files, config, timeout) {
     const mutatePattern = files.join(",");
     const args = ["run", "--reporters", "json", "--mutate", mutatePattern];
-    const useNpx = fs4.existsSync(path5.join(config.workdir, "node_modules", ".bin", "stryker"));
+    const useNpx = fs7.existsSync(path8.join(config.workdir, "node_modules", ".bin", "stryker"));
     const command = useNpx ? "npx" : "stryker";
     const execArgs = useNpx ? ["stryker", ...args] : args;
-    const result = await execa11(command, execArgs, {
+    const result = await execa14(command, execArgs, {
       cwd: config.workdir,
       reject: false,
       timeout
@@ -1304,7 +1572,7 @@ var StrykerAdapter = class {
 };
 
 // src/adapters/mutmut.ts
-import { execa as execa12 } from "execa";
+import { execa as execa15 } from "execa";
 function matchToResult(match) {
   const classname = match[1];
   const name = match[2];
@@ -1378,13 +1646,13 @@ var MutmutAdapter = class {
   }
   async executeMutmut(files, config, timeout) {
     const pathsToMutate = files.join(",");
-    const runResult = await execa12("mutmut", ["run", `--paths-to-mutate=${pathsToMutate}`, "--CI", "--no-progress"], {
+    const runResult = await execa15("mutmut", ["run", `--paths-to-mutate=${pathsToMutate}`, "--CI", "--no-progress"], {
       cwd: config.workdir,
       reject: false,
       timeout
     });
     if (runResult.timedOut) return null;
-    const xmlResult = await execa12("mutmut", ["junitxml"], {
+    const xmlResult = await execa15("mutmut", ["junitxml"], {
       cwd: config.workdir,
       reject: false
     });
@@ -1412,8 +1680,10 @@ var MutmutAdapter = class {
 };
 
 // src/adapters/mutant.ts
-import { execa as execa13 } from "execa";
-var RESULT_LINE_RE = /^(alive|killed|timeout):(.+):(.+):(\d+)/;
+import { execa as execa16 } from "execa";
+import fs8 from "fs";
+import path9 from "path";
+var RESULT_LINE_RE = /^(alive|evil|killed|timeout):(.+):([^:]+\.rb):(\d+)(?::.*)?$/;
 var COVERAGE_RE = /Coverage:\s+([\d.]+)%/;
 function parseOutput(stdout) {
   const entries = [];
@@ -1422,7 +1692,7 @@ function parseOutput(stdout) {
     const resultMatch = RESULT_LINE_RE.exec(line);
     if (resultMatch) {
       entries.push({
-        status: resultMatch[1],
+        status: resultMatch[1] === "evil" ? "alive" : resultMatch[1],
         subject: resultMatch[2],
         file: resultMatch[3],
         line: parseInt(resultMatch[4], 10)
@@ -1457,7 +1727,7 @@ function groupByFile2(entries) {
   const fileStats = /* @__PURE__ */ new Map();
   for (const [file, g] of groups) {
     const total = g.killed + g.survived + g.timeout;
-    const score = total > 0 ? (g.killed + g.timeout) / total * 100 : 100;
+    const score = total > 0 ? g.killed / total * 100 : 100;
     fileStats.set(file, { killed: g.killed, survived: g.survived, timeout: g.timeout, total, score, survivors: g.survivors });
   }
   return fileStats;
@@ -1485,7 +1755,7 @@ function processEntries(opts) {
   let totalMutants = 0;
   for (const [file, stats] of fileStatsMap) {
     if (!fileSet.has(file)) continue;
-    totalKilled += stats.killed + stats.timeout;
+    totalKilled += stats.killed;
     totalMutants += stats.total;
     if (stats.score < opts.threshold) {
       findings.push(fileStatsToFinding(file, stats, opts.threshold));
@@ -1498,31 +1768,154 @@ function processEntries(opts) {
 var MutantAdapter = class {
   name = "mutant";
   supportedLanguages = ["ruby"];
-  async isAvailable() {
-    return isBinaryAvailable("mutant");
+  async isAvailable(workdir = process.cwd()) {
+    if (!fs8.existsSync(path9.join(workdir, "Gemfile"))) {
+      return isBinaryAvailable("mutant");
+    }
+    try {
+      const result = await execa16("bundle", ["exec", "mutant", "--version"], {
+        cwd: workdir,
+        reject: false
+      });
+      return result.exitCode === 0;
+    } catch {
+      return false;
+    }
   }
   async run(files, config) {
     if (files.length === 0) return { findings: [], mutationScore: 100 };
     const timeout = config.timeout ?? 3e5;
     const threshold = config.mutationScoreThreshold ?? 80;
     const maxSurvivorFindings = config.maxSurvivorFindings ?? 5;
-    const stdout = await this.executeMutant(config.workdir, timeout);
-    if (stdout === null) return timeoutResult("mutant", timeout);
-    if (!stdout.trim()) return { findings: [], mutationScore: 100 };
-    const { entries, overallScore } = parseOutput(stdout);
-    if (entries.length === 0 && overallScore === null) return { findings: [], mutationScore: 100 };
+    if (!config.usage) {
+      return toolError(
+        "Mutant requires an explicit usage policy",
+        "Set --mutant-usage opensource or --mutant-usage commercial according to the project license."
+      );
+    }
+    let execution;
+    try {
+      execution = await this.executeMutant(files, config.workdir, timeout, config.usage);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : "unknown execution error";
+      return toolError(`Mutant could not start: ${detail}`, "Verify Bundler, Mutant, and the project test environment.");
+    }
+    if (execution.timedOut) return timeoutResult("mutant", timeout);
+    const stdout = execution.stdout;
+    if (!stdout.trim()) {
+      return toolError("Mutant produced no report", "Run Mutant through the project bundle and verify its RSpec integration.");
+    }
+    if (![0, 1].includes(execution.exitCode ?? -1)) {
+      return toolError(
+        `Mutant failed with exit code ${execution.exitCode ?? "unknown"}`,
+        "Run Mutant directly and fix its bundle, licence, Rails, or RSpec configuration."
+      );
+    }
+    const parsed = parseOutput(stdout);
+    const entries = parsed.entries.map((entry) => ({
+      ...entry,
+      file: path9.isAbsolute(entry.file) ? path9.relative(config.workdir, entry.file) : entry.file
+    }));
+    const { overallScore } = parsed;
+    if (entries.length === 0 && overallScore === null) {
+      return toolError("Mutant output could not be parsed", "Check the installed Mutant version and its command output.");
+    }
     return processEntries({ entries, overallScore, files, threshold, maxSurvivorFindings });
   }
-  async executeMutant(workdir, timeout) {
-    const result = await execa13("mutant", ["run", "--include", "lib", "--use", "rspec"], {
+  async executeMutant(files, workdir, timeout, usage) {
+    const bundled = fs8.existsSync(path9.join(workdir, "Gemfile"));
+    const command = bundled ? "bundle" : "mutant";
+    const roots = [...new Set(files.map((file) => file.split("/")[0]).filter((root) => root === "app" || root === "lib"))];
+    const railsArgs = fs8.existsSync(path9.join(workdir, "config", "environment.rb")) ? ["--require", "./config/environment"] : [];
+    const mutantArgs = [
+      "run",
+      "--usage",
+      usage,
+      ...roots.flatMap((root) => ["--include", root]),
+      ...railsArgs,
+      "--integration",
+      "rspec",
+      "--jobs",
+      "1",
+      "--",
+      ...files.map((file) => `source:${file}`)
+    ];
+    const args = bundled ? ["exec", "mutant", ...mutantArgs] : mutantArgs;
+    const result = await execa16(command, args, {
       cwd: workdir,
+      env: { RAILS_ENV: "test", CI: "true" },
       reject: false,
       timeout
     });
-    if (result.timedOut) return null;
-    return result.stdout || "";
+    return { stdout: result.stdout || "", timedOut: result.timedOut, exitCode: result.exitCode };
+  }
+};
+function toolError(message, suggestion) {
+  return {
+    findings: [{
+      file: "",
+      line: 0,
+      severity: "blocker",
+      metric: "mutation_tool_error",
+      message,
+      why: "A failed mutation test cannot be treated as a perfect mutation score.",
+      suggestion,
+      metadata: { source: "mutant" }
+    }],
+    mutationScore: 0
+  };
+}
+
+// src/adapters/test-command.ts
+import { execaCommand } from "execa";
+var TestCommandAdapter = class {
+  name = "test-command";
+  supportedLanguages = ["typescript", "javascript", "python", "ruby", "go", "rust"];
+  async isAvailable() {
+    return true;
+  }
+  async run(_files, config) {
+    let result;
+    try {
+      result = await execaCommand(config.command, {
+        cwd: config.workdir,
+        env: { CI: "true" },
+        reject: false,
+        timeout: config.timeout
+      });
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : "unknown execution error";
+      return this.failure(`Test command could not start: ${detail}`, "test_command_failed");
+    }
+    if (result.timedOut) {
+      return this.failure(`Test command timed out after ${config.timeout}ms`, "test_command_timeout");
+    }
+    if (result.exitCode !== 0) {
+      const detail = diagnosticLine(result.stderr) ?? diagnosticLine(result.stdout);
+      const message = detail ? `Test command failed with exit code ${result.exitCode}: ${detail}` : `Test command failed with exit code ${result.exitCode}`;
+      return this.failure(message, "test_command_failed");
+    }
+    return { findings: [], mutationScore: 100 };
+  }
+  failure(message, metric) {
+    const finding = {
+      file: "",
+      line: 0,
+      severity: "blocker",
+      metric,
+      message,
+      why: "The project-defined test suite must complete successfully.",
+      suggestion: "Run the configured test command directly and inspect its full logs.",
+      metadata: { source: "test-command" }
+    };
+    return { findings: [finding], mutationScore: 0 };
   }
 };
+function diagnosticLine(output) {
+  const lines = output.split("\n").map((line) => line.trim()).filter((line) => line && !/^=+$/.test(line));
+  const errorLine = lines.find((line) => /error|failed|cannot|denied|no such file|docker:/i.test(line));
+  return (errorLine ?? lines.at(-1))?.slice(0, 500);
+}
 
 // src/gates/test-quality.ts
 var TestQualityGate = class {
@@ -1530,16 +1923,18 @@ var TestQualityGate = class {
   stryker = new StrykerAdapter();
   mutmut = new MutmutAdapter();
   mutant = new MutantAdapter();
+  testCommand = new TestCommandAdapter();
   async run(ctx) {
     const start = Date.now();
     const config = ctx.config.testQuality ?? DEFAULT_TEST_QUALITY;
     const available = await this.checkAvailability(config, ctx);
-    if (!available.stryker && !available.mutmut && !available.mutant) {
+    if (!available.stryker && !available.mutmut && !available.mutant && !available.testCommand) {
       return toolMissingResult(this.name, start, "No mutation testing tools available", "Install: npm i -D @stryker-mutator/core | pip install mutmut | gem install mutant");
     }
-    const { findings, mutationScore } = await this.collectFindings(available, config, ctx);
+    const { findings, mutationScore, mutationRan } = await this.collectFindings(available, config, ctx);
     const score = calculateTestQualityScore({ mutationScore });
-    const status = deriveStatus(score, findings);
+    const hasBlocker = findings.some((finding) => finding.severity === "blocker");
+    const status = !mutationRan && available.testCommand && !hasBlocker ? "warn" : score < config.mutationScoreThreshold ? "fail" : deriveStatus(score, findings);
     return { gate: this.name, score, status, duration_ms: Date.now() - start, findings };
   }
   async checkAvailability(config, ctx) {
@@ -1549,13 +1944,13 @@ var TestQualityGate = class {
     return {
       stryker: config.strykerEnabled && tsOrJs ? await this.stryker.isAvailable(ctx.workdir) : false,
       mutmut: config.mutmutEnabled && isPython ? await this.mutmut.isAvailable() : false,
-      mutant: config.mutantEnabled && isRuby ? await this.mutant.isAvailable() : false
+      mutant: config.mutantEnabled && isRuby && (!config.testCommand || Boolean(config.mutantUsage)) ? await this.mutant.isAvailable(ctx.workdir) : false,
+      testCommand: Boolean(config.testCommand)
     };
   }
   async collectFindings(available, config, ctx) {
     const allFindings = [];
-    let totalScore = 0;
-    let adapterCount = 0;
+    const scores = [];
     const adapters = [
       { available: available.stryker, adapter: this.stryker },
       { available: available.mutmut, adapter: this.mutmut },
@@ -1567,13 +1962,33 @@ var TestQualityGate = class {
       if (result) {
         allFindings.push(...result.findings);
         if (!result.timedOut) {
-          totalScore += result.mutationScore;
-          adapterCount++;
+          scores.push(result.mutationScore);
         }
       }
     }
-    const mutationScore = adapterCount > 0 ? totalScore / adapterCount : 100;
-    return { findings: allFindings, mutationScore };
+    if (available.testCommand && config.testCommand) {
+      const result = await this.testCommand.run(ctx.files.map((file) => file.relativePath), {
+        workdir: ctx.workdir,
+        thresholds: {},
+        command: config.testCommand,
+        timeout: config.timeout
+      });
+      allFindings.push(...result.findings);
+      if (result.findings.length === 0 && scores.length === 0) {
+        allFindings.push({
+          file: "",
+          line: 0,
+          severity: "info",
+          metric: "mutation_not_run",
+          message: "Project tests passed, but mutation testing was not run",
+          why: "A passing test suite does not measure whether tests detect behavioral changes.",
+          suggestion: "Configure Mutant in the project bundle to obtain a mutation score.",
+          metadata: { source: "test-command" }
+        });
+      }
+    }
+    const mutationScore = scores.length > 0 ? Math.min(...scores) : 0;
+    return { findings: allFindings, mutationScore, mutationRan: scores.length > 0 };
   }
   async runAdapter(adapter, ctx, config) {
     const files = ctx.files.filter((f) => adapter.supportedLanguages.includes(f.language)).map((f) => f.relativePath);
@@ -1583,7 +1998,8 @@ var TestQualityGate = class {
       thresholds: {},
       timeout: config.timeout,
       mutationScoreThreshold: config.mutationScoreThreshold,
-      maxSurvivorFindings: config.maxSurvivorFindings
+      maxSurvivorFindings: config.maxSurvivorFindings,
+      usage: config.mutantUsage
     });
   }
 };
@@ -1638,7 +2054,8 @@ async function runGates(ctx, gateNames) {
 
 // src/reporter.ts
 import chalk from "chalk";
-function reportText(results, meta) {
+import { stripVTControlCharacters } from "util";
+function reportText(results, meta, options = {}) {
   const lines = [];
   lines.push(chalk.bold("=== VALIDATOR REPORT ==="));
   lines.push(`Files analyzed: ${meta.filesAnalyzed} (mode: ${meta.mode})`);
@@ -1670,7 +2087,8 @@ function reportText(results, meta) {
   lines.push(
     `RESULT: ${overall.toUpperCase()} (${blockerCount} blockers, ${warnCount} warnings)`
   );
-  return lines.join("\n");
+  const report = lines.join("\n");
+  return options.ansi === false ? stripVTControlCharacters(report) : report;
 }
 function reportJson(results, meta) {
   const allFindings = results.flatMap((r) => r.findings);
@@ -1688,7 +2106,11 @@ function reportJson(results, meta) {
     },
     gates: Object.fromEntries(results.map((r) => [r.gate, r]))
   };
-  return JSON.stringify(report, null, 2);
+  return JSON.stringify(
+    report,
+    (_key, value) => typeof value === "string" ? stripVTControlCharacters(value) : value,
+    2
+  );
 }
 function statusIcon(status) {
   switch (status) {
@@ -1786,29 +2208,70 @@ function getProfile(name) {
   return profile;
 }
 
+// src/output.ts
+import fs9 from "fs";
+import path10 from "path";
+async function writeReport(output, outputPath, workdir) {
+  const absolutePath = path10.resolve(workdir, outputPath);
+  await fs9.promises.mkdir(path10.dirname(absolutePath), { recursive: true });
+  await fs9.promises.writeFile(absolutePath, `${output}
+`, "utf8");
+  return absolutePath;
+}
+
 // src/cli.ts
 var program = new Command();
 program.name("validator").description("Validate code quality using deterministic metrics").version("0.1.0");
 function addCommonOptions(cmd) {
-  return cmd.option("-p, --profile <name>", "validation profile", "default").option("-f, --format <type>", "output format (text|json)", "text").option("-g, --gates <names>", "comma-separated gate names").option("--fail-on <level>", "exit 1 on: blocker|warning|any", "blocker");
+  return cmd.option("-p, --profile <name>", "validation profile", "default").addOption(new Option("-f, --format <type>", "output format").choices(["text", "json"]).default("text")).option("-g, --gates <names>", "comma-separated gate names").option("-o, --output <path>", "write the report to a file").option("--test-command <command>", "project test command, for example ./rspec.sh").option("--test-timeout <ms>", "test command timeout in milliseconds", parsePositiveInteger).addOption(new Option("--mutant-usage <usage>", "Mutant usage policy").choices(["opensource", "commercial"])).addOption(new Option("--fail-on <level>", "exit 1 threshold").choices(["blocker", "warning", "any"]).default("blocker"));
 }
-function handleEmptyFiles(format) {
-  if (format === "json") {
-    console.log(JSON.stringify({ status: "pass", message: "No files to analyze" }));
-  } else {
-    console.log(chalk2.gray("No source files found to analyze."));
+function parsePositiveInteger(value) {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`Expected a positive integer, received: ${value}`);
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Expected a positive integer, received: ${value}`);
   }
+  return parsed;
 }
 function checkExitCondition(results, failOn) {
   const hasFail = results.some((r) => r.status === "fail");
-  const hasWarn = results.some((r) => r.status === "warn");
-  if (failOn === "blocker" && hasFail) process.exit(1);
-  if (failOn === "warning" && (hasFail || hasWarn)) process.exit(1);
-  if (failOn === "any" && results.some((r) => r.findings.length > 0)) process.exit(1);
+  const hasWarn = results.some((r) => r.status === "warn" || r.status === "skip");
+  if (failOn === "blocker" && hasFail) process.exitCode = 1;
+  if (failOn === "warning" && (hasFail || hasWarn)) process.exitCode = 1;
+  if (failOn === "any" && results.some((r) => r.findings.length > 0)) process.exitCode = 1;
+}
+function withRuntimeOptions(profile, options) {
+  if (!options.testCommand && !options.testTimeout && !options.mutantUsage) return profile;
+  return {
+    ...profile,
+    testQuality: {
+      ...profile.testQuality ?? {
+        strykerEnabled: true,
+        mutmutEnabled: true,
+        mutantEnabled: true,
+        mutationScoreThreshold: 80,
+        timeout: 3e5,
+        maxSurvivorFindings: 5
+      },
+      testCommand: options.testCommand,
+      timeout: options.testTimeout ?? profile.testQuality?.timeout ?? 3e5,
+      mutantUsage: options.mutantUsage
+    }
+  };
+}
+async function emitReport(output, outputPath, workdir) {
+  if (!outputPath) {
+    console.log(output);
+    return;
+  }
+  const absolutePath = await writeReport(output, outputPath, workdir);
+  console.log(chalk2.gray(`Report written to ${absolutePath}`));
 }
 async function executeValidation(mode, options, targets) {
   const workdir = process.cwd();
-  const profile = getProfile(options.profile);
+  const profile = withRuntimeOptions(getProfile(options.profile), options);
   const format = options.format;
   const gateNames = options.gates ? options.gates.split(",").map((g) => g.trim()) : getAllGateNames();
   const files = await resolveFiles({
@@ -1820,15 +2283,11 @@ async function executeValidation(mode, options, targets) {
     exclude: options.exclude?.split(","),
     workdir
   });
-  if (files.length === 0) {
-    handleEmptyFiles(format);
-    return;
-  }
   const language = detectPrimaryLanguage(files);
-  const results = await runGates({ files, config: profile, workdir, language }, gateNames);
+  const results = files.length > 0 ? await runGates({ files, config: profile, workdir, language }, gateNames) : [];
   const meta = { mode, filesAnalyzed: files.length };
-  const output = format === "json" ? reportJson(results, meta) : reportText(results, meta);
-  console.log(output);
+  const output = format === "json" ? reportJson(results, meta) : reportText(results, meta, { ansi: !options.output });
+  await emitReport(output, options.output, workdir);
   checkExitCondition(results, options.failOn);
 }
 addCommonOptions(
@@ -1848,15 +2307,15 @@ addCommonOptions(
   await executeValidation("dir", options, targets);
 });
 addCommonOptions(
-  program.command("scan").description("Full project scan")
+  program.command("scan").description("Full project scan").option("-e, --exclude <patterns>", "comma-separated exclude patterns")
 ).action(async (options) => {
   await executeValidation("scan", options);
 });
 async function isToolAvailable(name, workdir) {
   const npmTools = ["stryker", "tsc", "madge", "jscpd", "knip"];
   if (npmTools.includes(name)) {
-    const localBin = path6.join(workdir, "node_modules", ".bin", name);
-    if (fs5.existsSync(localBin)) return true;
+    const localBin = path11.join(workdir, "node_modules", ".bin", name);
+    if (fs10.existsSync(localBin)) return true;
   }
   return await isBinaryAvailable(name);
 }
@@ -1866,8 +2325,11 @@ program.command("doctor").description("Check tool availability").action(async ()
     { name: "lizard", hint: "pip install lizard", gates: ["complexity"] },
     { name: "semgrep", hint: "pip install semgrep", gates: ["security"] },
     { name: "gitleaks", hint: "brew install gitleaks", gates: ["security"] },
+    { name: "brakeman", hint: "gem install brakeman", gates: ["security"] },
     { name: "tsc", hint: "npm install -g typescript", gates: ["type_safety"] },
     { name: "mypy", hint: "pip install mypy", gates: ["type_safety"] },
+    { name: "ruby", hint: "install the Ruby version used by the project", gates: ["type_safety"] },
+    { name: "bundle", hint: "gem install bundler", gates: ["type_safety", "test_quality"] },
     { name: "madge", hint: "npm install -g madge", gates: ["architecture"] },
     { name: "jscpd", hint: "npm install -g jscpd", gates: ["architecture"] },
     { name: "knip", hint: "npm install -g knip", gates: ["architecture"] },
@@ -1895,5 +2357,5 @@ ${available}/${tools.length} tools available.`);
     console.log(chalk2.gray("Gates that need missing tools will report status: skip."));
   }
 });
-program.parse();
+await program.parseAsync();
 //# sourceMappingURL=cli.js.map