mutineer 1.4.0 → 1.6.0

data/lib/mutineer/reporter.rb

@@ -25,9 +25,24 @@ module Mutineer
     # workflow, so one bad mutant never fails the gate on its own, at any size.
     BROKEN_FLOOR = 1
 
-    def initialize(aggregate, source_map)
+    # The JSON report's `schema_version` (see docs/json-schema.md).
+    SCHEMA_VERSION = "1.7"
+
+    # The warning both matrix renderers give under the redundant tests.
+    MATRIX_REDUNDANT_NOTE = "Delete redundant tests one at a time: two of them can be the only killers of one mutant."
+
+    # How many blind or redundant tests the human report lists before it points
+    # to `--format json` for the rest.
+    MATRIX_LIST_LIMIT = 20
+
+    # @param aggregate [Mutineer::AggregateResult] the run's results.
+    # @param source_map [Hash{String => String}] source file path => source text.
+    # @param matrix [Mutineer::KillMatrix, nil] the kill matrix of a `--matrix`
+    #   run; nil leaves every format exactly as it is without the flag.
+    def initialize(aggregate, source_map, matrix: nil)
       @agg = aggregate
       @source_map = source_map
+      @matrix = matrix
     end
 
     # Single entry point. Branches on `format` ("human" | "json" | "html") and
@@ -96,6 +111,7 @@ module Mutineer
       per_source(out)
 
       survivors(out)
+      matrix_section(out) if @matrix
       verdict(out, threshold) if threshold && threshold.positive?
     end
 
@@ -146,11 +162,13 @@ module Mutineer
       score = @agg.mutation_score
 
       doc = {
-        schema_version: "1.4",
+        schema_version: SCHEMA_VERSION,
         summary: {
           total: @agg.total, killed: killed, survived: survived,
           no_coverage: @agg.no_coverage_count,
           uncapturable: @agg.uncapturable_count,
+          unplaceable: @agg.unplaceable_count,
+          ran_at_load: @agg.ran_at_load_count,
           skipped_invalid: @agg.skipped_invalid_count,
           errored: @agg.errored_count, timeout: @agg.timeout_count,
           ignored: @agg.ignored_count,
@@ -172,17 +190,24 @@ module Mutineer
         },
         survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
                        .sort_by { |h| [h[:file], h[:line], h[:operator]] },
-        no_coverage: @agg.results.select(&:no_coverage?).map { |r| no_coverage_json(r) }
-                         .sort_by { |h| [h[:file], h[:line]] },
+        # id extends the key to a total order: several mutants share a line.
+        no_coverage: @agg.results.select(&:no_coverage?).map { |r| mutant_json(r) }
+                         .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
         # Same shape as no_coverage; additive key.
-        uncapturable: @agg.results.select(&:uncapturable?).map { |r| no_coverage_json(r) }
-                          .sort_by { |h| [h[:file], h[:line]] },
+        uncapturable: @agg.results.select(&:uncapturable?).map { |r| mutant_json(r) }
+                          .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
+        # Additive (1.7): owner-unknown mutants redefine did not run. Not in no_verdict.
+        unplaceable: @agg.results.select(&:unplaceable?).map { |r| mutant_json(r) }
+                         .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
+        # Additive (1.7, #187): mutants on a line that ran at load. Not in no_verdict.
+        ran_at_load: @agg.results.select(&:ran_at_load?).map { |r| mutant_json(r) }
+                         .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
         # Every mutant that was attempted and produced no verdict, whatever the
         # reason — the set the --threshold completeness gate counts. Named for the
         # condition rather than one status, because summary.errored means :error
         # alone and a key that reconciled with neither would be worse. `details`
         # carries the cause where there is one. Uncapturable mutants also appear in
-        # uncapturable[]; that key keeps its lean shape for existing consumers.
+        # uncapturable[], which stays for consumers that already read it.
         # to_s/to_i because a pre-fork failure has no subject, so its file and line
         # are null and would not compare against a real entry. id and status extend
         # the key to a total order: these entries collide on (file, line) far more
@@ -195,13 +220,15 @@ module Mutineer
         # Equivalent mutants the user suppressed: emitted with their stable id so
         # the user can audit what is silenced (and copy ids for survivors they
         # want to add). Excluded from the score; never in `survivors`.
-        ignored: @agg.results.select(&:ignored?).map { |r| ignored_json(r) }
-                     .sort_by { |h| [h[:file], h[:line], h[:operator]] },
+        ignored: @agg.results.select(&:ignored?).map { |r| mutant_json(r) }
+                     .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
         # Per-source breakdown (additive; baseline consumes it). Sorted by file so
         # output is byte-stable. Reuses AggregateResult via by_source.
         per_source: @agg.by_source.map { |file, agg| per_source_json(file, agg) }
                         .sort_by { |h| h[:file] }
       }
