rail_verdict 1.3.0 → 1.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63845a29f84295397de20a23b72c7d6e0a9d6c969be35ac8081e2536b0a37cec
-  data.tar.gz: 6e778d530c6abe87db5997b9d5fe328ebd750ac1722ede75042195b5d98d92cf
+  metadata.gz: 564018ea0a8253a34b54578dc59864000267937ac5175aa437903a5afb67ece8
+  data.tar.gz: ed89e1c5d4b7610b12eca7d66eca82e268dc17297ac040107ff26f79e620ac86
 SHA512:
-  metadata.gz: beabe5b069a803549a6af55d03f16256e5ebe7e5ab6152672a7a1fa415a75827656108c01207860251fc8936fdc3bfb6397c1f53ca53f342da5ee913051d1c2a
-  data.tar.gz: 72e637013c3a4216a90fcb466c947b6b6e97bc9035166bb8b96b76b62579c76f1253eb765d1c56ac1e39dd82197489c3535a411fece8535c6cd340bd0e741ac9
+  metadata.gz: b41423f2cedfac216e9997745f93d8480fc78d8b0b4b0d7274c2c4f9a32d430287b7250d0229e5c23374f91097dfe178df2164bc3f5bc9e0d1dcd0282382e378
+  data.tar.gz: efef3d68cf12a5f40788a946b086a74428b06afca0f1f68b9cad79d8dbbc8fdfe81ca0def0d8de3090d050afbee9e2e224f25be7b1f1961c5788a599c40efa34

data/README.md

@@ -35,7 +35,8 @@ Running test suites alone is not enough to answer a fundamental question:
 Existing tools produce fragmented formats and disparate semantics:
 
 - **RuboCop** reports style and lint offenses;
-- **RSpec** and **Minitest** report test outcomes and failures;
+- **Brakeman** reports Rails security vulnerabilities;
+- **RSpec** and **Minitest** report test outcomes and failures (with intelligent Rails-aware targeted test selection);
 - **SimpleCov** reports line coverage metrics;
 - **bundler-audit** reports gem dependency advisories;
 - **Git** tracks what actually changed.

