saboteur 0.2.0 → 0.4.0

data/lib/saboteur/ignore_list.rb

@@ -1,40 +1,94 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
-require "yaml"
-
 module Saboteur
-  # Survivors the team has accepted. YAML list of entries:
+  # Entry point used by config/saboteur_ignore.rb.
+  def self.ignore
+    collector = IgnoreList.current_collector
+    raise "Saboteur.ignore is only valid while config/saboteur_ignore.rb loads" unless collector
+
+    yield collector
+    collector
+  end
+
+  # Survivors the team has accepted. config/saboteur_ignore.rb declares them:
   #
-  #   - subject: "Person#adult?"
-  #     mutation: "1a2b3c4d5e6f7a8b"   # digest shown next to each survivor
-  #     reason: "equivalent: age is always an integer"
+  #   Saboteur.ignore do |i|
+  #     i.mutation "1a2b3c4d5e6f7a8b",
+  #                subject: "Person#adult?",
+  #                reason: "equivalent: age is always an integer"
+  #   end
   #
   # reason is mandatory; a file with a missing or blank reason does not load.
   class IgnoreList
     Entry = Data.define(:subject, :mutation, :reason)
 
+    # Collects the entries a saboteur_ignore.rb file declares.
+    class Collector
+      attr_reader :entries
+
+      def initialize
+        @entries = []
+      end
+
+      def mutation(digest = nil, subject: nil, reason: nil)
+        line = caller_locations(1, 1).first.lineno
+        values = { "subject" => subject, "mutation" => digest, "reason" => reason }
+        missing = values.select { |_, value| value.to_s.strip.empty? }.keys
+        raise ConfigError, "#{line}: entry is missing #{missing.join(', ')}" if missing.any?
+
+        @entries << Entry.new(
+          subject: subject.to_s.strip,
+          mutation: digest.to_s.strip,
+          reason: reason.to_s.strip
+        )
+      end
+    end
+
     attr_reader :entries
 
+    # The collector is process-global on purpose: the ignore file calls the
+    # top-level Saboteur.ignore, which must reach the load in progress.
+    # Loads are therefore serialized - never load two ignore files at once.
     def self.load(path)
       return new([]) unless path && File.file?(path)
 
-      data = YAML.safe_load_file(path) || []
-      raise ConfigError, "#{path}: expected a list of entries" unless data.is_a?(Array)
+      @collector = Collector.new
+      Kernel.load(path)
+      new(@collector.entries)
+    rescue ConfigError => e
+      raise ConfigError, "#{path}:#{e.message}"
+    rescue NoMethodError => e
+      raise ConfigError, unknown_directive_message(path, e) if e.receiver.is_a?(Collector)
 
-      new(data.each_with_index.map { |raw, index| parse_entry(raw, path, index) })
-    rescue Psych::SyntaxError => e
-      raise ConfigError, "#{path}: #{e.message}"
+      # A typo'd call outside the collector: same treatment as a bare
+      # constant, or the raw NoMethodError points at our internals.
+      raise ConfigError, name_error_message(path, e)
+    rescue SyntaxError, LoadError => e
+      raise ConfigError, "#{path}: #{e.message.lines.first.to_s.chomp}"
+    rescue NameError => e
+      raise ConfigError, name_error_message(path, e)
+    ensure
+      @collector = nil
     end
 
-    def self.parse_entry(raw, path, index)
-      raise ConfigError, "#{path}: entry #{index + 1} is not a mapping" unless raw.is_a?(Hash)
+    def self.unknown_directive_message(path, error)
+      line = error.backtrace_locations.find { |loc| loc.path == path }&.lineno
+      "#{path}:#{line}: unknown directive #{error.name.to_s.inspect} - " \
+        'declare entries with mutation "<digest>", subject:, reason:'
+    end
+
+    def self.name_error_message(path, error)
+      line = error.backtrace_locations&.find { |loc| loc.path == path }&.lineno
+      "#{path}:#{line}: #{error.message.lines.first.to_s.chomp} " \
+        "- this file loads before the app boots; use plain Ruby or ENV"
+    end
 
-      values = %w[subject mutation reason].to_h { |key| [key, raw[key].to_s.strip] }
-      missing = values.select { |_, value| value.empty? }.keys
-      raise ConfigError, "#{path}: entry #{index + 1} is missing #{missing.join(', ')}" if missing.any?
+    private_class_method :unknown_directive_message, :name_error_message
 
