saboteur 0.4.0 → 0.6.0

data/lib/saboteur/reporter/agent_commands.rb

@@ -15,7 +15,8 @@ module Saboteur
 
         # Options typed on the command line that change how a run behaves.
         SETTING_FLAGS = { reeval: "--reeval", integration: "--integration", jobs: "--jobs",
-                          timeout_factor: "--timeout-factor", json_report: "--json", html_report: "--html" }.freeze
+                          timeout_factor: "--timeout-factor", json_report: "--json", html_report: "--html",
+                          operators: "--operators", exclude_operators: "--exclude-operators" }.freeze
 
         class << self
           # Run the same selection again: ref, subjects, sources, tests, config,
@@ -40,15 +41,28 @@ module Saboteur
             command.bytesize <= MAX_BYTES ? command : nil
           end
 
+          # An explicit scope is frozen: --no-guess-tests keeps a config-file
+          # guess_tests from conflicting with the --test list.
+          def test_words(tests)
+            tests.empty? ? [] : ["--no-guess-tests", *tests.flat_map { |test| ["--test", test] }]
+          end
+
+          def setting_words(provenance)
+            SETTING_FLAGS.flat_map do |key, flag|
+              next [] unless provenance.settings.key?(key)
+
+              value = provenance.settings[key]
+              [flag, value.is_a?(Array) ? value.join(",") : value.to_s]
+            end
+          end
+
           def selection(provenance, replay: false)
             words = []
             words.push("--config", provenance.config_path) if provenance.config_path
             words.push("--since", provenance.ref) if provenance.ref
             provenance.subjects.each { |subject| words.push("--subject", subject) }
-            provenance.tests.each { |test| words.push("--test", test) }
-            SETTING_FLAGS.each do |key, flag|
-              words.push(flag, provenance.settings[key].to_s) if provenance.settings.key?(key)
-            end
+            words.push(*test_words(provenance.tests))
+            words.concat(setting_words(provenance))
             words << "--no-cache" if provenance.cache == false
             words << "--incremental" if provenance.incremental
             words.push("--id", provenance.digest) if provenance.digest && !replay

data/lib/saboteur/reporter/agent_incomplete.rb

@@ -7,24 +7,47 @@ module Saboteur
       # What makes a verdict cover less than the whole selection. Each reason has a
       # stable code, a count and a plain meaning.
       module Incomplete
+        NO_COVERAGE = "no coverage"
+
         class << self
           def reasons(report)
             reasons = []
             add(reasons, "no_coverage", skipped_for_coverage(report), "subjects or mutants had no covering test")
+            load_only = report.counts[:ran_at_load] + report.skipped_subjects.values.count do |reason|
+              reason == Selection::CoverageMap::RAN_AT_LOAD
+            end
+            add(reasons, "unsupported", unsupported_subjects(report),
+                "subjects were skipped as unsupported (for example defined inside a block); no mutant was judged")
+            add(reasons, "ran_at_load", load_only, "code ran only at load; no mutant was judged")
+            add(reasons, "unreachable", report.counts[:unreachable], "tests did not call the replacement definition")
             add(reasons, "mutant_cap", omitted_by_cap(report), "mutants omitted by max_mutants_per_method")
             add(reasons, "errors", report.counts[:error], "mutants errored; their verdict did not hold up")
             add(reasons, "resource_limit", report.counts[:resource_limit], "mutants hit the memory or process cap")
+            add(reasons, "fail_fast", report.early_stop&.unreached&.size.to_i,
+                "selected subjects did not run because --fail-fast stopped the run")
+            inline_scope(reasons, report)
             reasons
           end
 
           private
 
+          def inline_scope(reasons, report)
+            add(reasons, "inline_suppressed", report.inline_suppressions.size,
+                "candidates were suppressed by inline directives; see the full report audit")
+          end
+
           def add(reasons, code, count, meaning)
             reasons << { reason: code, count: count, meaning: meaning } if count.positive?
           end
 
           def skipped_for_coverage(report)