data/lib/rail_verdict/analyzers/brakeman.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require "json"
+require "tmpdir"
+require "securerandom"
+
+require_relative "_shared"
+
+module RailVerdict
+  module Analyzers
+    class Brakeman
+      ANALYZER_ID = "brakeman"
+      SUPPORTED_VERSIONS = Gem::Requirement.new(">= 7.0", "< 9")
+
+      SEVERITY_MAP = {
+        "High" => "high",
+        "Medium" => "medium",
+        "Weak" => "low"
+      }.freeze
+
+      CONFIDENCE_MAP = {
+        "High" => "high",
+        "Medium" => "medium",
+        "Weak" => "low"
+      }.freeze
+
+      Probe = Struct.new(:status, :version, :message, keyword_init: true)
+
+      class MalformedOutput < StandardError; end
+
+      def initialize(command_resolver: nil)
+        @command_resolver = command_resolver || method(:default_command)
+      end
+
+      def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        effective_timeout = [timeout_seconds.to_f, 5.0].min
+        command = @command_resolver.call(repository_root)
+        clean_prefix = clean_args_prefix(command.fetch(:args_prefix))
+        clean_command = command.merge(args_prefix: clean_prefix)
+        invocation = Shared.invocation_for(clean_command, ["--version"])
+        result = runner.run(
+          clean_command.fetch(:executable),
+          invocation.fetch("argv"),
+          chdir: repository_root,
+          timeout_seconds: effective_timeout
+        )
+
+        return Probe.new(status: "unavailable", message: Shared.detail_for(result)) if result.status == :spawn_failed
+        return Probe.new(status: "timed_out", message: Shared.detail_for(result)) if result.status == :timed_out
+        return Probe.new(status: "signaled", message: Shared.detail_for(result)) if result.status == :signaled
+        return Probe.new(status: "truncated", message: Shared.detail_for(result)) if Shared.truncated?(result)
+        return Probe.new(status: "unavailable", message: Shared.detail_for(result)) unless result.exit_code == 0
+
+        version = Shared.parse_semver(result.stdout)
+        return Probe.new(status: "unsupported", message: "Brakeman version could not be parsed") unless version
+        return Probe.new(status: "unsupported", version: version, message: "unsupported Brakeman version #{version}") unless SUPPORTED_VERSIONS.satisfied_by?(Gem::Version.new(version))
+
+        Probe.new(status: "succeeded", version: version)
+      rescue ArgumentError
+        Probe.new(status: "unsupported", message: "Brakeman reported an invalid version")
+      rescue KeyError, ArgumentError => error
+        Probe.new(status: "malformed", message: Shared.bounded_message(error.message))
+      end
+
+      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil)
+        command = @command_resolver.call(repository_root)
+        clean_prefix = clean_args_prefix(command.fetch(:args_prefix))
+        clean_command = command.merge(args_prefix: clean_prefix)
+        probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
+        version_invocation = Shared.invocation_for(clean_command, ["--version"])
+
+        unless probe_result.status == "succeeded"
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: version_invocation, status: probe_result.status, message: probe_result.message, tool_version: probe_result.version), []]
+        end
+
+        output_path = File.join(Dir.tmpdir, "railverdict-brakeman-#{SecureRandom.hex(8)}.json")
+        public_invocation = Shared.invocation_for(clean_command, ["-q", "--no-pager", "-f", "json"])
+        run_argv = clean_prefix.dup.concat(["-q", "--no-pager", "-f", "json", "-o", output_path])
+
+        max_stdout = resolve_stdout_limit(configuration, repository_root, 16 * 1024 * 1024)
+        tool_version = probe_result.version
+
+        begin
+          result = runner.run(
+            clean_command.fetch(:executable),
+            run_argv,
+            chdir: repository_root,
+            timeout_seconds: timeout_seconds,
+            max_stdout_bytes: max_stdout
+          )
+
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "unavailable", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :spawn_failed
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "truncated", message: Shared.detail_for(result), tool_version: tool_version), []] if Shared.truncated?(result)
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "timed_out", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :timed_out
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "signaled", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :signaled
+
+          unless File.file?(output_path)
+            detail = Shared.detail_for(result)
+            msg = detail.strip.empty? ? "Brakeman did not produce structured output" : detail
+            status = result.exit_code && result.exit_code != 0 ? "failed" : "malformed"
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: status, message: msg, tool_version: tool_version), []]
+          end
+
+          begin
+            bytes = File.binread(output_path)
+          rescue SystemCallError => error
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+          end
+
+          if bytes.bytesize > max_stdout
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "truncated", message: "Brakeman output exceeds #{max_stdout} bytes", tool_version: tool_version), []]
+          end
+
+          text = bytes.dup.force_encoding(Encoding::UTF_8)
+          unless text.valid_encoding?
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "parse_failed", message: "Brakeman output is not valid UTF-8", tool_version: tool_version), []]
+          end
+
+          begin
+            document = JSON.parse(text)
+          rescue JSON::ParserError => error
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+          end
+
+          begin
+            summary, findings = normalize_document(document)
+          rescue MalformedOutput => error
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+          end
+
+          # Process exit reconciliation:
+          # 0: Clean scan (0 warnings) or explicit no-exit-on-warn
+          # 3: Warnings reported by Brakeman (findings > 0)
+          # Any other status: execution failure
+          warnings_count = summary["security_warnings"] || 0
+          if result.exit_code == 0
+            # Clean scan or non-failing mode
+          elsif result.exit_code == 3
+            if warnings_count == 0 && findings.empty?
+              detail = Shared.detail_for(result)
+              msg = detail.strip.empty? ? "Brakeman exited with status 3 but reported 0 warnings" : detail
+              return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "failed", message: msg, tool_version: tool_version), []]
+            end
+          else
+            detail = Shared.detail_for(result)
+            msg = detail.strip.empty? ? "Brakeman exited with unexpected status #{result.exit_code}" : detail
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "failed", message: msg, tool_version: tool_version), []]
+          end
+
+          analyzer_result = AnalyzerResult.new(
+            analyzer: ANALYZER_ID,
+            tool_version: tool_version,
+            invocation: public_invocation,
+            execution_status: "succeeded",
+            finding_ids: findings.map(&:id),
+            evidence_summary: summary
+          )
+          [analyzer_result, findings]
+        ensure
+          begin
+            File.unlink(output_path) if output_path && File.exist?(output_path)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      private
+
+      def default_command(repository_root)
+        if File.file?(File.join(repository_root, "Gemfile"))
+          { executable: "bundle", args_prefix: ["exec", "brakeman"] }
+        else
+          { executable: "brakeman", args_prefix: [] }
+        end
+      end
+
+      def clean_args_prefix(prefix)
+        cleaned = []
+        skip_next = false
+        Array(prefix).each_with_index do |arg, i|
+          if skip_next
+            skip_next = false
+            next
+          end
+          if (arg == "-f" || arg == "--format" || arg == "-o" || arg == "--output") && Array(prefix)[i + 1]
+            skip_next = true
+            next
+          elsif arg.start_with?("-f=") || arg.start_with?("--format=") || arg.start_with?("-o=") || arg.start_with?("--output=")
+            next
+          elsif arg == "-q" || arg == "--quiet" || arg == "--no-pager"
+            next
+          end
+          cleaned << arg
+        end
+        cleaned
+      end
+
+      def normalize_document(document)
+        raise MalformedOutput, "Brakeman JSON root must be an object" unless document.is_a?(Hash)
+
+        scan_info = document["scan_info"]
+        warnings = document["warnings"]
+        errors = document["errors"]
+
+        raise MalformedOutput, "Brakeman JSON is missing scan_info" unless scan_info.is_a?(Hash)
+        raise MalformedOutput, "Brakeman JSON is missing warnings array" unless warnings.is_a?(Array)
+
+        findings = []
+        warnings.each_with_index do |warning, index|
+          finding = normalize_warning(warning, index)
+          findings << finding if finding
+        end
+
+        findings = findings.uniq(&:fingerprint).sort_by(&:sort_key)
+        summary_h = build_summary(scan_info, findings.length)
+
+        [summary_h, findings]
+      end
+
+      def normalize_warning(warning, index)
+        raise MalformedOutput, "Brakeman warning #{index} must be an object" unless warning.is_a?(Hash)
+
+        check_name = warning["check_name"] || warning["warning_type"] || "warning_#{warning['warning_code'] || index}"
+        rule_id = check_name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")[0, 64]
+        rule_id = "warning_#{index}" if rule_id.empty?
+
+        raw_msg = warning["message"] || warning["warning_type"] || "security warning"
+        message = Shared.normalize_finding_message(ANALYZER_ID, raw_msg)
+
+        confidence_str = warning["confidence"].to_s
+        confidence = CONFIDENCE_MAP.fetch(confidence_str) { "medium" }
+        severity = SEVERITY_MAP.fetch(confidence_str) { "medium" }
+
+        category = "security"
+        path = normalize_path(warning["file"] || "unknown")
+        start_line = extract_line(warning["line"])
+
+        location = { "path" => path }
+        location["start_line"] = start_line if start_line && start_line >= 1
+        location["end_line"] = location["start_line"] if location.key?("start_line")
+
+        fingerprint = Finding.fingerprint_for(
+          analyzer: ANALYZER_ID,
+          rule_id: rule_id,
+          path: path,
+          message: message
+        )
+
+        Finding.new(
+          fingerprint: fingerprint,
+          origin: "deterministic",
+          analyzer: ANALYZER_ID,
+          rule_id: rule_id,
+          category: category,
+          severity: severity,
+          confidence: confidence,
+          state: "observed",
+          evidence_ref: "native:brakeman:#{fingerprint.delete_prefix("sha256:")[0, 12]}",
+          location: location,
+          message: message
+        )
+      rescue ArgumentError => error
+        raise MalformedOutput, "Brakeman warning #{index} is malformed: #{error.message}"
+      end
+
+      def normalize_path(file)
+        return "unknown" unless file.is_a?(String) && !file.empty?
+
+        cleaned = file.delete_prefix("./").delete_prefix("/")
+        return cleaned if cleaned.match?(Finding::LOCATION_PATH_PATTERN)
+
+        "unknown"
+      end
+
+      def extract_line(line)
+        return nil if line.nil?
+        val = Integer(line) rescue nil
+        val && val >= 1 ? val : nil
+      end
+
+      def build_summary(scan_info, security_warnings_count)
+        {
+          "security_warnings" => security_warnings_count,
+          "checks_performed" => scan_info["checks_performed"].is_a?(Array) ? scan_info["checks_performed"].length : 0,
+          "duration_seconds" => Float(scan_info["duration"] || scan_info["duration_seconds"] || 0),
+          "rails_version" => scan_info["rails_version"].to_s,
+          "ruby_version" => scan_info["ruby_version"].to_s,
+          "brakeman_version" => scan_info["brakeman_version"].to_s
+        }
+      rescue ArgumentError, TypeError
+        raise MalformedOutput, "Brakeman scan_info fields have invalid types"
+      end
+
+      def resolve_stdout_limit(configuration, repository_root, default_bytes)
+        raw_limit = nil
+        if configuration
+          sel = configuration.analyzers[ANALYZER_ID] rescue nil
+          raw_limit = sel && sel["output_limit_bytes"]
+        end
+        raw_limit ||= default_bytes
+        limit = Integer(raw_limit) rescue default_bytes
+        limit = default_bytes if limit <= 0
+        max = RailVerdict::ProcessRunner::MAX_SAFE_STDOUT_BYTES
+        [[limit, max].min, 1024].max
+      end
+    end
+  end
+end