+      # Additive (1.5): the kill matrix, present only with --matrix.
+      doc[:matrix] = matrix_json if @matrix
       # Additive baseline-delta block, present only with --baseline. Existing
       # consumers ignore the extra key; it does not move schema_version on its own.
       doc[:baseline] = baseline_json(baseline) if baseline
@@ -257,6 +284,7 @@ module Mutineer
         #{summary_html}
         #{per_source_html(per_source)}
         #{survivors_html(survivors)}
+        #{matrix_html}
         </body>
         </html>
       HTML
@@ -267,9 +295,10 @@ module Mutineer
       counts = {
         "total" => @agg.total, "killed" => @agg.killed_count,
         "survived" => @agg.survived_count, "no_coverage" => @agg.no_coverage_count,
-        "uncapturable" => @agg.uncapturable_count, "ignored" => @agg.ignored_count,
+        "uncapturable" => @agg.uncapturable_count, "unplaceable" => @agg.unplaceable_count,
+        "ran_at_load" => @agg.ran_at_load_count, "ignored" => @agg.ignored_count,
         "skipped" => @agg.skipped_invalid_count,
-        "errored" => @agg.errored_count + @agg.timeout_count
+        "errored" => @agg.errored_count, "timeout" => @agg.timeout_count
       }
       spans = counts.map { |k, v| "<span><strong>#{v}</strong> #{esc(k)}</span>" }.join("\n  ")
       "<div class=\"counts\">\n  #{spans}\n</div>"
@@ -316,11 +345,191 @@ module Mutineer
       "<h2>Surviving Mutants</h2>\n#{cards}"
     end
 