-            report.skipped_subjects.size + report.counts[:skipped]
+            report.skipped_subjects.values.count(NO_COVERAGE) + report.counts[:skipped]
+          end
+
+          def unsupported_subjects(report)
+            report.skipped_subjects.values.count do |reason|
+              reason != NO_COVERAGE && reason != Selection::CoverageMap::RAN_AT_LOAD
+            end
           end
 
           def omitted_by_cap(report)

data/lib/saboteur/reporter/agent_summary.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "findings"
+require_relative "survivor_hints"
 require_relative "agent_incomplete"
 require_relative "agent_clipping"
 
@@ -21,12 +22,12 @@ module Saboteur
             verdict = verdict_of(report, status)
             {
               version: VERSION, status: status, verdict: verdict, exitCode: exit_code_for(verdict),
-              provenance: provenance_hash(provenance),
+              provenance: provenance_hash(provenance).merge(operatorPolicy: report.operator_policy),
               counts: counts(report), score: score(report),
               scoreDefinition: "(killed + timeout) / (killed + survived + timeout); null when nothing was tested",
               incomplete: incomplete, timeoutCountedAsDetected: report.counts[:timeout],
               findings: findings(report, shown, snippet_limit),
-              warnings: warnings(report),
+              warnings: report.warnings.first(WARNING_LIMIT).map { |warning| warning.to_s[0, WARNING_LENGTH] },
               next: next_steps(report, provenance)
             }
           end
@@ -34,7 +35,7 @@ module Saboteur
           private
 
           def status_of(report, incomplete)
-            return "not_applicable" if report.results.empty? && report.skipped_subjects.empty?
+            return "not_applicable" if report.results.empty? && incomplete.empty?
 
             incomplete.empty? ? "complete" : "partial"
           end
@@ -87,7 +88,8 @@ module Saboteur
             {
               survivors: live, shown: shown_findings(all[:survivors], shown, snippet_limit),
               omitted: live - [shown, all[:survivors].size].min,
-              accepted: report.survivors.size - live, ordering: all[:ordering]
+              accepted: report.survivors.size - live, ordering: all[:ordering],
+              hintCaveat: SurvivorHints::CAVEAT
             }
           end
 
@@ -97,11 +99,15 @@ module Saboteur
                      .merge(path: clip_value(finding[:path], 200), subject: clip_value(finding[:subject], 200),
                             original: clip(finding[:original], snippet_limit),
                             replacement: clip(finding[:replacement], snippet_limit))
+                     .merge(finding_hints(finding))
             end
           end
 
-          def warnings(report)
-            report.warnings.first(WARNING_LIMIT).map { |warning| warning.to_s[0, WARNING_LENGTH] }
+          def finding_hints(finding)
+            structured = SurvivorHints.structured(operator: finding[:operator], original: finding[:original],
+                                                  replacement: finding[:replacement], coarse: finding[:coarse])
+            { hint: SurvivorHints.for(finding[:operator], coarse: finding[:coarse]) }.compact
+                                                                                     .merge(testHint: structured)
           end
 
           def next_steps(report, provenance)

data/lib/saboteur/reporter/findings.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "survivor_ranking"
+
 module Saboteur
   module Reporter
     # Findings for a code-review surface such as the saboteur GitHub Action:
@@ -15,12 +17,7 @@ module Saboteur
       # GitHub shows at most 10 annotations of one kind per step.
       LIMIT = 10
 
-      # Published ordering, coarse survivors first: a surviving coarse mutant
-      # replaced the whole method body, which hints that no test pins the
-      # method's behavior - though it can also be a re-evaluation limit or an
-      # equivalent mutant, so this is a heuristic, not a guarantee. Ties break
-      # by file, line and digest, so one report always reads the same way.
-      ORDERING = "coarse survivors first, then file, line and digest"
+      ORDERING = SurvivorRanking::ORDERING
 
       class << self
         def build(report)
@@ -46,20 +43,8 @@ module Saboteur
           [results.size - LIMIT, 0].max
         end
 
-        # partition keeps the coarse group ahead; inside a group the key is
-        # total (no two mutants share a digest), so the order is stable.
         def ordered(report, results)