-      Entry.new(subject: values["subject"], mutation: values["mutation"], reason: values["reason"])
+    # The Collector Saboteur.ignore hands to the file being loaded.
+    def self.current_collector
+      @collector
     end
 
     def initialize(entries)

data/lib/saboteur/install.rb

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Saboteur
+  # Writes the Rails starter files: config/saboteur.rb, bin/saboteur and a
+  # .gitignore entry. Plain Ruby so it runs and tests without Rails; the
+  # `rails generate saboteur:install` generator is a thin wrapper over it.
+  # Existing files are never overwritten unless force is set.
+  class Install
+    CONFIG = <<~RUBY
+      # saboteur configuration for a Rails + RSpec app. CLI flags override this file.
+      Saboteur.configure do |c|
+        c.include = ["app/**/*.rb"]
+        # Empty base classes: nothing useful to mutate.
+        c.exclude = [
+          "app/models/application_record.rb",
+          "app/controllers/application_controller.rb",
+          "app/jobs/application_job.rb",
+          "app/mailers/application_mailer.rb",
+        ]
+        c.require = ["./config/environment"] # boots the app before specs load
+        c.rails = true                       # reconnect ActiveRecord after fork, per-worker databases
+        c.jobs = 4                           # parallel workers; use 1 if your specs share external state
+      end
+    RUBY
+
+    BIN = <<~RUBY
+      #!/usr/bin/env ruby
+      # frozen_string_literal: true
+
+      ENV["RAILS_ENV"] ||= "test"
+      require "bundler/setup"
+      load Gem.bin_path("saboteur", "saboteur")
+    RUBY
+
+    IGNORE_ENTRY = ".saboteur/"
+
+    GEMFILE_HINT = <<~TEXT
+      Add saboteur to your Gemfile if it is not there yet:
+
+        group :test do
+          gem "saboteur", require: false
+        end
+
+      Then run it with SimpleCov off for the run, for example:
+
+        bin/saboteur run --since origin/main
+    TEXT
+
+    Result = Data.define(:status, :path)
+
+    def initialize(root: Dir.pwd, force: false)
+      @root = File.expand_path(root)
+      @force = force
+    end
+
+    # Returns the list of Results (:created, :overwritten, :skipped, :appended, :unchanged).
+    def call
+      [write("config/saboteur.rb", CONFIG), write("bin/saboteur", BIN, mode: 0o755), gitignore]
+    end
+
+    # Printed after install; the Gemfile is never edited.
+    def gemfile_hint
+      gemfile = File.join(@root, "Gemfile")
+      return nil if File.file?(gemfile) && File.read(gemfile).match?(/^\s*gem\s+["']saboteur["']/)
+
+      GEMFILE_HINT
+    end
+
+    private
+
+    # Never writes or chmods through a symlink: not the file itself, and not a
+    # symlinked directory above it (bin -> elsewhere). Without force the file is
+    # skipped; with force the link is removed and replaced by a real file or
+    # directory inside the project, and the old target is left alone.
+    def write(relative, content, mode: nil)
+      path = File.join(@root, relative)
+      link = symlink_component(relative)
+      existed = present?(path)
+      return Result.new(:skipped, relative) if (existed || link) && !@force
+
+      File.delete(link) if link
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+      File.chmod(mode, path) if mode
+      Result.new(existed ? :overwritten : :created, relative)
+    end
+
+    # The first symlink on the way from the project root to the file, if any.
+    def symlink_component(relative)
+      current = @root
+      relative.split("/").each do |part|
+        current = File.join(current, part)
+        return current if File.symlink?(current)
+      end
+      nil
+    end
+
+    # A dangling symlink does not "exist" but is not free to write either.
+    def present?(path)
+      File.exist?(path) || File.symlink?(path)
+    end
+
+    def gitignore
+      path = File.join(@root, ".gitignore")
+      link = symlink_component(".gitignore")
+      return Result.new(:skipped, ".gitignore") if link && !@force
+
+      current = File.file?(path) ? File.read(path) : ""
+      listed = listed?(current)
+      return Result.new(:unchanged, ".gitignore") if listed && !link
+
+      File.delete(link) if link
+      File.write(path, "#{current}#{missing_entry(current, listed)}")
+      Result.new(link ? :overwritten : :appended, ".gitignore")
+    end
+
+    def listed?(text)
+      text.lines.map(&:strip).include?(IGNORE_ENTRY)
+    end
+
+    # What to append so .saboteur/ is on its own line; nothing if already there.
+    def missing_entry(current, listed)
+      return "" if listed
+
+      separator = current.empty? || current.end_with?("\n") ? "" : "\n"
+      "#{separator}#{IGNORE_ENTRY}\n"
+    end
+  end
+end

data/lib/saboteur/integration/base.rb

@@ -61,6 +61,14 @@ module Saboteur
         raise NotImplementedError
       end
 
+      # Checks the unchanged suite in a fresh child. Existing adapters can
+      # use their selected-test runner; adapters may override to retain full
+      # suite ordering and report every executed test.
+      def run_baseline(seed:)
+        Kernel.srand(seed)
+        run(all_tests.map(&:id))
+      end
+
       # Files whose content decides which tests exist (for the cache key).
       def test_files
         []

data/lib/saboteur/integration/rspec.rb

@@ -10,9 +10,9 @@ module Saboteur
       def setup
         require "rspec/core"
         ::RSpec::Core::Runner.disable_autorun!
-        options = ::RSpec::Core::ConfigurationOptions.new(rspec_args)
-        @runner = ::RSpec::Core::Runner.new(options)
+        @runner = ::RSpec::Core::Runner.new(configuration_options)
         @runner.setup($stderr, $stdout)
+        configuration.order = "rand:#{config.fetch('seed', 1)}"
         raise Error, "rspec quit while loading spec files" if world.wants_to_quit
       end
 
@@ -22,6 +22,16 @@ module Saboteur
         args.any? { |arg| !arg.start_with?("-") } ? args : args + ["spec"]
       end
 
+      # RSpec's own parser reads rspec_args and .rspec, so option values such
+      # as `--require path` stay intact. Explicit tests then replace only the
+      # files and directories to run.
+      def configuration_options
+        ::RSpec::Core::ConfigurationOptions.new(rspec_args).tap do |options|
+          explicit = Array(config.fetch("tests", []))
+          options.options[:files_or_directories_to_run] = explicit if explicit.any?
+        end
+      end
+
       def all_tests
         groups = world.ordered_example_groups.flat_map(&:descendants)
         groups.flat_map { |group| world.filtered_examples[group] }
@@ -47,8 +57,19 @@ module Saboteur
       end
 
       def run_all(recorder)
+        configuration.order = "rand:#{config.fetch('seed', 1)}"
         configuration.fail_fast = false
-        execute(Listener.new(recorder))
+        execute(Listener.new(recorder), log_phase: true)
+      end
+
+      def run_baseline(seed:)
+        configuration.order = "rand:#{seed}"
+        configuration.fail_fast = false
+        listener = Listener.new
+        passed = execute(listener, log_phase: true)
+        RunResult.new(passed: passed && listener.failed.empty?, failed_ids: listener.failed,
+                      executed_ids: listener.executed, runtime: listener.runtime,
+                      failure_classes: listener.failure_classes, failure_messages: listener.failure_messages)
       end
 
       private
@@ -83,11 +104,19 @@ module Saboteur
         world.example_groups.flat_map(&:descendants).each(&:reset_memoized)
       end
 
-      def execute(listener)
+      # log_phase is for the baseline and coverage children, whose $stdout is
+      # redirected to the phase's log: progress and failure detail land in
+      # that log, so a failed phase can be diagnosed from it. Mutant runs
+      # stay quiet.
+      def execute(listener, log_phase: false)
         reporter = ::RSpec::Core::Reporter.new(configuration)
         reporter.register_listener(listener, *Listener::EVENTS)
         groups = world.ordered_example_groups.select { |group| group.descendant_filtered_examples.any? }
         count = world.example_count(groups)
+        if log_phase
+          logger = PhaseLogger.new($stdout, total: count)
+          reporter.register_listener(logger, *PhaseLogger::EVENTS)
+        end
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         passed = reporter.report(count) do |r|
           configuration.with_suite_hooks { groups.map { |group| group.run(r) }.all? }
@@ -96,6 +125,42 @@ module Saboteur
         passed && !world.non_example_failure
       end
 
+      # Progress and failure detail for a phase log. Every 25 finished
+      # examples is enough to see movement on a tail; failures print RSpec's
+      # full formatted detail, and the run ends with RSpec's totals line.
+      class PhaseLogger
+        EVENTS = %i[example_finished message dump_failures dump_summary].freeze
+
+        PROGRESS_EVERY = 25
+
+        def initialize(out, total:)
+          @out = out
+          @total = total
+          @executed = 0
+        end
+
+        def example_finished(_notification)
+          @executed += 1
+          return unless @executed == @total || (@executed % PROGRESS_EVERY).zero?
+
+          @out.puts("#{@executed}/#{@total} examples finished")
+        end
+
+        # A failure outside any example (a suite hook, a load error) arrives
+        # as a message, never in dump_failures.
+        def message(notification)
+          @out.puts(notification.message)
+        end
+
+        def dump_failures(notification)
+          @out.puts(notification.fully_formatted_failed_examples)
+        end
+
+        def dump_summary(notification)
+          @out.puts(notification.totals_line)
+        end
+      end
+
       class Listener
         EVENTS = %i[example_started example_finished example_failed].freeze
 

data/lib/saboteur/mutation_source/argument_removal.rb

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Deletes one ordinary argument from a parenthesized method call.
+    class ArgumentRemoval < Base
+      BOUNDARIES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode,
+                    Prism::ParametersNode, Prism::BlockParametersNode].freeze
+      EXCLUDED = [Prism::KeywordHashNode, Prism::SplatNode, Prism::ForwardingArgumentsNode].freeze
+
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "argument_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? do |p|
+              p.match?(child.slice)
+            end
+          end
+          return
+        end
+        remove_arguments(node, subject, found, tokens) if node.is_a?(Prism::CallNode)
+        node.compact_child_nodes.each { |child| visit(child, subject, found, tokens) }
+      end
+
+      def remove_arguments(node, subject, found, tokens)
+        return unless node.opening_loc&.slice == "(" && node.arguments
+
+        arguments = node.arguments.arguments
+        arguments.each_with_index do |argument, index|
+          next if EXCLUDED.any? { |type| argument.is_a?(type) } || heredoc?(argument)
+
+          separator = separator_for(node, arguments, index, tokens)
+          edits = [delete(subject, argument.location)]
+          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, arguments, index, tokens)
+        argument = arguments[index]
+        after = comma_between(argument.location.end_offset, node.closing_loc.start_offset, tokens)
+        return after if after
+
+        previous = arguments[0...index].last
+        comma_between(previous.location.end_offset, argument.location.start_offset, tokens) if previous
+      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/mutation_source/builtin.rb

