rail_verdict 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 808405ac6448a462283966840c5b9074afff5cd43f0c2c3b477d9951e7dfe0a8
-  data.tar.gz: 2f3aa97c547c6db980c284ca4081bc09230d4e13f63369cced690f60d18ccddd
+  metadata.gz: cd73e695fc399f10d5e9dcde4f8f04294948160821c9f256234e79d6345bb8e0
+  data.tar.gz: dfb8a4b7ae5613ab75ef864dfbca00d3fa7c6241ad47937241e524aa5724b7ff
 SHA512:
-  metadata.gz: a70e6b7d070e6d4990b0b7991af2332c572e0ad2c9438b0ada3afb7e095729285b5b5714c8be8be512e1c7d8907e089bec08d5e4b62524a401719d215bc2eb28
-  data.tar.gz: 6881881853b9073e8add4c6946d1bdb0da79928a57b6d27a057e9b1646dcbe9e960a9f646c9fb9f62743f5ba3c0d61f93fc2a1fa572b529e8071268f97b69f0b
+  metadata.gz: 9faf8ca3b218e240f87800727704caa02c588d5e88fa8a614a15f0862928ad4ccd36725bbd66300d89330c9994a4f16c2f7d63cd14df2c79899b8d4380bb95de
+  data.tar.gz: 05daa4f456785c207522f9c8be75066ee0a7c112ee5681b7ea311151b3e0b2180fee7008ff97e5b79f12f439751c115a43cefc7550a1a6e16c1637296d9415c5

data/README.md

@@ -334,6 +334,22 @@ exit code `2`.
 - **Changed-Line Coverage:** Evaluates whether newly added or modified executable lines are covered by tests;
 - **Fail-Closed Git Boundary:** If the base revision is missing or repository history is shallow, RailVerdict returns `INCOMPLETE` (exit code 2) rather than guessing or silently passing.
 
+### Verification Receipts (1.2)
+
+Verification is only meaningful for the exact state that was verified. RailVerdict 1.2 binds every guarded verification to a deterministic **Repository State Identity** (HEAD + Git index snapshot + worktree delta with content hashes + configuration/baseline/waiver digests) and issues a machine-readable **Verification Receipt**:
+
+```console
+$ railverdict receipt create --format json > receipt.json
+$ railverdict receipt verify receipt.json --format json
+{"schema_version":"1.0","status":"fresh","reasons":[],"gate":"PASS", ...}
+```
+
+Edit anything afterwards — source, staged index, untracked files, config, baseline, waivers — and the same receipt reports `stale` with a deterministic reason (`head_changed`, `index_changed`, `worktree_changed`, `configuration_changed`, `baseline_changed`, `waivers_changed`). If the repository mutates while analyzers run, receipt issuance fails closed with `repository_changed_during_verification`. Receipts exist for PASS, FAIL, and INCOMPLETE alike; they are deterministic integrity records, not signed attestations — a trusted CI remains the trust anchor when forgery is in scope. Coding agents follow the completion protocol in [docs/agent-verification.md](docs/agent-verification.md).
+
+```
+Deterministic Verification → PR Intelligence → Verification Receipt → Agent Verification Protocol
+```
+
 ---
 
 ## Supported Analyzers

data/lib/rail_verdict/analyzers/_shared.rb

@@ -12,7 +12,15 @@ module RailVerdict
       def detail_for(run_result)
         detail = run_result.detail.to_s
         stderr = run_result.stderr.to_s.lines.first.to_s.strip
-        bounded_message([detail, stderr].reject(&:empty?).join(": "))
+        combined = [detail, stderr].reject(&:empty?).join(": ")
+        if combined.empty?
+          combined = if run_result.status == :exited
+            "analyzer exited with status #{run_result.exit_code} and produced no diagnostic output"
+          else
+            "analyzer produced no diagnostic output"
+          end
+        end
+        bounded_message(combined)
       end
 
       def execution_message(run_result)