-          results.partition { |result| result.mutation.coarse }
-                 .map { |group| group.sort_by { |result| tie_break(report, result) } }
-                 .flatten
-        end
-
-        def tie_break(report, result)
-          [path(report, result), first_line(result), result.digest]
-        end
-
-        def first_line(result)
-          result.subject.line_of(result.mutation.edits.map(&:start_byte).min)
+          SurvivorRanking.ordered(report, results)
         end
 
         def finding(report, result)

data/lib/saboteur/reporter/history_paths.rb

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # Refuses linked or non-regular history/report destinations before writes.
+    module HistoryPaths
+      module_function
+
+      def validate(paths)
+        paths = paths.compact.map { |path| File.expand_path(path) }
+        identities = paths.map do |path|
+          reject_links(path)
+          next unless File.exist?(path)
+
+          stat = File.stat(path)
+          raise Error, "score history/report destination must be a regular file" unless stat.file?
+
+          [stat.dev, stat.ino]
+        end.compact
+        raise Error, "score history/report destinations alias the same file" unless identities.uniq == identities
+      rescue SystemCallError => e
+        raise Error, "score history/report paths cannot be verified: #{e.message}"
+      end
+
+      def reject_links(path)
+        loop do
+          raise Error, "score history/report paths must not contain symlinks" if File.symlink?(path)
+
+          parent = File.dirname(path)
+          break if parent == path
+
+          path = parent
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/history_policy.rb

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # v1 stays readable, but v2 records require versioned operator evidence.
+    module HistoryPolicy
+      def validate_header(record, fields)
+        version = record.is_a?(Hash) && record["version"]
+        raise Error, "score history contains an invalid version" unless version.is_a?(Integer) && [1,
+                                                                                                   2].include?(version)
+
+        fields(record, version == 2 ? fields + ["operatorPolicy"] : fields)
+        validate_policy(record["operatorPolicy"]) if version == 2
+      end
+
+      def validate_policy(value)
+        raise Error, "score history contains invalid operator policy" unless value.is_a?(Hash)
+
+        fields(value, %w[version selected excluded effective])
+        raise Error, "score history contains invalid operator policy" if value["effective"].empty?
+
+        lists = value.values_at("selected", "excluded", "effective")
+        unless lists.all? { |list| list.is_a?(Array) && list.all?(String) }
+          raise Error, "score history contains invalid operator policy"
+        end
+
+        expected = MutationSource::OperatorRegistry.policy(value["selected"], value["excluded"])
+        raise Error, "score history contains invalid operator policy" unless value == expected
+      rescue ConfigError, NoMethodError, TypeError
+        raise Error, "score history contains invalid operator policy"
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/history_record.rb

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "history_policy"
+
+module Saboteur
+  module Reporter
+    # Strict version-one observation schema. Never repairs imported evidence.
+    module HistoryRecord
+      FIELDS = %w[version date commit selection inventory score coveredScore counts breakdown incomplete].freeze
+      BREAKDOWN = %w[score tested assertionKills crashKills unclassifiedKills timeouts survivors
+                     assertionShare crashShare].freeze
+      COUNTS = STATUSES.map(&:to_s).freeze
+
+      class UniqueObject < Hash
+        def []=(key, value)
+          raise Error, "score history contains duplicate keys" if key?(key)
+
+          super
+        end
+      end
+
+      extend HistoryPolicy
+
+      module_function
+
+      def parse(line)
+        record = JSON.parse(line, object_class: UniqueObject)
+        validate(record)
+        record
+      rescue JSON::ParserError, ArgumentError, TypeError => e
+        raise Error, "score history contains an invalid record: #{e.message}"
+      end
+
+      def validate(record)
+        validate_header(record, FIELDS)
+
+        date(record.fetch("date"))
+        commit = record.fetch("commit")
+        raise Error, "score history contains an invalid commit" unless commit.nil? || sha?(commit, 40)
+
+        %w[selection inventory].each do |key|
+          raise Error, "score history contains an invalid digest" unless sha?(record.fetch(key), 64)
+        end
+        %w[score coveredScore].each { |key| fraction(record.fetch(key)) }
+        counts = record.fetch("counts")
+        fields(counts, COUNTS)
+        counts.each_value { |value| count(value) }
+        breakdown(record.fetch("breakdown"), counts, record.fetch("coveredScore"))
+        score_consistency(record)
+        reasons(record.fetch("incomplete"))
+      end
+
+      def date(value)
+        return if Time.iso8601(value).utc.iso8601 == value
+
+        raise Error,
+              "score history contains an invalid date"
+      rescue ArgumentError, TypeError, NoMethodError => e
+        raise Error, "score history contains an invalid date: #{e.message}"
+      end
+
+      def reasons(value)
+        unless value.is_a?(Array) && value.all? do |reason|
+          reason.is_a?(String) && !reason.empty?
+        end && value.uniq == value
+          raise Error, "score history contains invalid incomplete reasons"
+        end
+      end
+
+      def score_consistency(record)
+        value = record.fetch("breakdown")
+        detected = value.values_at("assertionKills", "crashKills", "unclassifiedKills", "timeouts").sum
+        tested = value.fetch("tested")
+        expected = tested.zero? ? nil : detected.fdiv(tested)
+        raise Error, "score history contains an inconsistent score" unless record.fetch("coveredScore") == expected
+
+        %w[assertion crash].each do |kind|
+          expected_share = tested.zero? ? nil : value.fetch("#{kind}Kills").fdiv(tested)
+          unless value.fetch("#{kind}Share") == expected_share
+            raise Error,
+                  "score history contains an inconsistent share"
+          end
+        end
+        overall = record.fetch("score")
+        return unless overall && ((record.fetch("coveredScore").nil? && !overall.zero?) ||
+                          (record.fetch("coveredScore") && overall > record.fetch("coveredScore")))
+
+        raise Error, "score history contains an inconsistent overall score"
+      end
+
+      def fields(object, expected)
+        return if object.is_a?(Hash) && object.keys.sort == expected.sort
+
+        raise Error,
+              "score history contains an invalid record schema"
+      end
+
+      def sha?(value, length)
+        value.is_a?(String) && value.match?(/\A[0-9a-f]{#{length}}\z/)
+      end
+
+      def fraction(value)
+        return if value.nil? || (0..1).cover?(value)
+
+        raise Error,
+              "score history contains an invalid score"
+      end
+
+      def count(value)
+        raise Error, "score history contains an invalid count" unless value.is_a?(Integer) && value >= 0
+      end
+
+      def breakdown(value, counts, covered)
+        fields(value, BREAKDOWN)
+        %w[score assertionShare crashShare].each { |key| fraction(value.fetch(key)) }
+        (BREAKDOWN - %w[score assertionShare crashShare]).each { |key| count(value.fetch(key)) }
+        kills = value.values_at("assertionKills", "crashKills", "unclassifiedKills").sum
+        tested = counts.values_at("killed", "survived", "timeout").sum
+        unless kills == counts.fetch("killed") && value.fetch("tested") == tested &&
+               value.fetch("timeouts") == counts.fetch("timeout") &&
+               value.fetch("survivors") == counts.fetch("survived") &&
+               value.fetch("score") == covered
+          raise Error, "score history contains inconsistent counts"
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/html.rb

@@ -57,7 +57,7 @@ module Saboteur
           <title>saboteur report</title>
           <style>#{STYLE}</style></head><body>
           <h1>saboteur report</h1>
-          #{summary(report, data)}#{warnings(data[:warnings])}#{skipped_subjects(data[:skippedSubjects])}
+          #{summary(report, data)}#{inline_suppressions(report)}#{warnings(data[:warnings])}#{skipped_subjects(data[:skippedSubjects])}
           <h2>Files</h2>
           #{data[:files].map { |file, entry| file_section(file, entry, names, results) }.join("\n")}
           </body></html>
@@ -66,6 +66,17 @@ module Saboteur
 
       private
 
+      def inline_suppressions(report)
+        return "" if report.inline_suppressions.empty?
+
+        items = report.inline_suppressions.map do |entry|
+          path = entry[:file].delete_prefix("#{report.root}/")
+          "<li>#{escape(path)}:#{entry[:line]} #{escape(entry[:subject])} " \
+            "#{escape(entry[:operator])} <code>#{escape(entry[:digest])}</code>: #{escape(entry[:reason])}</li>"
+        end
+        "<h2>Inline suppressions (#{items.size}, outside the score)</h2><ul>#{items.join}</ul>"
+      end
+
       def summary(report, data)
         seed = data.dig(:config, :seed)
         seed_note = seed ? ", seed #{seed}" : ""

data/lib/saboteur/reporter/mutation_text.rb

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # The original and replacement text of one mutant, and the line it
+    # changes, for compact one-line output.
+    module MutationText
+      module_function
+
+      def line(result)
+        result.subject.line_of(sorted_edits(result).first.start_byte)
+      end
+
+      def original(result)
+        join(result) { |edit| result.subject.file_source.byteslice(edit.start_byte, edit.end_byte - edit.start_byte) }
+      end
+
+      def replacement(result)
+        join(result, &:replacement)
+      end
+
+      def sorted_edits(result)
+        result.mutation.edits.sort_by(&:start_byte)
+      end
+
+      # Whole-body mutants carry a long text; one line keeps the output compact.
+      def join(result, &pick)
+        text = sorted_edits(result).map { |edit| pick.call(edit).to_s.dup.force_encoding(Encoding::UTF_8).scrub }
+                                   .join(" | ")
+        flat = text.gsub(/\s*\n\s*/, " ").strip
+        flat.length > 60 ? "#{flat[0, 57]}..." : flat
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/next_steps.rb

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # The footer under a run that left survivors: how to look at one, how to
+    # accept one, and how to hand the run to an agent. Silent when nothing
+    # survived, so a clean run stays short.
+    class NextSteps
+      def initialize(out, palette)
+        @out = out
+        @palette = palette
+      end
+
+      def call(report)
+        survivor = report.unignored_survivors.first
+        return unless survivor
+
+        @out.puts "\n#{@palette.paint(:bold, 'Next steps:')}"
+        seed = " --seed #{report.seed}" if report.seed
+        @out.puts "  replay one survivor: saboteur run --id #{survivor.digest}#{seed}"
+        @out.puts "    (add this run's own --config, --since, --subject, --test and source options)"
+        @out.puts "  accept an equivalent one: add to your ignore file (c.ignore_file, default #{Config::IGNORE_FILE}):"
+        entry = %(i.mutation "#{survivor.digest}", subject: "#{survivor.subject.id}", reason: "why it is equivalent")
+        @out.puts "    #{entry}"
+        @out.puts "  let an agent close the gaps: saboteur run --agent, with the same options"
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/palette.rb

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # Wraps text in ANSI colour codes when colour is on, and returns it
+    # unchanged when it is off. Colour is on only when asked for or when the
+    # output is a terminal and NO_COLOR is not set (https://no-color.org).
+    class Palette
+      CODES = { red: 31, green: 32, yellow: 33, magenta: 35, cyan: 36, dim: 2, bold: 1 }.freeze
+
+      # mode: :auto, :always or :never.
+      def self.for(out, mode: :auto, environment: ENV)
+        enabled = case mode
+                  when :always then true
+                  when :never then false
+                  else out.respond_to?(:tty?) && out.tty? && environment["NO_COLOR"].to_s.empty?
+                  end
+        new(enabled: enabled)
+      end
+
+      def initialize(enabled:)
+        @enabled = enabled
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def paint(color, text)
+        return text unless @enabled
+
+        "\e[#{CODES.fetch(color)}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/score_history.rb

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "digest"
+require "fileutils"
+require_relative "agent_incomplete"
+require_relative "history_record"
+
+module Saboteur
+  module Reporter
+    # Opt-in append-only score observations, not a baseline or a CI gate.
+    class ScoreHistory
+      DIFFERENT_RUN = "score history: change unavailable (different selection/inventory or incomplete run)"
+      DIFFERENT_POLICY = "score history: change unavailable (different record version or operator policy)"
+      MISSING_SCORE = "score history: change unavailable (no tested mutants)"
+      MAX_RECORD_BYTES = 64 * 1024
+      OPEN_FLAGS = File::RDWR | File::CREAT | File::NONBLOCK | File::NOFOLLOW
+
+      def initialize(path)
+        @path = path
+      end
+
+      def append(report, head:, scope:)
+        record = build(report, head, scope)
+        HistoryRecord.validate(record)
+        line = "#{JSON.generate(record)}\n"
+        raise Error, "score history record exceeds byte limit" if line.bytesize > MAX_RECORD_BYTES
+
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, OPEN_FLAGS, 0o600) do |file|
+          regular_file(file)
+          lock(file, File::LOCK_EX)
+
+          previous = previous_record(file)
+          file.seek(0, IO::SEEK_END)
+          file.write(line)
+          file.flush
+          change(previous, record)
+        end
+      rescue SystemCallError, IOError, JSON::ParserError, KeyError, TypeError => e
+        raise Error, "score history was not recorded: #{e.message}"
+      end
+
+      def validate_existing
+        return unless File.exist?(@path) || File.symlink?(@path)
+
+        File.open(@path, File::RDONLY | File::NONBLOCK | File::NOFOLLOW) do |file|
+          regular_file(file)
+          lock(file, File::LOCK_SH)
+
+          previous_record(file)
+        end
+      rescue SystemCallError, IOError => e
+        raise Error, "score history cannot be read: #{e.message}"
+      end
+
+      private
+
+      def build(report, head, scope)
+        { "version" => 2, "date" => Time.now.utc.iso8601, "commit" => head,
+          "selection" => Digest::SHA256.hexdigest(JSON.generate(scope.sort_by { |key, _| key.to_s }.to_h)),
+          "inventory" => Digest::SHA256.hexdigest(JSON.generate(report.results.map(&:digest).sort)),
+          "score" => overall_score(report), "coveredScore" => report.score,
+          "counts" => report.counts.transform_keys(&:to_s),
+          "breakdown" => report.score_breakdown.to_h.transform_keys(&:to_s),
+          "incomplete" => incompleteness(report), "operatorPolicy" => report.operator_policy }
+      end
+
+      def overall_score(report)
+        score = report.score_breakdown
+        missing = report.results.count { |result| result.status == :skipped && result.reason == "no coverage" }
+        denominator = score.tested + missing
+        denominator.zero? ? nil : score.detected.fdiv(denominator)
+      end
+
+      def incompleteness(report)
+        reasons = Agent::Incomplete.reasons(report).map { |reason| reason[:reason] }
+        reasons << "baseline_incomplete" if report.run_evidence && !report.run_evidence["complete"]
+        reasons << "omissions" unless report.omissions.empty?
+        reasons.uniq
+      end
+
+      def lock(file, mode)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 2
+        until file.flock(mode | File::LOCK_NB)
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise Error,
+                  "score history lock was not acquired"
+          end
+
+          sleep 0.01
+        end
+      end
+
+      def regular_file(file)
+        raise Error, "score history must be a regular file" unless file.stat.file?
+      end
+
+      def previous_record(file)
+        while (line = file.gets(MAX_RECORD_BYTES + 1))
+          raise Error, "score history record exceeds byte limit" if line.bytesize > MAX_RECORD_BYTES
+          raise Error, "score history contains a truncated record" unless line.end_with?("\n")
+
+          previous = HistoryRecord.parse(line)
+        end
+        previous
+      end
+
+      # Only one record version and one non-null operator policy compare:
+      # scores never mix across v1/v2 or across policy configurations.
+      # A non-null previous policy forces a non-null equal current one, so
+      # only the previous record needs the null guard.
+      def comparable_policy?(previous, current)
+        previous["version"] == current["version"] &&
+          !previous["operatorPolicy"].nil? &&
+          previous["operatorPolicy"] == current["operatorPolicy"]
+      end
+
+      def change(previous, current)
+        return "score history: first record" unless previous
+        return DIFFERENT_RUN unless
+          previous["selection"] == current["selection"] && previous["inventory"] == current["inventory"] &&
+          previous["incomplete"].empty? && current["incomplete"].empty?
+        return DIFFERENT_POLICY unless comparable_policy?(previous, current)
+        return MISSING_SCORE if
+          previous["coveredScore"].nil? || current["coveredScore"].nil?
+
+        delta = (current["coveredScore"] - previous["coveredScore"]) * 100
+        format("score history: covered score change %+.2f percentage points (same configured selection)", delta)
+      end
+    end
+  end
+end