data/lib/rail_verdict/analyzers/bundler_audit.rb

@@ -19,13 +19,14 @@ module RailVerdict
       end
 
       def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        effective_timeout = [timeout_seconds.to_f, 5.0].min
         command = @command_resolver.call(repository_root)
         invocation = Shared.invocation_for(command, ["version"])
         result = runner.run(
           command.fetch(:executable),
           invocation.fetch("argv"),
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: effective_timeout
         )
 
         return Probe.new(status: "unavailable", message: Shared.detail_for(result)) if result.status == :spawn_failed
@@ -146,7 +147,7 @@ module RailVerdict
         raw_msg = advisory["title"] || advisory["description"] || entry["title"] || entry["description"] || "vulnerability in #{gem_name}"
         message = Shared.normalize_finding_message(ANALYZER_ID, raw_msg)
 
-        rule_id = "bundler_audit/advisory:#{id}"
+        rule_id = "advisory:#{id}"
         category = "dependency"
 
         path = "Gemfile.lock"

data/lib/rail_verdict/analyzers/minitest.rb

@@ -21,13 +21,14 @@ module RailVerdict
       end
 
       def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        effective_timeout = [timeout_seconds.to_f, 5.0].min
         command = @command_resolver.call(repository_root)
         probe_argv = probe_argv_for(command, repository_root)
         result = runner.run(
           command.fetch(:executable),
           probe_argv,
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: effective_timeout
         )
 
         return Probe.new(status: "unavailable", message: Shared.detail_for(result)) if result.status == :spawn_failed