@@ -3,6 +3,10 @@
 
 require "prism"
 require_relative "base"
+require_relative "filter_replacement"
+require_relative "literal_replacement"
+require_relative "argument_removal"
+require_relative "pair_removal"
 
 module Saboteur
   module MutationSource
@@ -46,6 +50,10 @@ module Saboteur
       def initialize(arid: DEFAULT_ARID)
         super()
         @arid = arid.map { |pattern| pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern) }
+        @filter_replacement = FilterReplacement.new(arid: arid)
+        @literal_replacement = LiteralReplacement.new(arid: arid)
+        @argument_removal = ArgumentRemoval.new(arid: arid)
+        @pair_removal = PairRemoval.new(arid: arid)
       end
 
       def name
@@ -58,7 +66,10 @@ module Saboteur
         @found = []
         coarse(body)
         visit(body)
-        @found
+        @found.concat(@filter_replacement.mutations_for(subject))
+        @found.concat(@literal_replacement.mutations_for(subject))
+        @found.concat(@argument_removal.mutations_for(subject))
+        @found.concat(@pair_removal.mutations_for(subject))
       ensure
         @subject = nil
       end
@@ -86,8 +97,8 @@ module Saboteur
       end
 
       # A raise that the method's own rescue catches is absorbed by design. It