@@ -40,15 +48,57 @@ module RailVerdict
 
       def failure_result(analyzer_id:, invocation:, status:, message:, tool_version: nil)
         status = status.to_s
+        bounded = bounded_message(message.to_s)
+        bounded = "#{status}: analyzer produced no diagnostic output" if bounded.strip.empty?
+        normalized_version = normalize_tool_version(tool_version)
         AnalyzerResult.new(
           analyzer: analyzer_id,
-          tool_version: tool_version,
+          tool_version: normalized_version,
           invocation: invocation,
           execution_status: status,
           finding_ids: [],
-          failure: { "code" => status, "message" => bounded_message(message.to_s) }
+          failure: { "code" => status, "message" => bounded }
         )
       end
+
+      def normalize_tool_version(version)
+        return nil if version.nil?
+        str = version.to_s.strip
+        return nil if str.empty?
+        str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?").scrub("?")[0, 128]
+      end
+
+      def canonical_tool_version(version)
+        normalized = normalize_tool_version(version)
+        normalized.nil? || normalized.empty? ? "unknown" : normalized
+      end
+
+      # Canonical finding message normalization — single path for all analyzers.
+      # Guarantees deterministic, bounded, valid non-empty UTF-8.
+      FALLBACK_MESSAGE_SUFFIX = "reported a finding without a message"
+
+      def normalize_finding_message(analyzer_id, raw_message)
+        raw = raw_message.to_s.dup
+        # Handle invalid UTF-8, null bytes
+        raw = raw.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+        raw = raw.scrub("\uFFFD")
+        raw = raw.delete("\u0000")
+        # Strip ANSI escape sequences
+        raw = raw.gsub(/\e\[[0-9;]*[A-Za-z]/, "")
+        raw = raw.gsub(/\e\][^\a]*\a/, "")
+        raw = raw.gsub(/\e\(B/, "")
+        # Remove control characters except tab/newline then normalize whitespace
+        raw = raw.gsub(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/, "")
+        raw = raw.strip
+        # Collapse whitespace including tabs/newlines
+        raw = raw.gsub(/\s+/, " ").strip
+        if raw.empty?
+          "#{analyzer_id} #{FALLBACK_MESSAGE_SUFFIX}"
+        else
+          raw = raw.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD").scrub("\uFFFD")
+          raw.bytesize > 4096 ? raw.byteslice(0, 4096).scrub("\uFFFD").strip : raw
+        end
+      end
     end
   end
 end

data/lib/rail_verdict/analyzers/bundler_audit.rb

@@ -47,7 +47,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)
+      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil)
         command = @command_resolver.call(repository_root)
         probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
         version_invocation = Shared.invocation_for(command, ["version"])
@@ -143,9 +143,8 @@ module RailVerdict
         gem_name = "unknown" if gem_name.to_s.empty?
 
         severity = map_severity(advisory["criticality"] || advisory["severity"] || entry["criticality"] || entry["severity"])
-        message = (advisory["title"] || advisory["description"] || entry["title"] || entry["description"] || "vulnerability in #{gem_name}").to_s
-        message = message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 4096]
-        message = "vulnerability in #{gem_name}" if message.empty?
+        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}"
         category = "dependency"

data/lib/rail_verdict/analyzers/minitest.rb

@@ -47,7 +47,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)
+      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil)
         probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
 
         unless probe_result.status == "succeeded"
@@ -248,12 +248,8 @@ module RailVerdict
         severity = status == "errored" ? "critical" : "high"
         category = "test"
         rule_id = "minitest/test:#{class_name}##{method_name}"
-        message = (test["failure_message"] || test["method_name"]).to_s
-        message = message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 4096]
-        message = "test failed: #{method_name}" if message.empty?
-        unless message.is_a?(String) && message.valid_encoding? && !message.empty? && message.bytesize <= 4096
-          raise MalformedOutput, "Minitest finding message is invalid"
-        end
+        raw_msg = test["failure_message"] || test["method_name"] || "test failed: #{method_name}"
+        message = Shared.normalize_finding_message(ANALYZER_ID, raw_msg)
 
         path = normalize_path(test["file"], class_name)
         start_line = test["line"]