+    # The kill-matrix section of the HTML report: the counts, then the blind and
+    # redundant tests. Empty without --matrix.
+    #
+    # @api private
+    # @return [String] HTML.
+    def matrix_html
+      return "" unless @matrix
+
+      lists = { "Blind tests" => @matrix.blind, "Redundant tests" => @matrix.redundant }.map do |title, tests|
+        items = tests.map { |test| "<li><span class=\"id\">#{esc(test[0])}</span> #{esc(test_label(test))}</li>" }
+        body = items.empty? ? "<p>None.</p>" : "<ul>\n#{items.join("\n")}\n</ul>"
+        "<h3>#{esc(title)} (#{tests.size})</h3>\n#{body}"
+      end
+      note = @matrix.complete? ? "" : "\n<p>#{esc(matrix_incomplete_note)}</p>\n#{matrix_incomplete_html}"
+      delete = @matrix.redundant.empty? ? "" : "\n<p>#{esc(MATRIX_REDUNDANT_NOTE)}</p>"
+      "<h2>Kill matrix</h2>\n<p>#{esc(matrix_counts_line)}</p>#{note}\n#{lists.join("\n")}#{delete}"
+    end
+
+    # Every incomplete row of the HTML kill-matrix section.
+    #
+    # @api private
+    # @return [String] HTML.
+    def matrix_incomplete_html
+      items = @matrix.incomplete_rows.map { |r| "<li>#{esc(matrix_row_label(r))}</li>" }
+      "<h3>Incomplete rows (#{items.size})</h3>\n<ul>\n#{items.join("\n")}\n</ul>"
+    end
+
+    # The JSON `matrix` block: every test with its kill count, one row per
+    # mutant that ran (its killers as indexes into `tests`), and the blind and
+    # redundant tests. Rows sort like survivors, then by id, so output is
+    # byte-stable regardless of --jobs.
+    #
+    # @api private
+    # @return [Hash] the matrix JSON object.
+    def matrix_json
+      tests = @matrix.tests
+      index = tests.each_with_index.to_h
+      {
+        complete: @matrix.complete?,
+        tests: tests.map { |test| test_json(test).merge(kills: @matrix.kill_count(test)) },
+        mutants: @matrix.rows.map { |r| matrix_row_json(r, index) }
+                        .sort_by { |h| [h[:file].to_s, h[:line].to_i, h[:operator].to_s, h[:id].to_s] },
+        blind: @matrix.blind.map { |test| test_json(test) },
+        redundant: @matrix.redundant.map { |test| test_json(test) }
+      }
+    end
+
+    # One test as JSON: its file, display name and id.
+    #
+    # @api private
+    # @param test [Array(String, String, String)] a `[file, name, id]` test.
+    # @return [Hash]
+    def test_json(test)
+      file, name, id = test
+      { file: file, name: name, id: id }
+    end
+
+    # A test's name for people: the display name, plus the id when it differs
+    # (an RSpec example id, which tells apart examples that share a name and
+    # runs exactly that example with `rspec`).
+    #
+    # @api private
+    # @param test [Array(String, String, String)] a `[file, name, id]` test.
+    # @return [String]
+    def test_label(test)
+      _file, name, id = test
+      id == name ? name : "#{name} (#{id})"
+    end
+
+    # One mutant's row under `matrix.mutants`.
+    #
+    # @api private
+    # @param result [Mutineer::Result] a result with a {Kills} row.
+    # @param index [Hash{Array => Integer}] test => its index in `matrix.tests`.
+    # @return [Hash] the row JSON object.
+    def matrix_row_json(result, index)
+      file = result.subject&.file
+      kills = result.kills
+      {
+        subject: result.subject&.qualified_name, file: file, line: result_line(result),
+        operator: result.mutation&.operator&.to_s, id: result.id, status: result.status.to_s,
+        killed_by: kills.killed_by.map { |test| index.fetch(test) }.sort,
+        ran: kills.ran.size, complete: kills.complete
+      }
+    end
+
+    # The kill-matrix section of the human report.
+    #
+    # @api private
+    # @param out [IO] output stream.
+    # @return [void]
+    def matrix_section(out)
+      out.puts
+      out.puts "Kill matrix"
+      out.puts "-----------"
+      out.puts matrix_counts_line
+      matrix_incomplete_section(out) unless @matrix.complete?
+      matrix_list(out, "Blind tests (ran, killed no mutant)", @matrix.blind)
+      matrix_list(out, "Redundant tests (each mutant they kill has another killer)", @matrix.redundant)
+      return if @matrix.redundant.empty?
+
+      out.puts MATRIX_REDUNDANT_NOTE
+    end
+
+    # The human report's warning about incomplete rows, with the first
+    # {MATRIX_LIST_LIMIT} of them named.
+    #
+    # @api private
+    # @param out [IO] output stream.
+    # @return [void]
+    def matrix_incomplete_section(out)
+      rows = @matrix.incomplete_rows
+      out.puts matrix_incomplete_note
+      rows.first(MATRIX_LIST_LIMIT).each { |r| out.puts "  #{printable(matrix_row_label(r))}" }
+      rest = rows.size - MATRIX_LIST_LIMIT
+      out.puts "  and #{rest} more" if rest.positive?
+      out.puts "The HTML and JSON reports list every incomplete row (JSON: matrix.mutants with complete: false)."
+    end
+
+    # A row's label: subject, place, operator, status and id.
+    #
+    # @api private
+    # @param result [Mutineer::Result] a result with a {Kills} row.
+    # @return [String]
+    def matrix_row_label(result)
+      place = [result.subject&.file, result_line(result)].compact.join(":")
+      [result.subject&.qualified_name, ("(#{place})" unless place.empty?), result.mutation&.operator,
+       result.status, result.id].compact.join(" ")
+    end
+
+    # The 1-based line of a result's mutation, or nil without one (a pre-fork
+    # failure has no subject or mutation).
+    #
+    # @api private
+    # @param result [Mutineer::Result] any result.
+    # @return [Integer, nil]
+    def result_line(result)
+      file = result.subject&.file
+      return unless result.mutation && file
+
+      source = @source_map[file] || File.read(file)
+      source.byteslice(0, result.mutation.start_offset).count("\n") + 1
+    end
+
+    # One titled list of tests in the human kill-matrix section, cut at
+    # {MATRIX_LIST_LIMIT}; the JSON report has the whole list.
+    #
+    # @api private
+    # @param out [IO] output stream.
+    # @param title [String] the list's title.
+    # @param tests [Array<Array(String, String, String)>] `[file, name, id]` tests.
+    # @return [void]
+    def matrix_list(out, title, tests)
+      out.puts
+      out.puts "#{title}: #{tests.size}"
+      tests.first(MATRIX_LIST_LIMIT).each { |test| out.puts "  #{printable(test[0])}  #{printable(test_label(test))}" }
+      rest = tests.size - MATRIX_LIST_LIMIT
+      out.puts "  and #{rest} more; see --format json" if rest.positive?
+    end
+
+    # The counts sentence both matrix renderers open with.
+    #
+    # @api private
+    # @return [String]
+    def matrix_counts_line
+      "#{@matrix.tests.size} tests ran against #{@matrix.rows.size} mutants " \
+        "(every test in each mutant's covering files): " \
+        "#{@matrix.blind.size} blind, #{@matrix.redundant.size} redundant."
+    end
+
+    # The warning both matrix renderers give when a row is incomplete.
+    #
+    # @api private
+    # @return [String]
+    def matrix_incomplete_note
+      "#{@matrix.incomplete_rows.size} mutants could not be verified as complete (a timeout, an error, " \
+        "an exit, an interrupt or a broken stream), so a blind test may have killed one of them. " \
+        "Do not delete a blind test until these rows are complete:"
+    end
+
     # HTML-escapes any text destined for the document (stdlib CGI).
     def esc(text) = CGI.escapeHTML(text.to_s)
 
     # The same delta facts the human report prints, for dashboards. new_survivors
