saboteur 0.2.0 → 0.3.0

data/lib/saboteur/reporter/html.rb

@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "cgi"
+require "fileutils"
+
+module Saboteur
+  module Reporter
+    # One self-contained HTML page: inline style, no script, no network. It is
+    # rendered from the same hash the JSON reporter writes (Stryker.build), so
+    # both reports list the same mutants with the same statuses. The scores can
+    # differ: the JSON schema counts NoCoverage as undetected, while this page
+    # shows Report#score, which leaves it out (see the "Covered mutation score"
+    # label on the page). The score note says what is and is not counted.
+    class Html
+      STYLE = <<~CSS
+        body{font:14px/1.5 system-ui,sans-serif;margin:1rem auto;max-width:72rem;padding:0 1rem;color:#1b1b1b}
+        h1,h2{margin:1.2em 0 .4em}table{border-collapse:collapse;width:100%;min-width:60rem}
+        th,td{border-bottom:1px solid #ddd;padding:.25rem .5rem;text-align:left;vertical-align:top;overflow-wrap:break-word}
+        td.fit{white-space:nowrap}td.wide{min-width:14rem}
+        th{background:#f4f4f4;font-size:12px;text-transform:uppercase}
+        .scroll{overflow-x:auto}.note{color:#555;font-size:12px}
+        .status{border-radius:3px;padding:0 .4rem;color:#fff;white-space:nowrap}
+        .Killed{background:#2e7d32}.Survived{background:#c62828}.Timeout{background:#b45309}
+        .RuntimeError{background:#6a1b9a}.NoCoverage{background:#455a64}.Ignored{background:#616161}
+        .Accepted{background:#8d6e63}
+        .warning{background:#fff8e1;border-left:4px solid #f9a825;margin:.3rem 0;padding:.3rem .6rem;overflow-wrap:anywhere}
+        code,pre{font-family:ui-monospace,monospace;font-size:13px}
+        pre{display:inline-block;vertical-align:top;margin:0;white-space:pre-wrap;overflow-wrap:anywhere}summary{cursor:pointer;font-weight:600;overflow-wrap:anywhere}
+      CSS
+
+      SCORE_FORMULA = "(killed + timeout) / (killed + survived + timeout)"
+
+      def initialize(path)
+        @path = path
+      end
+
+      def call(report)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, self.class.build(report))
+      end
+
+      def self.build(report)
+        new(nil).build(report)
+      end
+
+      def build(report)
+        data = Stryker.build(report)
+        names = test_names(data)
+        results = report.results.to_h do |result|
+          [[Stryker.relative(result.subject.file, report.root), result.digest], result]
+        end
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en"><head><meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>saboteur report</title>
+          <style>#{STYLE}</style></head><body>
+          <h1>saboteur report</h1>
+          #{summary(report, data)}#{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>
+        HTML
+      end
+
+      private
+
+      def summary(report, data)
+        seed = data.dig(:config, :seed)
+        seed_note = seed ? ", seed #{seed}" : ""
+        counts = data[:files].values.flat_map { |entry| entry[:mutants] }.map { |mutant| mutant[:status] }.tally
+        <<~HTML
+          <p><strong>Covered mutation score: #{score_text(report.score)}</strong>
+          (#{report.subjects.size} subjects, #{report.results.size} mutants, #{format('%.1f', report.wall_time)}s#{seed_note})</p>
+          <p class="note">Covered mutation score = #{SCORE_FORMULA}. NoCoverage, errors, resource limits and skipped
+          mutants are not counted. Survivors accepted on the ignore list stay in the denominator. It covers only the subjects of this run, not the whole project. A tool that reads the
+          Stryker JSON may show a different score, because the schema counts NoCoverage as undetected.</p>
+          <p class="note">Wide tables scroll sideways.</p>
+          <p>#{counts.map { |status, count| "#{status_label(status)} #{count}" }.join(' ')}</p>
+          <p>Survivors: #{report.unignored_survivors.size} to fix, #{report.survivors.size - report.unignored_survivors.size}
+          accepted on the ignore list (still shown as Survived, with the reason).</p>
+        HTML
+      end
+
+      def score_text(score)
+        score ? format("%.1f%%", score * 100) : "n/a"
+      end
+
+      def warnings(messages)
+        return "" if messages.empty?
+
+        items = messages.map { |message| %(<div class="warning">#{escape(message)}</div>) }
+        "<h2>Warnings</h2>\n#{items.join("\n")}"
+      end
+
+      def skipped_subjects(entries)
+        return "" if entries.empty?
+
+        rows = entries.map do |entry|
+          "<tr><td>#{escape(entry[:subject])}</td><td>#{escape(entry[:file])}:#{entry[:line]}</td>" \
+            "<td>#{escape(entry[:reason])}</td></tr>"
+        end
+        "<h2>Skipped subjects</h2>\n<div class=\"scroll\"><table><thead><tr><th>Subject</th><th>Location</th>" \
+          "<th>Reason</th></tr></thead>#{rows.join}</table></div>"
+      end
+
+      def test_names(data)
+        data[:testFiles].values.flat_map { |group| group[:tests] }.to_h { |test| [test[:id], test[:name]] }
+      end
+
+      def file_section(file, entry, names, results)
+        open = entry[:mutants].any? { |mutant| mutant[:status] == "Survived" } ? " open" : ""
+        ordered = entry[:mutants].sort_by { |mutant| position_key(mutant) }
+        rows = ordered.map { |mutant| mutant_row(mutant, names, results[[file, mutant[:id]]]) }
+        "<details#{open}><summary>#{escape(file)} (#{entry[:mutants].size} mutants)</summary>\n" \
+          "<div class=\"scroll\"><table><thead><tr><th>Location</th><th>Status</th><th>Operator</th><th>Change</th>" \
+          "<th>Id</th><th>Notes</th></tr></thead>\n#{rows.join("\n")}</table></div></details>"
+      end
+
+      def position_key(mutant)
+        start = mutant[:location][:start]
+        [start[:line], start[:column], mutant[:id]]
+      end
+
+      def mutant_row(mutant, names, result)
+        start = mutant[:location][:start]
+        tests = Array(mutant[:killedBy]).map { |id| names.fetch(id) }.join(", ")
+        notes = [mutant[:statusReason], tests.empty? ? nil : "killed by #{tests}"].compact.join("; ")
+        "<tr><td class=\"fit\">line #{start[:line]}, column #{start[:column]}</td><td>#{row_status(mutant,
+                                                                                                   result)}</td>" \
+          "<td>#{escape(mutant[:mutatorName])}</td><td class=\"wide\">#{change(mutant, result)}</td>" \
+          "<td class=\"fit\"><code>#{escape(mutant[:id])}</code></td><td class=\"wide\">#{escape(notes)}</td></tr>"
+      end
+
+      def row_status(mutant, result)
+        badge = status_label(mutant[:status])
+        # Only survivors are ever put on the ignore list.
+        result.ignored ? "#{badge} #{status_label('Accepted')}" : badge
+      end
+
+      # One edit shows the original text and its replacement. A mutant with
+      # several edits shows only the replacements, because one location cannot
+      # stand for all of them.
+      def change(mutant, result)
+        edits = result.mutation.edits
+        return "<pre>#{escape(mutant[:replacement])}</pre>" unless edits.size == 1
+
+        source = result.subject.file_source
+        edit = edits.first
+        original = source.byteslice(edit.start_byte, edit.end_byte - edit.start_byte).to_s
+        "<pre>#{escape(original.dup.force_encoding(Encoding::UTF_8).scrub)}</pre> becomes " \
+          "<pre>#{escape(edit.replacement)}</pre>"
+      end
+
+      def status_label(status)
+        %(<span class="status #{status}">#{status}</span>)
+      end
+
+      def escape(text)
+        CGI.escapeHTML(text.to_s)
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/replay.rb

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # A replay is an inspection too, regardless of the resulting verdict.
+    class Replay
+      def initialize(out)
+        @out = out
+      end
+
+      def call(report)
+        report.results.each do |result|
+          @out.puts "\nReplay: #{result.subject.id} #{result.mutation.operator} #{result.digest} (#{result.status})"
+          @out.puts result.diff(root: report.root)
+          @out.puts "Selected tests:"
+          result.covered_by.each { |name| @out.puts "  #{name}" }
+          @out.puts "  none" if result.covered_by.empty?
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/stryker.rb

@@ -34,10 +34,20 @@ module Saboteur
           projectRoot: report.root,
           files: files,
           testFiles: test_files(test_ids),
-          framework: { name: "saboteur", version: VERSION }
+          skippedSubjects: skipped_subjects(report),
+          rejectedKills: report.rejected_kills,
+          warnings: report.warnings,
+          framework: { name: "saboteur", version: VERSION },
+          saboteur: { findings: Findings.build(report) }
         }.merge(report.seed ? { config: { seed: report.seed } } : {})
       end
 
+      def self.skipped_subjects(report)
+        report.skipped_subjects.map do |subject, reason|
+          { subject: subject.id, file: relative(subject.file, report.root), line: subject.start_line, reason: reason }
+        end
+      end
+
       def self.test_index(results)
         names = results.flat_map { |result| result.covered_by + result.killed_by }.uniq
         names.each_with_index.to_h { |name, index| [name, index.to_s] }

data/lib/saboteur/reporter/terminal.rb

@@ -14,6 +14,7 @@ module Saboteur
 
       def call(report)
         summary(report)
+        skipped_subjects(report)
         warnings(report)
         errors(report)
         survivors(report)
@@ -50,6 +51,7 @@ module Saboteur
         reused = report.results.count(&:reused?)
         @out.puts "reused #{reused} of #{report.results.size} verdicts from earlier runs (--incremental)" if
           reused.positive?
+        @out.puts "kills rejected by unchanged-method check: #{report.rejected_kills}"
         kill_causes(report)
       end
 
@@ -80,6 +82,15 @@ module Saboteur
         parts.join(", ")
       end
 
+      def skipped_subjects(report)
+        report.skipped_subjects.values.tally.each do |reason, count|
+          @out.puts "skipped subjects: #{reason}: #{count}"
+        end
+        report.skipped_subjects.each do |subject, reason|
+          @out.puts "  #{subject.id} #{relative(subject.file, report.root)}:#{subject.start_line}: #{reason}"
+        end
+      end
+
       def warnings(report)
         report.warnings.each { |warning| @out.puts "warning: #{warning}" }
       end

data/lib/saboteur/result.rb

@@ -17,7 +17,7 @@ module Saboteur
     attr_accessor :ignored
 
     def initialize(subject:, mutation:, status:, mutated_source:, reason: nil, runtime: nil, killed_by: [],
-                   covered_by: [], kill_cause: nil, reused: false)
+                   covered_by: [], kill_cause: nil, reused: false, rejected_kill: false)
       raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
 
       @subject = subject
@@ -29,14 +29,20 @@ module Saboteur
       @covered_by = covered_by
       @mutated_source = mutated_source
       @kill_cause = kill_cause
+      @rejected_kill = rejected_kill
       @reused = reused
       @ignored = nil
     end
 
     # The same mutant, marked as an error: its verdict did not hold up.
-    def as_error(reason)
+    def as_error(reason, rejected_kill: false)
       MutantResult.new(subject: subject, mutation: mutation, status: :error, mutated_source: mutated_source,
-                       reason: reason, runtime: runtime, killed_by: killed_by, covered_by: covered_by)
+                       reason: reason, runtime: runtime, killed_by: killed_by, covered_by: covered_by,
+                       rejected_kill: rejected_kill)
+    end
+
+    def rejected_kill?
+      @rejected_kill
     end
 
     def digest
@@ -78,12 +84,12 @@ module Saboteur
 
   # Everything one run produced.
   class Report
-    attr_reader :results, :subjects, :wall_time, :invalid_mutations, :warnings, :root, :seed
+    attr_reader :results, :subjects, :wall_time, :invalid_mutations, :warnings, :root, :seed, :skipped_subjects
 
     # REVIEW: diff mode; the terminal then shows one survivor per line.
     # seed: the random seed every test run started from (nil when unknown).
     def initialize(results:, subjects:, wall_time:, root:, invalid_mutations: 0, warnings: [], review: false,
-                   seed: nil)
+                   seed: nil, skipped_subjects: {})
       @results = results
       @subjects = subjects
       @wall_time = wall_time
@@ -92,6 +98,11 @@ module Saboteur
       @warnings = warnings
       @review = review
       @seed = seed
+      @skipped_subjects = skipped_subjects
+    end
+
+    def rejected_kills
+      results.count(&:rejected_kill?)
     end
 
     def review?

data/lib/saboteur/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Saboteur
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/saboteur.rb

@@ -38,6 +38,7 @@ require_relative "saboteur/execution/supervisor"
 require_relative "saboteur/execution/reevaluator"
 require_relative "saboteur/execution/runner"
 require_relative "saboteur/execution/worker_pool"
+require_relative "saboteur/execution/fork_readiness"
 require_relative "saboteur/selection/coverage_map"
 require_relative "saboteur/selection/recorder"
 require_relative "saboteur/selection/git_diff"
@@ -46,6 +47,8 @@ require_relative "saboteur/config"
 require_relative "saboteur/ignore_list"
 require_relative "saboteur/frameworks/rails"
 require_relative "saboteur/reporter/diff"
+require_relative "saboteur/reporter/findings"
 require_relative "saboteur/reporter/terminal"
 require_relative "saboteur/reporter/stryker"
+require_relative "saboteur/reporter/html"
 require_relative "saboteur/engine"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: saboteur
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Vamsi Pavan Mahesh Gunturu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiddle
@@ -59,20 +59,26 @@ files:
 - README.md
 - exe/saboteur
 - lib/saboteur.rb
+- lib/saboteur/baseline_health.rb
 - lib/saboteur/cli.rb
 - lib/saboteur/config.rb
+- lib/saboteur/doctor.rb
 - lib/saboteur/engine.rb
+- lib/saboteur/engine/baseline_guard.rb
 - lib/saboteur/engine/boot.rb
+- lib/saboteur/engine/candidate_selection.rb
 - lib/saboteur/engine/candidates.rb
 - lib/saboteur/engine/coverage_store.rb
 - lib/saboteur/engine/diagnostics.rb
 - lib/saboteur/engine/diff_scope.rb
 - lib/saboteur/engine/distribution.rb
 - lib/saboteur/engine/result_cache.rb
+- lib/saboteur/engine/run_fingerprint.rb
 - lib/saboteur/engine/scheduler.rb
 - lib/saboteur/engine/subject_selection.rb
 - lib/saboteur/engine/suite_files.rb
 - lib/saboteur/engine/verdict_check.rb
+- lib/saboteur/execution/fork_readiness.rb
 - lib/saboteur/execution/process_table.rb
 - lib/saboteur/execution/process_tree.rb
 - lib/saboteur/execution/protocol.rb
@@ -81,6 +87,7 @@ files:
 - lib/saboteur/execution/supervisor.rb
 - lib/saboteur/execution/worker_pool.rb
 - lib/saboteur/frameworks/rails.rb
+- lib/saboteur/help.rb
 - lib/saboteur/hooks.rb
 - lib/saboteur/ignore_list.rb
 - lib/saboteur/integration/base.rb
@@ -88,8 +95,14 @@ files:
 - lib/saboteur/mutation_source/base.rb
 - lib/saboteur/mutation_source/builtin.rb
 - lib/saboteur/mutation_source/edit.rb
+- lib/saboteur/mutation_source/filter_replacement.rb
+- lib/saboteur/mutation_source/literal_replacement.rb
 - lib/saboteur/mutation_source/mutation.rb
+- lib/saboteur/replay.rb
 - lib/saboteur/reporter/diff.rb
+- lib/saboteur/reporter/findings.rb
+- lib/saboteur/reporter/html.rb
+- lib/saboteur/reporter/replay.rb
 - lib/saboteur/reporter/stryker.rb
 - lib/saboteur/reporter/terminal.rb
 - lib/saboteur/result.rb