data/lib/rail_verdict/analyzers/rspec.rb

@@ -45,7 +45,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)
+      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil)
         command = @command_resolver.call(repository_root)
         probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
         version_invocation = Shared.invocation_for(command, ["--version"])
@@ -55,11 +55,14 @@ module RailVerdict
         end
 
         invocation = Shared.invocation_for(command, ["--format", "json"])
+        # Real-world large RSpec suites can exceed 4 MiB; use bounded but larger capture.
+        max_stdout = resolve_stdout_limit(configuration, repository_root, 16 * 1024 * 1024)
         result = runner.run(
           command.fetch(:executable),
           invocation.fetch("argv"),
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: timeout_seconds,
+          max_stdout_bytes: max_stdout
         )
         tool_version = probe_result.version
 
@@ -136,9 +139,8 @@ module RailVerdict
           return nil
         end
 
-        message = (example["exception"] && example["exception"]["message"]) || example["full_description"] || example["description"] || "rspec example failed"
-        message = message.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")[0, 4096]
-        message = "rspec example failed" if message.empty?
+        raw_msg = (example["exception"] && example["exception"]["message"]) || example["full_description"] || example["description"] || nil
+        message = Shared.normalize_finding_message(ANALYZER_ID, raw_msg.nil? || raw_msg.to_s.strip.empty? ? "rspec example failed" : raw_msg)
 
         rule_id = "rspec/example:#{example['id'] || id_for(example, index)}"
         path = normalize_path(example["file_path"] || example["file"] || "spec/unknown_spec.rb")
@@ -269,6 +271,21 @@ module RailVerdict
       rescue ArgumentError, TypeError
         raise MalformedOutput, "RSpec summary fields have invalid types"
       end
+
+      def resolve_stdout_limit(configuration, repository_root, default_bytes)
+        # Prefer explicit per-analyzer config if present (future-compatible), else default.
+        raw_limit = nil
+        if configuration
+          sel = configuration.analyzers[ANALYZER_ID] rescue nil
+          raw_limit = sel && sel["output_limit_bytes"]
+        end
+        raw_limit ||= default_bytes
+        # Clamp to safe ceiling
+        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/rubocop.rb

@@ -55,7 +55,7 @@ module RailVerdict
         Probe.new(status: "malformed", message: bounded_message(error.message))
       end
 
-      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil)
+      def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil)
         command = @command_resolver.call(repository_root)
         probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
         version_invocation = invocation_for(command, ["--version"])
@@ -65,11 +65,13 @@ module RailVerdict
         end
 
         invocation = invocation_for(command, ["--format", "json"])
+        max_stdout = resolve_stdout_limit(configuration, 8 * 1024 * 1024)
         result = runner.run(
           command.fetch(:executable),
           invocation.fetch("argv"),
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: timeout_seconds,
+          max_stdout_bytes: max_stdout
         )
         tool_version = probe_result.version
 
@@ -255,10 +257,8 @@ module RailVerdict
           raise MalformedOutput, "RuboCop offense line range is invalid"
         end
 
