saboteur 0.2.0 → 0.4.0

data/lib/saboteur/mutation_source/pair_removal.rb

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Deletes one association from a hash literal or keyword argument list.
+    class PairRemoval < Base
+      BOUNDARIES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode,
+                    Prism::ParametersNode, Prism::BlockParametersNode].freeze
+
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "pair_removal"
+      end
+
+      def mutations_for(subject)
+        found = []
+        tokens = Prism.lex(subject.file_source).value.map(&:first)
+        visit(subject.node.body, subject, found, tokens)
+        found
+      end
+
+      private
+
+      def visit(node, subject, found, tokens)
+        return if node.nil? || BOUNDARIES.any? { |type| node.is_a?(type) }
+
+        if node.is_a?(Prism::StatementsNode)
+          node.body.each do |child|
+            visit(child, subject, found, tokens) unless @arid.any? { |p| p.match?(child.slice) }
+          end
+          return
+        end
+        remove_pairs(node, subject, found, tokens) if node.is_a?(Prism::HashNode)
+        remove_keywords(node, subject, found, tokens) if node.is_a?(Prism::CallNode)
+        node.compact_child_nodes.each { |child| visit(child, subject, found, tokens) }
+      end
+
+      def remove_keywords(node, subject, found, tokens)
+        return unless node.arguments
+
+        node.arguments.arguments.grep(Prism::KeywordHashNode).each do |hash|
+          remove_pairs(hash, subject, found, tokens, call: node)
+        end
+      end
+
+      def remove_pairs(node, subject, found, tokens, call: nil)
+        pairs = node.elements
+        pairs.each_with_index do |pair, index|
+          next unless pair.is_a?(Prism::AssocNode)
+          next if heredoc?(pair)
+
+          edits = [delete(subject, pair.location)]
+          separator = separator_for(node, pairs, index, tokens, call)
+          edits << delete(subject, separator) if separator
+          found << Mutation.new(subject_id: subject.id, operator: name, edits: edits, source: name)
+        end
+      end
+
+      def separator_for(node, pairs, index, tokens, call)
+        pair = pairs[index]
+        ending = ending_for(node, call)
+        after = comma_between(pair.location.end_offset, ending, tokens)
+        return after if after
+
+        previous = pairs[0...index].last
+        previous ||= call.arguments.arguments[0...-1].last if call
+        comma_between(previous.location.end_offset, pair.location.start_offset, tokens) if previous
+      end
+
+      def ending_for(node, call)
+        return node.closing_loc.start_offset if node.is_a?(Prism::HashNode)
+        return call.closing_loc.start_offset if call.closing_loc
+        return call.block.location.start_offset if call.block
+
+        node.location.end_offset
+      end
+
+      def comma_between(first, last, tokens)
+        tokens.find do |token|
+          token.type == :COMMA && token.location.start_offset >= first && token.location.end_offset <= last
+        end&.location
+      end
+
+      def heredoc?(node)
+        (node.respond_to?(:opening_loc) && node.opening_loc&.slice&.start_with?("<<")) ||
+          node.compact_child_nodes.any? { |child| heredoc?(child) }
+      end
+
+      def delete(subject, location)
+        Edit.new(file: subject.file, start_byte: location.start_offset, end_byte: location.end_offset, replacement: "")
+      end
+    end
+  end
+end

data/lib/saboteur/replay.rb

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # Resolves one exact digest from current source, before caps, ignore suppression or incremental reuse.
+  class Replay
+    def initialize(digest:)
+      unless digest.match?(/\A[0-9a-f]{16}\z/)
+        raise ConfigError, "--id needs a full 16 lowercase hexadecimal mutant digest"
+      end
+
+      @digest = digest
+    end
+
+    def select(subjects, candidates, scope: nil)
+      match = nil
+      subjects.each do |subject|
+        list = candidates.for(subject)
+        list = scope.restrict(subject, list) if scope
+        list.each do |mutation, text|
+          digest = mutation.digest(subject_start: subject.start_byte, original_source: subject.file_source)
+          next unless digest == @digest
+          raise ConfigError, "mutant #{@digest} is ambiguous; narrow --subject or include files" if match
+
+          match = [subject, [mutation, text]]
+        end
+      end
+      raise ConfigError, "mutant #{@digest} not found in the selected current source" unless match
+
+      match
+    end
+  end
+end