-    # reuse the ignored_json shape (subject/file/line/operator/token/id) and sort
+    # reuse the mutant_json shape (subject/file/line/operator/token/id) and sort
     # byte-stably so output does not depend on --jobs finish order.
     def baseline_json(delta)
       {
@@ -332,8 +541,8 @@ module Mutineer
         # a diff-scoped side), so a consumer knows not to render the two scores
         # as a comparison.
         score_comparable: delta.score_comparable,
-        new_survivors: delta.new_survivors.map { |r| ignored_json(r) }
-                            .sort_by { |h| [h[:file], h[:line], h[:operator]] },
+        new_survivors: delta.new_survivors.map { |r| mutant_json(r) }
+                            .sort_by { |h| [h[:file], h[:line], h[:operator], h[:id].to_s] },
         fixed_survivors: delta.fixed_survivors.map do |h|
           { subject: h["subject"], file: h["file"], line: h["line"],
             operator: h["operator"], id: h["id"] }
@@ -365,8 +574,11 @@ module Mutineer
       file = result.subject.file
       source = @source_map[file] || File.read(file)
       start_line, original_block, mutated_block, token = diff_for(m, source)
-      minus = original_block.each_line.map { |l| "-#{l.chomp}" }.join("\n")
-      plus  = mutated_block.each_line.map { |l| "+#{l.chomp}" }.join("\n")
+      # A block at the end of the file has no newline after it; elsewhere the
+      # file's next byte is one. Each side's own text decides its marker.
+      at_eof = source.byteindex("\n", m.end_offset).nil?
+      old_lines = side_lines(original_block, at_eof)
+      new_lines = side_lines(mutated_block, at_eof)
       {
         subject: result.subject.qualified_name,
         file: file,
@@ -376,12 +588,53 @@ module Mutineer
         # user can paste it straight into .mutineer.yml `ignore:`.
         id: result.id,
         token: token,
-        diff: "--- a/#{file}\n+++ b/#{file}\n@@ -#{start_line} +#{start_line} @@\n#{minus}\n#{plus}\n"
+        diff: "--- a/#{file}\n+++ b/#{file}\n" \
+              "@@ -#{hunk_range(start_line, old_lines)} +#{hunk_range(start_line, new_lines)} @@\n" \
+              "#{diff_body("-", old_lines)}#{diff_body("+", new_lines)}"
       }
     end
 
-    # An entry under the JSON `ignored:` key: what the user already suppressed.
-    def ignored_json(result)
+    # One side of the diff as the file holds it: the {#diff_for} block plus the
+    # newline that follows it, unless the block ends the file. Each line keeps
+    # its own ending, so a CRLF line keeps its "\r" and a last line with no
+    # newline is told apart from one with a newline.
+    #
+    # @api private
+    # @param block [String] the block's text.
+    # @param at_eof [Boolean] no newline follows the block in the file.
+    # @return [Array<String>] its lines, with their endings.
+    def side_lines(block, at_eof)
+      (at_eof ? block : "#{block}\n").lines
+    end
+
+    # The `-` or `+` lines of one side. A line with no newline is the file's
+    # last, so it gets the unified diff's no-newline marker (#106).
+    #
+    # @api private
+    # @param sign [String] "-" or "+".
+    # @param lines [Array<String>] the side's lines, with their endings.
+    # @return [String]
+    def diff_body(sign, lines)
+      lines.map { |l| l.end_with?("\n") ? "#{sign}#{l}" : "#{sign}#{l}\n\\n" }.join
+    end
+
+    # One side of a unified diff hunk header: `start` for one line, else
+    # `start,count`; an empty side is `start-1,0` (#106).
+    #
+    # @api private
+    # @param start_line [Integer] 1-based first line of the block.
+    # @param lines [Array<String>] the block's lines.
+    # @return [String] the range, e.g. "3", "3,2" or "2,0".
+    def hunk_range(start_line, lines)
+      return "#{start_line - 1},0" if lines.empty? # an empty side names the line before it
+
+      lines.size == 1 ? start_line.to_s : "#{start_line},#{lines.size}"
+    end
+
+    # The fields that name one mutant, for the lists that point at mutants:
+    # `no_coverage`, `uncapturable`, `unplaceable`, `ran_at_load`, `ignored` and
+    # `baseline.new_survivors`.
+    def mutant_json(result)
       m = result.mutation
       file = result.subject.file
       source = @source_map[file] || File.read(file)
@@ -415,22 +668,6 @@ module Mutineer
       [start_line, original_block, mutated_block, token]
     end
 
-    # Builds no-coverage JSON.
-    #
-    # @api private
-    # @param result [Mutineer::Result] result object.
-    # @return [Hash] no-coverage JSON object.
-    def no_coverage_json(result)
-      m = result.mutation
-      file = result.subject.file
-      source = @source_map[file] || File.read(file)
-      {
-        subject: result.subject.qualified_name,
-        file: file,
-        line: source.byteslice(0, m.start_offset).count("\n") + 1
-      }
-    end
-
     # An entry under the JSON `no_verdict:` key: an attempted mutant with no verdict.
     # A pre-fork failure has no subject or mutation attached, so those degrade to
     # nulls rather than dropping the entry — the count must still reconcile with
@@ -440,16 +677,10 @@ module Mutineer
     # @param result [Mutineer::Result] an errored or timed-out result.
     # @return [Hash] no-verdict JSON object.
     def no_verdict_json(result)
-      file = result.subject&.file
-      line =
-        if result.mutation && file
-          source = @source_map[file] || File.read(file)
-          source.byteslice(0, result.mutation.start_offset).count("\n") + 1
-        end
       {
         subject: result.subject&.qualified_name,
-        file: file,
-        line: line,
+        file: result.subject&.file,
+        line: result_line(result),
         id: result.id,
         status: result.status.to_s,
         details: result.details
@@ -465,10 +696,16 @@ module Mutineer
       out.puts "-------"
       out.puts format("Total:        %-6d  Killed:        %d", @agg.total, @agg.killed_count)
       out.puts format("Survived:     %-6d  No coverage:   %d", @agg.survived_count, @agg.no_coverage_count)
-      out.puts format("Skipped:      %-6d  Errored:       %d", @agg.skipped_invalid_count,
-                      @agg.errored_count + @agg.timeout_count)
+      out.puts format("Skipped:      %-6d  Errored:       %d", @agg.skipped_invalid_count, @agg.errored_count)
+      out.puts format("Timeout:      %-6d  (over the per-mutant time limit)", @agg.timeout_count)
       # A broken harness, not a coverage gap: report it distinctly from No coverage.
       out.puts format("Uncapturable: %-6d  (tests failed to run)", @agg.uncapturable_count)
+      # Not broken: redefine has no named class to load these onto; reload runs them.
+      out.puts format("Unplaceable:  %-6d  (class cannot be named statically; --strategy reload runs these)",
+                      @agg.unplaceable_count)
+      # Not a verdict: the line ran before the mutant was applied (#187).
+      out.puts format("Ran at load:  %-6d  (ran while the app or class loaded; mutineer cannot re-run that; " \
+                      "verify with --test-command)", @agg.ran_at_load_count)
       # Equivalent mutants the user suppressed; excluded from the denominator.
       out.puts format("Ignored:      %-6d  (equivalent, suppressed)", @agg.ignored_count)
     end
@@ -481,8 +718,9 @@ module Mutineer
     def score_line(out, err)
       score = @agg.mutation_score
       excluded = "#{@agg.no_coverage_count} no-coverage, #{@agg.uncapturable_count} uncapturable, " \
+                 "#{@agg.unplaceable_count} unplaceable, #{@agg.ran_at_load_count} ran at load, " \
                  "#{@agg.skipped_invalid_count} skipped, " \
-                 "#{@agg.errored_count + @agg.timeout_count} errored, " \
+                 "#{@agg.errored_count} errored, #{@agg.timeout_count} timeout, " \
                  "#{@agg.ignored_count} ignored excluded"
       if score.nil?
         out.puts "Mutation score: N/A  (no covered mutants)"
@@ -581,7 +819,7 @@ module Mutineer
       sources.sort.each do |file, agg|
         score = agg.mutation_score
         out.puts format("%s  %s  (%d killed / %d survived / %d no-cov)",
-                        file, score.nil? ? "N/A" : "#{score}%",
+                        printable(file), score.nil? ? "N/A" : "#{score}%",
                         agg.killed_count, agg.survived_count, agg.no_coverage_count)
       end
     end
@@ -600,7 +838,7 @@ module Mutineer
         file = r.subject.file
         source = @source_map[file] || File.read(file)
         line, = diff_for(r.mutation, source)
-        out.puts "  + #{r.subject.qualified_name} (#{file}:#{line}) #{r.mutation.operator}"
+        out.puts "  + #{printable(r.subject.qualified_name)} (#{printable(file)}:#{line}) #{r.mutation.operator}"
       end
       out.puts "score dropped #{delta.score_before}% -> #{delta.score_after}%" if delta.score_drop
       # An OK verdict must not imply a check that never ran: say when the score
@@ -622,7 +860,7 @@ module Mutineer
       out.puts "-----------------"
       mutants.group_by { |r| r.subject.file }.sort.each do |file, group|
         out.puts
-        out.puts file
+        out.puts printable(file)
         group.sort_by { |r| r.mutation.start_offset }.each { |r| survivor(out, file, r) }
       end
     end
@@ -638,10 +876,25 @@ module Mutineer
       source = @source_map[file] || File.read(file)
       start_line, original_block, mutated_block, token = diff_for(m, source)
 
-      out.puts "  #{result.subject.qualified_name} (#{File.basename(file)}:#{start_line})"
-      out.puts "  Operator: #{m.operator}  (#{token} -> #{m.replacement})"
-      original_block.each_line { |l| out.puts "  - #{l.chomp}" }
-      mutated_block.each_line  { |l| out.puts "  + #{l.chomp}" }
+      out.puts "  #{printable(result.subject.qualified_name)} (#{printable(File.basename(file))}:#{start_line})"
+      out.puts "  Operator: #{m.operator}  (#{printable(token)} -> #{printable(m.replacement)})"
+      original_block.each_line { |l| out.puts "  - #{printable(l.chomp)}" }
+      mutated_block.each_line  { |l| out.puts "  + #{printable(l.chomp)}" }
+    end
+
+    # Source text, a method name or a file path made safe for a terminal (#163):
+    # each control character except tab becomes its Ruby escape (ESC prints as
+    # `\e`). The text is read as UTF-8 whatever the locale, and each byte that is
+    # not valid UTF-8 (a Latin-1 source, say) prints as `\xNN`, so nothing is
+    # lost and the regex never raises. JSON and HTML escape on their own.
+    #
+    # @api private
+    # @param text [String] source text.
+    # @return [String] the text with control characters and invalid bytes escaped.
+    def printable(text)
+      text.dup.force_encoding(Encoding::UTF_8)
+          .scrub { |bytes| bytes.unpack("C*").map { |b| format("\\x%02X", b) }.join }
+          .gsub(/[[:cntrl:]&&[^\t]]/) { |c| c.dump[1..-2] }
     end
 
     # Writes the final verdict line.

data/lib/mutineer/result.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # Immutable outcome of running one mutant. Eight distinct states:
+  # Immutable outcome of running one mutant. Ten distinct states:
   #   killed       - a test failed/errored, so the mutation was caught.
   #   survived     - every test passed, so the mutation went undetected.
   #   error        - the child crashed (unhandled exception): exit status 2.
@@ -13,6 +13,19 @@ module Mutineer
   #                  like no_coverage, but reported separately: it signals a
   #                  broken harness (a test that failed to run), not a genuine
   #                  coverage gap.
+  #   unplaceable  - under `--strategy redefine`, the method belongs to a class
+  #                  or module that cannot be named statically, so it has no
+  #                  owner to be loaded onto and is not run. Excluded from the
+  #                  denominator and, unlike uncapturable, from the
+  #                  no-verdict gate: nothing is broken. `--strategy reload`
+  #                  runs these mutants.
+  #   ran_at_load  - the mutated line ran while the app booted or its class
+  #                  loaded. That run happened before the mutant was applied,
+  #                  so a test can check a value the original code computed.
+  #                  A survivor on such a line, and a line that ran only at
+  #                  load, get this status; a kill stays killed. Excluded from
+  #                  the denominator and from the no-verdict gate, like
+  #                  unplaceable. `--test-command` verifies these mutants.
   #   ignored      - a known-equivalent mutant the user suppressed, via an
   #                  inline `# mutineer:disable-line` comment or a
   #                  `.mutineer.yml` `ignore:` id. A pre-fork classification
@@ -21,8 +34,9 @@ module Mutineer
   #
   # `error` and `skipped` are deliberately distinct: skipped is a pre-fork
   # validity failure (counted separately by the reporter), error is a runtime
-  # crash. Never conflate them via `details` string parsing. `no_coverage` and
-  # `uncapturable` are pre-fork selection results: both excluded from the score
+  # crash. Never conflate them via `details` string parsing. `no_coverage`,
+  # `uncapturable` and `unplaceable` are pre-fork results, and `ran_at_load` is
+  # pre-fork or a reclassified survivor: all excluded from the score
   # denominator.
   #
   # `subject`, `mutation`, and `id` are nil when the Result is built by
@@ -30,7 +44,28 @@ module Mutineer
   # them afterwards via `result.with(subject:, mutation:, id:)` so the Reporter
   # can render survivor diffs and emit the id. `id` is the content-based
   # MutantId (it includes the project-relative file path).
-  Result = Data.define(:status, :details, :subject, :mutation, :id) do
+  #
+  # `kills` is nil except in a `--matrix` run, where a mutant that was forked
+  # carries the {Kills} its child reported. It annotates the verdict and never
+  # decides it.
+  #
+  # A Result crosses a process boundary only through WorkerPool's Marshal pipe,
+  # from a fork back to the process that forked it, so both ends always run the
+  # same code. Nothing persists a marshaled Result (reports, baselines and the
+  # coverage cache are JSON), so a new field needs no Marshal compatibility.
+  Result = Data.define(:status, :details, :subject, :mutation, :id, :kills) do
+    # Every field but `status` defaults to nil.
+    #
+    # @param status [Symbol] the outcome.
+    # @param details [String, nil] error or skip details.
+    # @param subject [Mutineer::Subject, nil] the mutated subject.
+    # @param mutation [Mutineer::Mutation, nil] the mutation.
+    # @param id [String, nil] the stable mutant id.
+    # @param kills [Mutineer::Kills, nil] the matrix row of a `--matrix` run.
+    def initialize(status:, details: nil, subject: nil, mutation: nil, id: nil, kills: nil)
+      super
+    end
+
     # Builds a killed result.
     #
     # @return [Mutineer::Result] killed result.
@@ -68,6 +103,16 @@ module Mutineer
     # @return [Mutineer::Result] uncapturable result.
     def self.uncapturable = new(status: :uncapturable, details: nil, subject: nil, mutation: nil, id: nil)
 
+    # Builds an unplaceable result.
+    #
+    # @return [Mutineer::Result] unplaceable result.
+    def self.unplaceable = new(status: :unplaceable, details: nil, subject: nil, mutation: nil, id: nil)
+
+    # Builds a ran_at_load result.
+    #
+    # @return [Mutineer::Result] ran-at-load result.
+    def self.ran_at_load = new(status: :ran_at_load, details: nil, subject: nil, mutation: nil, id: nil)
+
     # Builds an ignored result.
     #
     # @return [Mutineer::Result] ignored result.
@@ -87,14 +132,33 @@ module Mutineer
     def no_coverage?  = status == :no_coverage
     # @return [Boolean] true when the status is uncapturable.
     def uncapturable? = status == :uncapturable
+    # @return [Boolean] true when the status is unplaceable.
+    def unplaceable?  = status == :unplaceable
+    # @return [Boolean] true when the status is ran_at_load.
+    def ran_at_load?  = status == :ran_at_load
     # @return [Boolean] true when the status is ignored.
     def ignored?      = status == :ignored
 
   end
 
+  # One mutant's row of the kill matrix (`--matrix`): which tests killed it and
+  # which ran against it. A test is a `[file, name, id]` triple: the
+  # project-relative file that defines it, its name (`CalculatorTest#test_add`,
+  # or an RSpec example's full description), and an id that tells apart tests
+  # sharing a file and name (an RSpec example id; the name again for Minitest).
+  # File and id identify a test; the name is display data that a mutant can
+  # change. Both lists are sorted and unique, and `ran` includes the killers.
+  #
+  # `complete` is true when the child ran its whole suite and reported it
+  # cleanly (see Isolation.finish). It is false when the child timed out,
+  # errored or exited the process early, when the recorder never armed, when
+  # its lines arrived out of order, when Minitest returned after an Interrupt
+  # with tests unseen, or when the row does not agree with the verdict.
+  Kills = Data.define(:killed_by, :ran, :complete)
+
   # Aggregates a flat list of Results into counts, the mutation score, and the
   # surviving-mutant list. The score denominator is killed + survived ONLY:
-  # no-coverage, uncapturable, skipped (invalid), errored, timeout, and ignored
+  # no-coverage, uncapturable, unplaceable, ran-at-load, skipped (invalid), errored, timeout, and ignored
   # (equivalent-mutant suppression) are each excluded and surfaced separately,
   # so suppressing every survivor reaches 100%. An empty denominator yields a
   # nil score (rendered "N/A"), never 0.0, distinguishing "no testable mutants"
@@ -118,6 +182,10 @@ module Mutineer
     def no_coverage_count     = count(:no_coverage)
     # @return [Integer] uncapturable count.
     def uncapturable_count    = count(:uncapturable)
+    # @return [Integer] unplaceable count.
+    def unplaceable_count     = count(:unplaceable)
+    # @return [Integer] ran-at-load count.
+    def ran_at_load_count     = count(:ran_at_load)
     # @return [Integer] skipped-invalid count.
     def skipped_invalid_count = count(:skipped)
     # @return [Integer] errored count.