-        message = offense["message"]
-        unless message.is_a?(String) && message.valid_encoding? && !message.empty? && message.bytesize <= 4096
-          raise MalformedOutput, "RuboCop offense message is invalid"
-        end
+        raw_msg = offense["message"]
+        message = Shared.normalize_finding_message(ANALYZER_ID, raw_msg)
 
         fingerprint = Finding.fingerprint_for(
           analyzer: ANALYZER_ID,
@@ -284,6 +284,14 @@ module RailVerdict
       rescue ArgumentError => error
         raise MalformedOutput, "RuboCop offense #{file_index}:#{offense_index} is malformed: #{error.message}"
       end
+
+      def resolve_stdout_limit(configuration, default_bytes)
+        raw = configuration && configuration.analyzers["rubocop"] && configuration.analyzers["rubocop"]["output_limit_bytes"]
+        raw ||= default_bytes
+        limit = Integer(raw) rescue default_bytes
+        limit = default_bytes if limit <= 0
+        [[limit, RailVerdict::ProcessRunner::MAX_SAFE_STDOUT_BYTES].min, 1024].max
+      end
     end
   end
 end

data/lib/rail_verdict/analyzers/simplecov.rb

@@ -26,12 +26,21 @@ module RailVerdict
         return Probe.new(status: "parse_failed", message: "coverage file is not valid UTF-8") unless text.valid_encoding?
 
         document = JSON.parse(text)
-        return Probe.new(status: "unsupported", message: "coverage document has no version") unless document["version"].is_a?(String)
-
-        version = document["version"]
-        return Probe.new(status: "unsupported", message: "unsupported SimpleCov version #{version}") unless version.start_with?("1")
-
-        Probe.new(status: "succeeded", version: version)
+        detected = detect_format(document)
+        case detected
+        when :coverage_v1
+          version = document["version"].to_s
+          return Probe.new(status: "unsupported", message: "unsupported SimpleCov version #{version}") unless version.start_with?("1")
+          Probe.new(status: "succeeded", version: version)
+        when :native_simplecov
+          version = extract_native_version(document)
+          # Accept any native simplecov version >=0.20 with coverage hash; version check is permissive.
+          Probe.new(status: "succeeded", version: version)
+        when :unsupported
+          Probe.new(status: "unsupported", message: "unsupported coverage document shape")
+        else
+          Probe.new(status: "malformed", message: "coverage document is malformed")
+        end
       rescue JSON::ParserError => error
         Probe.new(status: "parse_failed", message: Shared.bounded_message(error.message))
       rescue MalformedOutput => error
@@ -72,21 +81,47 @@ module RailVerdict
           return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: Shared.bounded_message(error.message)), []]
         end
 
-        version = document["version"].to_s
-        probe_result ||= probe(repository_root, timeout_seconds: timeout_seconds)
-        unless version.start_with?("1")
-          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "unsupported", message: "unsupported SimpleCov version #{version}", tool_version: probe_result.version || version), []]
+        detected = detect_format(document)
+        if detected == :unsupported
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "unsupported", message: "unsupported coverage document shape", tool_version: probe_result&.version), []]
+        elsif detected == :malformed
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: "coverage document is malformed", tool_version: probe_result&.version), []]
         end
 
-        errors = validate_coverage_schema(document)
-        unless errors.empty?
-          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: errors.first, tool_version: probe_result.version || version), []]
+        normalized = nil
+        version = nil
+        if detected == :coverage_v1
+          version = document["version"].to_s
+          probe_result ||= probe(repository_root, timeout_seconds: timeout_seconds)
+          unless version.start_with?("1")
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "unsupported", message: "unsupported SimpleCov version #{version}", tool_version: probe_result.version || version), []]
+          end
+          errors = validate_coverage_schema(document)
+          unless errors.empty?
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: errors.first, tool_version: probe_result.version || version), []]
+          end
+          normalized = normalize_coverage_v1(document)
+          version = document["version"].to_s
+        elsif detected == :native_simplecov
+          begin
+            normalized = normalize_native_document(document, repository_root)
+            version = extract_native_version(document)
+          rescue MalformedOutput => error
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: probe_result&.version), []]
+          end
+          # Validate normalized shape via same schema
+          errors = validate_coverage_schema(normalized)
+          unless errors.empty?
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: errors.first, tool_version: version), []]
+          end
+        else
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: "coverage document shape is not supported", tool_version: probe_result&.version), []]
         end
 
         mtime = File.mtime(full_path)
         stale = (Time.now - mtime) > freshness_window
 