data/lib/saboteur/reporter/agent.rb

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "json"
+require_relative "agent_summary"
+require_relative "agent_commands"
+
+module Saboteur
+  module Reporter
+    # A small JSON summary for an AI agent that runs saboteur (`saboteur run --agent`).
+    #
+    # The payload stays under BYTE_BUDGET: it never embeds file sources or the full
+    # Stryker report. It names the verdict, says plainly what was not covered, shows
+    # the first few findings with short edit snippets, counts the rest, and points
+    # at the commands and files that hold the full detail.
+    #
+    # Exit codes in this mode are stricter than the classic ones: 0 means the run
+    # was complete and clean, nothing less.
+    module Agent
+      VERSION = 1
+      BYTE_BUDGET = 8 * 1024
+      FINDING_LIMIT = 3
+      SNIPPET_LIMITS = [200, 80, 0].freeze
+      MAX_NUMBER_DIGITS = 20
+      WARNING_LIMIT = 3
+      WARNING_LENGTH = 160
+
+      EXIT_CLEAN = 0
+      EXIT_REVIEW = 1
+      EXIT_INVOCATION = 2
+      EXIT_INCOMPLETE = 3
+
+      # Where a verdict comes from: the exact selection and the state of the working
+      # source before the run started. subjects, tests and sources are arrays.
+      Provenance = Data.define(:ref, :seed, :head, :working_tree, :changed_files, :mode, :json_report, :subjects,
+                               :tests, :sources, :config_path, :digest, :cache, :incremental, :settings)
+
+      class << self
+        def call(report, provenance)
+          fit(report, provenance)
+        end
+
+        def render(payload)
+          "#{JSON.pretty_generate(payload)}\n"
+        end
+
+        def exit_code(payload)
+          payload.fetch(:exitCode)
+        end
+
+        # The payload for a run that never started or could not finish.
+        def failure(message, exit_code)
+          verdict = exit_code == EXIT_INVOCATION ? "invalid_invocation" : "tool_failure"
+          { version: VERSION, status: "error", verdict: verdict, exitCode: exit_code,
+            message: message.to_s[0, 500], next: { help: "saboteur help run" } }
+        end
+
+        private
+
+        def fit(report, provenance)
+          FINDING_LIMIT.downto(0) do |shown|
+            SNIPPET_LIMITS.each do |snippet_limit|
+              payload = Summary.build(report, provenance, shown, snippet_limit)
+              return payload if render(payload).bytesize <= BYTE_BUDGET
+            end
+          end
+          bounded_last_resort(report, provenance)
+        end
+
+        # The minimal payload, or four fixed keys when even that is over the budget.
+        def bounded_last_resort(report, provenance)
+          small = minimal(report, provenance)
+          return small if render(small).bytesize <= BYTE_BUDGET
+
+          small.slice(:version, :status, :verdict, :exitCode).merge(truncated: true)
+        end
+
+        # The last resort: fixed keys and short clipped values, so it always fits.
+        def minimal(report, provenance)
+          small = Summary.build(report, provenance, 0, SNIPPET_LIMITS.last)
+          small.merge(warnings: [], next: {}, provenance: small[:provenance].slice(:seed, :workingTree, :mode),
+                      incomplete: small[:incomplete].map { |reason| reason.slice(:reason, :count) })
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/agent_clipping.rb

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    module Agent
+      # Keeps display values short so the agent payload stays inside its byte budget.
+      module Clipping
+        # A seed or setting stays a number while it is short; a huge value cannot take the budget.
+        def bounded_number(value)
+          value.to_s.length <= MAX_NUMBER_DIGITS ? value : clip_value(value, MAX_NUMBER_DIGITS)
+        end
+
+        def clip_value(value, limit)
+          return nil if value.nil?
+
+          text = value.to_s
+          text.length > limit ? "#{text[0, limit]}..." : text
+        end
+
+        def clip(text, limit)
+          return "" if limit.zero?
+
+          text.length > limit ? "#{text[0, limit]}..." : text
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/agent_commands.rb

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Saboteur
+  module Reporter
+    module Agent
+      # The shell commands an agent is told to run next. Every word is escaped with
+      # Shellwords, so a ref, path or subject holding shell syntax stays one literal
+      # argument. A command is never cut short: when it is longer than MAX_BYTES it
+      # is left out, because half a command could run something else.
+      module Commands
+        MAX_BYTES = 1024
+
+        # 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
+
+        class << self
+          # Run the same selection again: ref, subjects, sources, tests, config,
+          # cache mode and replay digest, with the recorded seed.
+          def rerun(provenance)
+            words = ["saboteur", "run", "--agent", *selection(provenance), "--seed", provenance.seed.to_s]
+            finish(words, provenance)
+          end
+
+          # Replay one survivor by digest in the same selection.
+          def replay(provenance, digest)
+            words = ["saboteur", "run", "--id", digest, *selection(provenance, replay: true), "--seed",
+                     provenance.seed.to_s]
+            finish(words, provenance)
+          end
+
+          private
+
+          def finish(words, provenance)
+            words += ["--", *provenance.sources] unless provenance.sources.empty?
+            command = Shellwords.join(words)
+            command.bytesize <= MAX_BYTES ? command : nil
+          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 << "--no-cache" if provenance.cache == false
+            words << "--incremental" if provenance.incremental
+            words.push("--id", provenance.digest) if provenance.digest && !replay
+            words
+          end
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/agent_incomplete.rb

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    module Agent
+      # What makes a verdict cover less than the whole selection. Each reason has a
+      # stable code, a count and a plain meaning.
+      module Incomplete
+        class << self
+          def reasons(report)
+            reasons = []
+            add(reasons, "no_coverage", skipped_for_coverage(report), "subjects or mutants had no covering test")
+            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")
+            reasons
+          end
+
+          private
+
+          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]
+          end
+
+          def omitted_by_cap(report)
+            report.warnings.sum { |warning| warning[/omitted (\d+) mutant/, 1].to_i }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/agent_summary.rb

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "findings"
+require_relative "agent_incomplete"
+require_relative "agent_clipping"
+
+module Saboteur
+  module Reporter
+    module Agent
+      # Builds the payload hash for one run: status, verdict, exit code, counts,
+      # provenance, a few findings and the next commands.
+      module Summary
+        class << self
+          include Clipping
+
+          # Public entry first; the helpers below are private.
+          def build(report, provenance, shown, snippet_limit)
+            incomplete = Incomplete.reasons(report)
+            status = status_of(report, incomplete)
+            verdict = verdict_of(report, status)
+            {
+              version: VERSION, status: status, verdict: verdict, exitCode: exit_code_for(verdict),
+              provenance: provenance_hash(provenance),
+              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),
+              next: next_steps(report, provenance)
+            }
+          end
+
+          private
+
+          def status_of(report, incomplete)
+            return "not_applicable" if report.results.empty? && report.skipped_subjects.empty?
+
+            incomplete.empty? ? "complete" : "partial"
+          end
+
+          def verdict_of(report, status)
+            return "survivors" if report.unignored_survivors.any?
+
+            { "complete" => "clean", "partial" => "incomplete", "not_applicable" => "not_applicable" }.fetch(status)
+          end
+
+          def exit_code_for(verdict)
+            case verdict
+            when "clean" then EXIT_CLEAN
+            when "survivors" then EXIT_REVIEW
+            else EXIT_INCOMPLETE
+            end
+          end
+
+          def counts(report)
+            report.counts.transform_keys { |status| camel(status) }.merge(executed: report.executed.size)
+          end
+
+          def camel(status)
+            status.to_s.gsub(/_(\w)/) { Regexp.last_match(1).upcase }.to_sym
+          end
+
+          def score(report)
+            report.score&.round(4)
+          end
+
+          # Display values are clipped; the commands under next use the exact values or are left out.
+          def provenance_hash(provenance)
+            { ref: clip_value(provenance.ref, 120), seed: bounded_number(provenance.seed),
+              head: clip_value(provenance.head, 64),
+              workingTree: provenance.working_tree, changedFiles: provenance.changed_files,
+              mode: provenance.mode, selection: selection_hash(provenance) }
+          end
+
+          def selection_hash(provenance)
+            %i[subjects tests sources].to_h do |key|
+              list = provenance.public_send(key)
+              [key, { count: list.size, first: list.first(3).map { |entry| clip_value(entry, 120) } }]
+            end.merge(config: clip_value(provenance.config_path, 120), digest: provenance.digest,
+                      settings: provenance.settings.transform_values { |value| clip_value(value, 120) })
+          end
+
+          def findings(report, shown, snippet_limit)
+            all = Findings.build(report)
+            live = report.unignored_survivors.size
+            {
+              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]
+            }
+          end
+
+          def shown_findings(listed, shown, snippet_limit)
+            listed.first(shown).map do |finding|
+              finding.slice(:digest, :line, :endLine, :operator, :coarse)
+                     .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))
+            end
+          end
+
+          def warnings(report)
+            report.warnings.first(WARNING_LIMIT).map { |warning| warning.to_s[0, WARNING_LENGTH] }
+          end
+
+          def next_steps(report, provenance)
+            steps = {}
+            add_command(steps, :rerun, Commands.rerun(provenance))
+            first = Findings.build(report)[:survivors].first
+            add_command(steps, :replay, Commands.replay(provenance, first[:digest])) if first
+            steps[:fullReport] = provenance.json_report if short_path?(provenance.json_report)
+            steps
+          end
+
+          def short_path?(path)
+            path && path.bytesize <= 400
+          end
+
+          def add_command(steps, key, command)
+            steps[key] = command
+            return if command
+
+            steps[:"#{key}Unavailable"] =
+              "command longer than #{Commands::MAX_BYTES} bytes; rebuild it from provenance"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/findings.rb

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # Findings for a code-review surface such as the saboteur GitHub Action:
+    # a bounded list of survivors with everything a note on the pull-request
+    # diff needs (file, line, digest, operator, original and replacement).
+    # Survivors accepted on the ignore list are listed apart, with their
+    # reason. The full, unbounded mutant data stays in the report's files
+    # section; survivorsTruncated says how many more findings live only there.
+    module Findings
+      VERSION = 1
+
+      # 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"
+
+      class << self
+        def build(report)
+          live, accepted = report.survivors.partition { |result| result.ignored.nil? }
+          {
+            version: VERSION,
+            ordering: ORDERING,
+            limit: LIMIT,
+            survivors: listed(report, live),
+            survivorsTruncated: truncated(live),
+            accepted: listed(report, accepted),
+            acceptedTruncated: truncated(accepted)
+          }
+        end
+
+        private
+
+        def listed(report, results)
+          ordered(report, results).first(LIMIT).map { |result| finding(report, result) }
+        end
+
+        def truncated(results)
+          [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)
+        end
+
+        def finding(report, result)
+          entries = edit_entries(result)
+          entry = {
+            digest: result.digest,
+            path: path(report, result),
+            line: entries.map { |edit| edit[:line] }.min,
+            endLine: entries.map { |edit| edit[:endLine] }.max,
+            subject: result.subject.id,
+            operator: result.mutation.operator,
+            original: joined_texts(result) { |edit| original_text(result, edit) },
+            replacement: joined_texts(result, &:replacement),
+            edits: entries,
+            coarse: result.mutation.coarse
+          }
+          entry = with_changed_lines(report, result, entry)
+          result.ignored ? entry.merge(reason: result.ignored) : entry
+        end
+
+        # In diff mode, the changed lines the mutant touches. line above is where
+        # the mutated statement starts, which can be above the changed line.
+        def with_changed_lines(report, result, entry)
+          lines = report.changed_lines_for(result)
+          lines.empty? ? entry : entry.merge(changedLines: lines)
+        end
+
+        # Subject#apply applies edits in start-byte order; findings use the
+        # same order, so an unsorted edit list from a custom mutation source
+        # still gets a sane range and one entry per edit.
+        def sorted_edits(result)
+          result.mutation.edits.sort_by(&:start_byte)
+        end
+
+        # Stryker joins a multi-edit mutant's replacements the same way, so
+        # both reports describe one mutant with one text.
+        def joined_texts(result, &pick)
+          sorted_edits(result).map { |edit| safe_text(pick.call(edit)) }.join(" | ")
+        end
+
+        # One entry per edit, so a multi-edit finding can point each joined
+        # text at its own spot on the diff.
+        def edit_entries(result)
+          sorted_edits(result).map do |edit|
+            {
+              line: result.subject.line_of(edit.start_byte),
+              endLine: result.subject.line_of([edit.end_byte - 1, edit.start_byte].max),
+              original: safe_text(original_text(result, edit)),
+              replacement: safe_text(edit.replacement)
+            }
+          end
+        end
+
+        def original_text(result, edit)
+          result.subject.file_source.byteslice(edit.start_byte, edit.end_byte - edit.start_byte)
+        end
+
+        # A byte slice of source may be invalid UTF-8, which JSON cannot hold.
+        def safe_text(text)
+          text.dup.force_encoding(Encoding::UTF_8).scrub
+        end
+
+        def path(report, result)
+          result.subject.file.delete_prefix("#{report.root}/")
+        end
+      end
+    end
+  end
+end