-      # would survive, and a surviving coarse mutant stops every fine mutant
-      # of the method, so it is not generated.
+      # is not generated: rejecting that exception is not the rescue contract.
+      # Fine mutants still run regardless of the coarse verdicts.
       def rescues_everything?(body)
         clause = body.is_a?(Prism::BeginNode) ? body.rescue_clause : nil
         while clause

data/lib/saboteur/mutation_source/filter_replacement.rb

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Swaps the inclusion rule of a filter call with its exclusion rule.
+    # Only message bytes change; arguments, receiver and block stay intact.
+    class FilterReplacement < Base
+      REPLACEMENTS = { select: "reject", reject: "select", select!: "reject!", reject!: "select!" }.freeze
+      SCOPE_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+
+      # Base inherits Object's empty initializer; there is no parent state to set.
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "filter_replacement"
+      end
+
+      def mutations_for(subject)
+        found = []
+        visit(subject.node.body, subject, found)
+        found
+      end
+
+      private
+
+      def visit(node, subject, found)
+        return if node.nil? || SCOPE_NODES.any? { |scope| node.is_a?(scope) }
+
+        if node.is_a?(Prism::StatementsNode)
+          node.body.each { |statement| visit(statement, subject, found) unless arid?(statement) }
+          return
+        end
+
+        replace_filter(node, subject, found) if node.is_a?(Prism::CallNode)
+        node.compact_child_nodes.each { |child| visit(child, subject, found) }
+      end
+
+      def replace_filter(node, subject, found)
+        replacement = REPLACEMENTS[node.name]
+        return unless replacement && node.receiver && node.block
+        return unless node.arguments.nil?
+
+        location = node.message_loc
+        edit = Edit.new(file: subject.file, start_byte: location.start_offset,
+                        end_byte: location.end_offset, replacement: replacement)
+        found << Mutation.new(subject_id: subject.id, operator: name, edits: [edit], source: name)
+      end
+
+      def arid?(node)
+        @arid.any? { |pattern| pattern.match?(node.slice) }
+      end
+    end
+  end
+end