-        covered, executable = coverage_totals(document)
+        covered, executable = coverage_totals(normalized)
 
         summary = {
           "covered_lines" => covered,
@@ -95,7 +130,8 @@ module RailVerdict
           "stale" => stale,
           "freshness_window_seconds" => Integer(freshness_window),
           "coverage_path" => coverage_path.to_s[0, 512],
-          "files" => document["files"]
+          "files" => normalized["files"],
+          "_coverage_document" => normalized
         }
 
         result = AnalyzerResult.new(
@@ -114,6 +150,152 @@ module RailVerdict
 
       private
 
+      def detect_format(document)
+        return :malformed unless document.is_a?(Hash)
+
+        # coverage-v1 has version starting with "1" and files array
+        if document["version"].is_a?(String) && document["files"].is_a?(Array)
+          return :coverage_v1
+        end
+
+        # Native SimpleCov JSON: has "coverage" hash where values contain lines
+        if document["coverage"].is_a?(Hash) && !document["coverage"].empty?
+          sample = document["coverage"].values.first
+          # Native values are hashes with "lines" key
+          if sample.is_a?(Hash) && sample.key?("lines")
+            return :native_simplecov
+          end
+        end
+
+        # Native may have empty coverage hash (empty file)
+        if document.key?("coverage") && document["coverage"].is_a?(Hash) && document["meta"].is_a?(Hash)
+          return :native_simplecov
+        end
+
+        # Also consider empty coverage hash without meta but with groups
+        if document.key?("coverage") && document["coverage"].is_a?(Hash) && document["coverage"].empty?
+          # Could be native empty or malformed; treat as native if meta or groups present
+          return :native_simplecov if document.key?("meta") || document.key?("groups")
+          # Fallback: if no files and no version, it's unsupported rather than malformed
+          return :unsupported
+        end
+
+        # If document has no recognizable shape but is Hash with coverage key mismatched
+        if document.key?("coverage") || document.key?("meta") || document.key?("groups")
+          return :native_simplecov if document["coverage"].is_a?(Hash)
+        end
+
+        # If it has version but not files, or files but wrong shape => unsupported/malformed via validator
+        if document.key?("version") || document.key?("files") || document.key?("timestamp")
+          # Let schema validation decide malformed vs unsupported
+          # If version exists but not starting 1 => unsupported
+          if document["version"].is_a?(String) && !document["version"].start_with?("1")
+            return :unsupported
+          end
+          return :malformed if document.key?("files") || document.key?("version")
+        end
+
+        :unsupported
+      end
+
+      def extract_native_version(document)
+        meta = document["meta"]
+        if meta.is_a?(Hash) && meta["simplecov_version"].is_a?(String) && !meta["simplecov_version"].empty?
+          return meta["simplecov_version"].to_s[0, 64]
+        end
+        if document["version"].is_a?(String) && !document["version"].empty?
+          return document["version"].to_s[0, 64]
+        end
+        # Default for native without explicit version
+        "1.0"
+      end
+
+      def normalize_native_document(document, repository_root)
+        coverage_hash = document["coverage"]
+        raise MalformedOutput, "native SimpleCov document has no coverage hash" unless coverage_hash.is_a?(Hash)
+
+        files = []
+        coverage_hash.keys.sort.each do |raw_path|
+          entry = coverage_hash[raw_path]
+          raise MalformedOutput, "coverage entry for #{raw_path} must be an object" unless entry.is_a?(Hash)
+
+          lines_raw = entry["lines"]
+          raise MalformedOutput, "coverage lines for #{raw_path} must be an array" unless lines_raw.is_a?(Array)
+
+          lines = lines_raw.map do |hit|
+            case hit
+            when Integer
+              hit >= 0 ? hit : (raise MalformedOutput, "negative coverage hit")
+            when NilClass
+              nil
+            when String
+              # SimpleCov uses "ignored" for skipped lines
+              hit == "ignored" ? nil : (raise MalformedOutput, "unexpected string in coverage lines: #{hit.inspect}")
+            else
+              raise MalformedOutput, "coverage lines must be integers, null, or \"ignored\""
+            end
+          end
+
+          filename = normalize_native_path(raw_path, repository_root)
+
+          # Skip empty paths after normalization
+          raise MalformedOutput, "normalized path is empty for #{raw_path}" if filename.empty?
+          unless filename.match?(RailVerdict::Finding::LOCATION_PATH_PATTERN)
+            raise MalformedOutput, "coverage filename is not a clean repository-relative path: #{filename.inspect}"
+          end
+
+          files << { "filename" => filename, "coverage" => { "lines" => lines } }
+        end
+
+        files.sort_by! { |f| f["filename"] }
+
+        {
+          "version" => "1.0",
+          "timestamp" => document["timestamp"].is_a?(Integer) ? document["timestamp"] : Time.now.to_i,
+          "files" => files
+        }
+      end
+
+      def normalize_native_path(raw_path, repository_root)
+        str = raw_path.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?").scrub("?").strip
+        str = str.delete("\u0000")
+        # Remove leading ./ 
+        str = str.delete_prefix("./")
+        # If absolute, make relative to repository_root if possible
+        if str.start_with?("/")
+          begin
+            root = File.realpath(repository_root)
+            abs = File.expand_path(str)
+            # Use Pathname relative if inside root
+            require "pathname"
+            rel = Pathname.new(abs).relative_path_from(Pathname.new(root)).to_s rescue nil
+            if rel && !rel.start_with?("..") && rel.match?(RailVerdict::Finding::LOCATION_PATH_PATTERN)
+              return rel
+            end
+          rescue StandardError
+            nil
+          end
+          # Fallback: strip leading slash
+          str = str.delete_prefix("/")
+        end
+        # Normalize redundant separators and strip
+        str = str.gsub(%r{//+}, "/")
+        str = str.strip
+        str
+      end
+
+      def normalize_coverage_v1(document)
+        # Already validated; ensure deterministic ordering by filename
+        files = document["files"].map do |f|
+          { "filename" => f["filename"].to_s, "coverage" => { "lines" => f.dig("coverage", "lines") } }
+        end.sort_by { |f| f["filename"] }
+        {
+          "version" => document["version"].to_s,
+          "timestamp" => document["timestamp"],
+          "files" => files
+        }
+      end
+
       def load_config(repository_root, configuration: nil)
         if configuration
           sel = configuration.analyzers["simplecov"]

data/lib/rail_verdict/baseline.rb

@@ -51,6 +51,10 @@ module RailVerdict
         }
       end
       entries = entries.uniq { |entry| entry.fetch("fingerprint") }.sort_by { |entry| entry.fetch("fingerprint") }
+      canonical_versions = {}
+      analyzer_versions.each do |key, value|
+        canonical_versions[key.to_s] = RailVerdict::Analyzers::Shared.canonical_tool_version(value)
+      end
       hash = {
         "schema_version" => SCHEMA_VERSION,
         "fingerprint_version" => Fingerprint::VERSION,
@@ -59,7 +63,7 @@ module RailVerdict
         "created_at" => created_at,
         "created_by" => "railverdict #{RailVerdict::VERSION}",
         "configuration_digest" => configuration.digest,
-        "analyzer_versions" => analyzer_versions.transform_keys(&:to_s).sort.to_h,
+        "analyzer_versions" => canonical_versions.sort.to_h,
         "entries" => entries
       }
       errors = SchemaValidator.validate_baseline(hash)

data/lib/rail_verdict/canonical_json.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailVerdict
+  module CanonicalJSON
+    module_function
+
+    def generate(value)
+      JSON.generate(canonicalize(value))
+    end
+
+    def canonicalize(value)
+      case value
+      when Hash
+        value.keys.sort_by(&:to_s).to_h { |key| [key, canonicalize(value[key])] }
+      when Array
+        value.map { |item| canonicalize(item) }
+      when String
+        scrub_text(value)
+      else
+        value
+      end
+    end
+
+    def scrub_text(text)
+      text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+          .gsub(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/, "?")
+    end
+  end
+end