@@ -47,7 +48,7 @@ module RailVerdict
         Probe.new(status: "malformed", message: Shared.bounded_message(error.message))
       end
 
-      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil)
+      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil, target_files: nil, test_scope: "full", fallback_reason: nil)
         probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
 
         unless probe_result.status == "succeeded"
@@ -56,21 +57,48 @@ module RailVerdict
           return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: version_invocation, status: probe_result.status, message: probe_result.message, tool_version: probe_result.version), []]
         end
 
+        target_list = Array(target_files).compact.reject(&:empty?)
+        if target_files.is_a?(Array) && target_files.empty? && test_scope == "targeted"
+          summary = {
+            "schema_version" => "1.0",
+            "runner" => "minitest #{probe_result.version}",
+            "seed" => 0,
+            "tests_total" => 0,
+            "assertions" => 0,
+            "failures" => 0,
+            "errors" => 0,
+            "skips" => 0,
+            "duration_seconds" => 0.0,
+            "test_scope" => "targeted",
+            "target_files" => [],
+            "fallback_reason" => fallback_reason
+          }.compact
+          analyzer_result = AnalyzerResult.new(
+            analyzer: ANALYZER_ID,
+            tool_version: probe_result.version,
+            invocation: Shared.invocation_for(@command_resolver.call(repository_root), ["run"]),
+            execution_status: "succeeded",
+            finding_ids: [],
+            evidence_summary: summary
+          )
+          return [analyzer_result, []]
+        end
+
         command = @command_resolver.call(repository_root)
         reporter_path = resolve_reporter_path
         unless reporter_path
           return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: Shared.invocation_for(command, ["run"]), status: "malformed", message: "installed Minitest reporter is missing", tool_version: probe_result.version), []]
         end
 