data/lib/saboteur/mutation_source/literal_replacement.rb

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "base"
+
+module Saboteur
+  module MutationSource
+    # Changes literal values without rebuilding the surrounding source.
+    class LiteralReplacement < Base
+      SCOPE_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+      TEXT_NODES = [Prism::InterpolatedStringNode, Prism::SymbolNode, Prism::InterpolatedSymbolNode,
+                    Prism::RegularExpressionNode, Prism::InterpolatedRegularExpressionNode,
+                    Prism::XStringNode, Prism::InterpolatedXStringNode].freeze
+      PARAMETER_NODES = [Prism::ParametersNode, Prism::BlockParametersNode].freeze
+      BOUNDARIES = (SCOPE_NODES + TEXT_NODES + PARAMETER_NODES).freeze
+
+      # Base inherits Object's empty initializer; there is no parent state to set.
+      def initialize(arid: []) # rubocop:disable Lint/MissingSuper
+        @arid = arid.map { |pattern| Regexp.new(pattern) }
+      end
+
+      def name
+        "literal_replacement"
+      end
+
+      def mutations_for(subject)
+        found = []
+        visit(subject.node.body, subject, found)
+        found
+      end
+
+      private
+
+      def visit(node, subject, found)
+        return if node.nil? || boundary?(node)
+
+        if node.is_a?(Prism::StatementsNode)
+          node.body.each { |statement| visit(statement, subject, found) unless arid?(statement) }
+          return
+        end
+
+        case node
+        when Prism::TrueNode then add(subject, found, node, "literal_boolean", "false")
+        when Prism::FalseNode then add(subject, found, node, "literal_boolean", "true")
+        when Prism::StringNode
+          replace_string(node, subject, found)
+        end
+        node.compact_child_nodes.each { |child| visit(child, subject, found) }
+      end
+
+      def boundary?(node)
+        BOUNDARIES.any? { |type| node.is_a?(type) }
+      end
+
+      def replace_string(node, subject, found)
+        return if node.unescaped.empty?
+        return unless node.opening_loc && !node.opening_loc.slice.start_with?("<<")
+
+        add(subject, found, node, "literal_string", '""')
+      end
+
+      def add(subject, found, node, operator, replacement)
+        edit = Edit.new(file: subject.file, start_byte: node.location.start_offset,
+                        end_byte: node.location.end_offset, replacement: replacement)
+        found << Mutation.new(subject_id: subject.id, operator: operator, edits: [edit], source: name)
+      end
+
+      def arid?(node)
+        @arid.any? { |pattern| pattern.match?(node.slice) }
+      end
+    end
+  end
+end