-        invocation = Shared.invocation_for(command, ["run"])
-        output_path = File.join(repository_root, ".railverdict-minitest-#{SecureRandom.hex(6)}.json")
+        invocation = Shared.invocation_for(command, target_list.empty? ? ["run"] : ["run"] + target_list)
+        output_path = File.join(Dir.tmpdir, "railverdict-minitest-#{SecureRandom.hex(8)}.json")
         env_reset_required = false
         previous_env = ENV["RAILVERDICT_MINITEST_OUTPUT"]
         begin
           ENV["RAILVERDICT_MINITEST_OUTPUT"] = output_path
           env_reset_required = true
           augmented_argv = invocation.fetch("argv").dup
-          augmented_argv = inject_reporter_require(augmented_argv, reporter_path)
+          augmented_argv = inject_reporter_require(augmented_argv, reporter_path, target_files: target_list)
           result = runner.run(
             command.fetch(:executable),
             augmented_argv,
@@ -88,12 +116,30 @@ module RailVerdict
           return document if document.is_a?(Array) && document.first.is_a?(AnalyzerResult)
 
           begin
-            summary, findings = normalize_document(document)
+            summary, findings = normalize_document(document, test_scope: test_scope, target_files: target_list, fallback_reason: fallback_reason)
           rescue MalformedOutput => error
             return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
           end
 
-          analyzer_result = AnalyzerResult.new(
+          # Process exit reconciliation (RH-03):
+failures_and_errors = (summary["failures"] || 0) + (summary["errors"] || 0)
+if result.exit_code == 0
+  if failures_and_errors > 0 || !findings.empty?
+    return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: "Minitest exited with status 0 but reported #{failures_and_errors} failures/errors", tool_version: tool_version), []]
+  end
+elsif result.exit_code == 1
+  if failures_and_errors == 0 && findings.empty?
+    detail = Shared.detail_for(result)
+    msg = detail.strip.empty? ? "Minitest exited with status 1 but reported 0 failed tests" : detail
+    return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "failed", message: msg, tool_version: tool_version), []]
+  end
+else
+  detail = Shared.detail_for(result)
+  msg = detail.strip.empty? ? "Minitest exited with unexpected status #{result.exit_code}" : detail
+  return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "failed", message: msg, tool_version: tool_version), []]
+end
+
+analyzer_result = AnalyzerResult.new(
             analyzer: ANALYZER_ID,
             tool_version: tool_version,
             invocation: invocation,
@@ -141,16 +187,11 @@ module RailVerdict
 
       def resolve_reporter_path
         candidates = []
-        begin
-          specs = Gem::Specification.find_all_by_name("rail_verdict")
-          if specs.any?
-            best = specs.max_by(&:version)
-            candidates << File.join(best.full_gem_path, "exe", "railverdict-minitest-reporter.rb")
-          end
-        rescue StandardError
-          nil
-        end
         candidates << File.expand_path("../../../exe/railverdict-minitest-reporter.rb", __dir__)
+        if defined?(Gem) && Gem.respond_to?(:loaded_specs) && Gem.loaded_specs["rail_verdict"]
+          spec = Gem.loaded_specs["rail_verdict"]
+          candidates << File.join(spec.full_gem_path, "exe", "railverdict-minitest-reporter.rb")
+        end
         candidates.find { |path| File.file?(path) && File.readable?(path) }
       end
 
@@ -161,53 +202,58 @@ module RailVerdict
         base
       end
 
-      def inject_reporter_require(argv, reporter_path)
+      def inject_reporter_require(argv, reporter_path, target_files: nil)
         argv = argv.dup
+        test_expr = if target_files && !target_files.empty?
+                      files_list = target_files.map { |f| File.expand_path(f) }.inspect
+                      "#{files_list}.each{|f| require f }"
+                    else
+                      "Dir['test/**/*_test.rb'].sort.each{|f| require File.expand_path(f) }"
+                    end
         if argv.include?("run")
           idx = argv.index("run")
           argv[idx] = "-r"
           argv.insert(idx + 1, reporter_path)
           argv.insert(idx + 2, "-e")
-          argv.insert(idx + 3, "Dir['test/**/*_test.rb'].sort.each{|f| require File.expand_path(f) }")
+          argv.insert(idx + 3, test_expr)
         else
           argv.concat(["-r", reporter_path])
-          argv.concat(["-e", "Dir['test/**/*_test.rb'].sort.each{|f| require File.expand_path(f) }"])
+          argv.concat(["-e", test_expr])
         end
         argv
       end
 
       def load_reporter_document(output_path, run_result, invocation, tool_version)
-        if File.file?(output_path)
-          begin
-            bytes = File.binread(output_path)
-          rescue SystemCallError => error
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
-          end
-          if bytes.bytesize > 4 * 1024 * 1024
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "truncated", message: "Minitest reporter output exceeds 4 MiB", tool_version: tool_version), []]
-          end
-          text = bytes.dup.force_encoding(Encoding::UTF_8)
-          unless text.valid_encoding?
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: "Minitest reporter output is not valid UTF-8", tool_version: tool_version), []]
-          end
-          begin
-            return JSON.parse(text)
-          rescue JSON::ParserError => error
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
-          end
+        unless File.file?(output_path)
+          detail = Shared.detail_for(run_result)
+          msg = detail.strip.empty? ? "Minitest reporter did not produce output" : detail
+          status = run_result.exit_code && run_result.exit_code != 0 ? "failed" : "malformed"
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: status, message: msg, tool_version: tool_version), []]
         end
-        stdout = run_result.stdout.to_s
-        if stdout.strip.empty?
-          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: "Minitest reporter did not produce output", tool_version: tool_version), []]
+
+        begin
+          bytes = File.binread(output_path)
+        rescue SystemCallError => error
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+        end
+
+        if bytes.bytesize > 4 * 1024 * 1024
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "truncated", message: "Minitest reporter output exceeds 4 MiB", tool_version: tool_version), []]
         end
+
+        text = bytes.dup.force_encoding(Encoding::UTF_8)
+        unless text.valid_encoding?
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: "Minitest reporter output is not valid UTF-8", tool_version: tool_version), []]
+        end
+
         begin
-          JSON.parse(stdout)
+          JSON.parse(text)
         rescue JSON::ParserError => error
           [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
         end
       end
 
-      def normalize_document(document)
+      def normalize_document(document, test_scope: "full", target_files: nil, fallback_reason: nil)
         raise MalformedOutput, "Minitest JSON root must be an object" unless document.is_a?(Hash)
 
         required = %w[schema_version runner seed tests_total assertions failures errors skips duration_seconds tests]
@@ -229,6 +275,9 @@ module RailVerdict
 
         findings = findings.uniq { |f| f.fingerprint }.sort_by(&:sort_key)
         summary = build_summary(document)
+        summary["test_scope"] = test_scope if test_scope
+        summary["target_files"] = target_files if target_files && !target_files.empty?
+        summary["fallback_reason"] = fallback_reason if fallback_reason
         [summary, findings]
       end
 
@@ -247,7 +296,7 @@ module RailVerdict
 
         severity = status == "errored" ? "critical" : "high"
         category = "test"
-        rule_id = "minitest/test:#{class_name}##{method_name}"
+        rule_id = "test:#{class_name}##{method_name}"
         raw_msg = test["failure_message"] || test["method_name"] || "test failed: #{method_name}"
         message = Shared.normalize_finding_message(ANALYZER_ID, raw_msg)