mutineer-mongoid 2.0.0

data/lib/mutineer/statement_lines.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # The lines of the statement that holds a position in a method body.
+  #
+  # Ruby counts one line of a statement only. A position on another line of a
+  # multi-line statement has no count of its own, but the tests that ran the
+  # statement ran it. Prism marks the statements (`Node#newline?`), so the
+  # nearest marked ancestor of the position is the statement. The caller reads
+  # the counts on the lines of the statement; a line Ruby does not count has none.
+  module StatementLines
+    # @param def_node [Prism::DefNode] the method that holds the position.
+    # @param source [String] the source text of the file.
+    # @param offset [Integer] byte offset of the position.
+    # @return [Array<Integer>] the lines of the statement, with the body of each
+    #   heredoc in it. Empty when no statement in the body holds the position.
+    #   A first or last line that holds other code is left out, because Ruby
+    #   can count that line without the statement: the `def` line counts when
+    #   the file loads, and `x if done; y(` counts when `y` does not run.
+    def self.for(def_node, source, offset)
+      return [] unless def_node.body
+
+      path = path_to(def_node.body, offset) || []
+      index = path.rindex(&:newline?)
+      return [] unless index
+
+      statement = path[index]
+      # Code that runs only sometimes inside the statement: the tests that ran
+      # the statement need not have run it.
+      return [] if path[index..].each_cons(2).any? { |parent, child| sometimes?(parent, child) }
+
+      # Ruby counts the line of `x while c` or `x if c` when it checks `c`,
+      # also when `x` never runs. The path is the modifier, its body, statement.
+      return [] if index >= 2 && modifier?(path[index - 2])
+
+      location = statement.location
+      lines = (location.start_line..last_line(statement)).to_a
+      lines.delete(location.start_line) unless before(source, location).strip.empty?
+      after = after(source, location).strip
+      lines.delete(location.end_line) unless after.empty? || after.start_with?("#")
+      lines
+    end
+
+    # Whether the code at `offset` runs each time the method runs: it is in
+    # the first statement of the body, not in a statement nested in it or in
+    # a {NESTED} node (a block or loop body), and not in code that runs only
+    # sometimes ({sometimes?}, the body of `x if c`). The first statement in
+    # parentheses or `begin ... end` runs with them, so it counts
+    # ({grouped_first?}). Used for a method whose body shares the `def` line,
+    # where only the method's call count tells that the code ran (#209).
+    #
+    # @param def_node [Prism::DefNode] the method that holds the position.
+    # @param offset [Integer] byte offset of the position.
+    # @return [Boolean]
+    def self.runs_with_method?(def_node, offset)
+      first = def_node.body.is_a?(Prism::StatementsNode) && def_node.body.body.first
+      path = first && path_to(first, offset)
+      return false unless path
+
+      return false if path.drop(1).any? { |node| NESTED.any? { |klass| node.is_a?(klass) } }
+      return false if path[1]&.newline?
+
+      path.each_cons(3).none? { |grand, parent, node| node.newline? && !grouped_first?(grand, parent, node) } &&
+        path.each_cons(2).none? { |parent, child| sometimes?(parent, child) }
+    end
+
+    # Whether `node` is the first statement in parentheses or `begin ... end`,
+    # which runs each time they do.
+    #
+    # @param grand [Prism::Node] the parent of `parent`.
+    # @param parent [Prism::Node] the parent of `node`.
+    # @param node [Prism::Node]
+    # @return [Boolean]
+    def self.grouped_first?(grand, parent, node)
+      (grand.is_a?(Prism::ParenthesesNode) || grand.is_a?(Prism::BeginNode)) &&
+        parent.is_a?(Prism::StatementsNode) && parent.body.first.equal?(node)
+    end
+
+    # Nodes whose code can run any number of times, or not at all, when the
+    # statement that holds them runs.
+    NESTED = [Prism::BlockNode, Prism::LambdaNode, Prism::WhileNode, Prism::UntilNode, Prism::ForNode,
+              Prism::DefNode].freeze
+
+    # Nodes whose code runs only when a branch, a match or an exception picks
+    # it: a `when` or `in` clause (its condition or pattern), a `rescue` clause
+    # (its class list), an `else` branch, parameters (their defaults) and
+    # `defined?` (its operand never runs). A statement in their bodies is a statement of its own, found
+    # deeper on the path.
+    SOMETIMES = [Prism::WhenNode, Prism::InNode, Prism::RescueNode, Prism::ElseNode, Prism::ParametersNode,
+                 Prism::BlockParametersNode, Prism::DefinedNode].freeze
+
+    # Whether `child` runs only sometimes when `parent` runs. Besides the
+    # {SOMETIMES} nodes: a branch of an `if`/`unless` inside the statement (a
+    # ternary, or `if c then a else b end` on the statement's lines), the
+    # rescue side of `x rescue y`, the pattern of `v in p` or `v => p`, the value of
+    # `a ||= v` or `a &&= v`, the right side of `a || b` or `a && b`, and the
+    # arguments and block of `x&.m(...)` and the value of `x&.m += v`, which do
+    # not run when `x` is nil.
+    #
+    # @param parent [Prism::Node]
+    # @param child [Prism::Node]
+    # @return [Boolean]
+    def self.sometimes?(parent, child)
+      return true if SOMETIMES.any? { |klass| child.is_a?(klass) }
+      return !child.equal?(parent.predicate) if parent.is_a?(Prism::IfNode) || parent.is_a?(Prism::UnlessNode)
+      # A pattern stops at its first part that does not match (`v in 1 | 2`).
+      if parent.is_a?(Prism::MatchPredicateNode) || parent.is_a?(Prism::MatchRequiredNode)
+        return child.equal?(parent.pattern)
+      end
+      return child.equal?(parent.rescue_expression) if parent.is_a?(Prism::RescueModifierNode)
+      return child.equal?(parent.right) if parent.is_a?(Prism::OrNode) || parent.is_a?(Prism::AndNode)
+      if parent.is_a?(Prism::CallNode) && parent.safe_navigation?
+        return child.equal?(parent.arguments) || child.equal?(parent.block)
+      end
+      # `a&.b += v` skips `v` when `a` is nil, like `a&.b ||= v`.
+      return true if parent.respond_to?(:safe_navigation?) && parent.safe_navigation? &&
+                     parent.respond_to?(:value) && child.equal?(parent.value)
+
+      parent.class.name.end_with?("OrWriteNode", "AndWriteNode") && child.equal?(parent.value)
+    end
+
+    # The nodes from `node` down to the deepest one that holds the offset. A
+    # heredoc body lies outside the node of its opener, so a child is searched
+    # even when its parent does not hold the offset.
+    #
+    # @param node [Prism::Node]
+    # @param offset [Integer] byte offset.
+    # @return [Array<Prism::Node>, nil] nil when no node in the subtree holds it.
+    def self.path_to(node, offset)
+      node.compact_child_nodes.each do |child|
+        path = path_to(child, offset)
+        return [node, *path] if path
+      end
+      location = node.location
+      [node] if location.start_offset <= offset && offset < location.end_offset
+    end
+
+    # The last line of `node` and its children. A heredoc body ends below the
+    # node of its opener.
+    #
+    # @param node [Prism::Node]
+    # @return [Integer]
+    def self.last_line(node)
+      [node.location.end_line, *node.compact_child_nodes.map { |child| last_line(child) }].max
+    end
+
+    # Whether `node` is a modifier whose body comes before its keyword, such
+    # as `x while c` or `x if c`. The body of `begin ... end while c` runs once
+    # before the check, so it is not.
+    #
+    # @param node [Prism::Node, nil] the parent of the body that holds the statement.
+    # @return [Boolean]
+    def self.modifier?(node)
+      keyword =
+        case node
+        when Prism::WhileNode, Prism::UntilNode then node.keyword_loc unless node.begin_modifier?
+        when Prism::IfNode then node.if_keyword_loc
+        when Prism::UnlessNode then node.keyword_loc
+        end
+      return false if keyword.nil? || node.statements.nil?
+
+      node.statements.location.start_offset < keyword.start_offset
+    end
+
+    # The text before `location` on its first line.
+    #
+    # @param source [String]
+    # @param location [Prism::Location]
+    # @return [String]
+    def self.before(source, location)
+      source.byteslice(location.start_offset - location.start_column, location.start_column)
+    end
+
+    # The text after `location` on its last line.
+    #
+    # @param source [String]
+    # @param location [Prism::Location]
+    # @return [String]
+    def self.after(source, location)
+      source.byteslice(location.end_offset, source.bytesize).each_line.first.to_s
+    end
+  end
+end

data/lib/mutineer/subject.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # One discoverable method and its AST node.
+  #
+  # Location, namespace context, and the live Prism::DefNode are kept together
+  # because mutators walk the def node directly. `namespace` names the owner
+  # (`module ::X` inside `Outer` owns into `X`); `lexical` is the class/module
+  # chain as written (`["Outer", "::X"]`), which the redefine strategy needs to
+  # rebuild the same Module.nesting as a whole-file reload (#145). `block_owner`
+  # is the constant a `Data.define`-style block is assigned to, as written;
+  # `owner_unknown` is true when the class that block builds cannot be named,
+  # so the redefine strategy cannot load a mutant onto it.
+  Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, :lexical, :block_owner, :owner_unknown,
+                       keyword_init: true) do
+    # Returns the fully-qualified subject name.
+    #
+    # @return [String] namespaced method name like `Billing::Invoice#total`.
+    def qualified_name
+      namespace.join("::") + (singleton ? "." : "#") + name.to_s
+    end
+
+    # Class/module chain as written in the source, for textual wrappers. Falls
+    # back to `namespace` for subjects built without one.
+    #
+    # @return [Array<String>] names; a root-anchored element keeps its `::`.
+    def lexical_namespace
+      lexical || namespace
+    end
+
+    # Returns the body location for the subject, if any.
+    #
+    # @return [Prism::Location, nil] body location or nil for empty methods.
+    def body_loc
+      def_node.body&.location
+    end
+  end
+end

data/lib/mutineer/test_runners/minitest.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "../minitest_integration"
+
+module Mutineer
+  module TestRunners
+    # Thin wrapper around the shared Minitest integration runner.
+    module Minitest
+      # Runs the given Minitest files.
+      #
+      # @param test_files [String, Array<String>] one file or many files.
+      # @param stop_at_first_failure [Boolean] when true, the run ends at the
+      #   first failing test.
+      # @param record_to [IO, nil] a `--matrix` run: send each test's outcome to
+      #   this channel and run every test.
+      # @return [Integer] 0 on success, 1 on failure.
+      def self.run(test_files, stop_at_first_failure: false, record_to: nil)
+        MinitestIntegration.run(test_files, stop_at_first_failure: stop_at_first_failure, record_to: record_to)
+      end
+    end
+  end
+end

data/lib/mutineer/test_runners/rspec.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../kill_channel"
+
+module Mutineer
+  # Raised when the target project asks for a framework whose gem isn't present.
+  # rspec is NOT a Mutineer dependency — it must come from the project's bundle.
+  class FrameworkUnavailable < StandardError; end
+
+  module TestRunners
+    # Child-process-only RSpec runner.
+    #
+    # Mirrors MinitestIntegration's contract: run the given spec files and
+    # return 0 (all passed) or 1 (any failure).
+    module RSpec
+      # Runs the given RSpec files.
+      #
+      # @param spec_files [String, Array<String>] one file or many files.
+      # @param stop_at_first_failure [Boolean] when true, the run ends at the
+      #   first failing example (RSpec `--fail-fast`).
+      # @param record_to [IO, nil] a `--matrix` run: send each example's outcome
+      #   to this channel (see {KillFormatter}) and run every example.
+      # @return [Integer] 0 on success, 1 on failure.
+      # @raise [ArgumentError] when both options are given: a matrix run never stops.
+      def self.run(spec_files, stop_at_first_failure: false, record_to: nil)
+        if stop_at_first_failure && record_to
+          raise ArgumentError, "stop_at_first_failure and record_to cannot be combined: a matrix run runs every example"
+        end
+
+        require_rspec!
+
+        ::RSpec::Core::Runner.disable_autorun!
+        # Not RSpec.reset: it also drops the settings that gems added when Bundler
+        # required them, such as rspec-retry's verbose_retry.
+        ::RSpec.clear_examples
+        # Added before the run reads its options, which leaves the reporter
+        # unbuilt, so the run's output stream still applies. With a formatter
+        # present, RSpec adds no default one; its output went to the sink anyway.
+        KillFormatter.last = nil
+        ::RSpec.configuration.add_formatter(KillFormatter.registered, record_to) if record_to
+
+        # The sink takes RSpec's own formatter output. Spec output is not
+        # silenced here: the fork boundary that calls this method has already
+        # pointed stdout at File::NULL (see ChildStdout).
+        sink = StringIO.new
+        keep_file_order(spec_files) if stop_at_first_failure || record_to
+        args = ["--no-color"]
+        args << "--fail-fast" if stop_at_first_failure
+        status = with_fail_fast_off(record_to) do
+          ::RSpec::Core::Runner.run([*args, *Array(spec_files)], sink, sink)
+        end
+        # Reached only when the suite returned: an example that exits the
+        # process skips it, and the parent then keeps the row incomplete. A
+        # return alone proves nothing: fail-fast turned on mid-run stops RSpec
+        # early, so `end` needs a reported outcome for every planned example.
+        KillChannel.write_end(record_to) if record_to && KillFormatter.last&.saw_every_example?
+
+        status.zero? ? 0 : 1
+      ensure
+        FileOrder.rank = nil
+      end
+
+      # Runs the top-level example groups in the order of `spec_files` (#203),
+      # after RSpec's own ordering, which then decides the order within a file.
+      #
+      # @api private
+      # @param spec_files [String, Array<String>] the files, in run order.
+      # @return [void]
+      def self.keep_file_order(spec_files)
+        FileOrder.rank = Array(spec_files).each_with_index.to_h { |f, i| [File.expand_path(f), i] }
+        ::RSpec::Core::World.prepend(FileOrder) unless ::RSpec::Core::World <= FileOrder
+      end
+
+      # Prepended on `RSpec::Core::World`: a stable sort of the ordered
+      # top-level groups by their file's position. Does nothing without a rank.
+      module FileOrder
+        class << self
+          # Each spec file's position, keyed by absolute path, or nil.
+          #
+          # @return [Hash{String => Integer}, nil]
+          attr_accessor :rank
+        end
+
+        # The groups RSpec ordered, sorted by file position.
+        #
+        # @return [Array<RSpec::Core::ExampleGroup>]
+        def ordered_example_groups
+          groups = super
+          rank = FileOrder.rank
+          return groups unless rank
+
+          groups.sort_by.with_index do |group, i|
+            file = group.metadata[:absolute_file_path] || File.expand_path(group.file_path)
+            [rank.fetch(file, rank.size), i]
+          end
+        end
+      end
+
+      # Runs the block with fail-fast forced off when `record_to` is set: a
+      # matrix run must run every example. RSpec reads options from .rspec, then
+      # the command line, then `SPEC_OPTS`, and the last one wins, so the option
+      # goes at the end of `SPEC_OPTS` (restored afterwards). A forced option
+      # also beats `config.fail_fast = true` in a spec helper.
+      #
+      # @api private
+      # @param record_to [IO, nil] the channel of a matrix run, or nil.
+      # @yieldreturn [Integer] RSpec's exit status.
+      # @return [Integer] the block's value.
+      def self.with_fail_fast_off(record_to)
+        return yield unless record_to
+
+        saved = ENV.fetch("SPEC_OPTS", nil)
+        ENV["SPEC_OPTS"] = [saved, "--no-fail-fast"].compact.join(" ")
+        begin
+          yield
+        ensure
+          ENV["SPEC_OPTS"] = saved
+        end
+      end
+
+      # Sends each example's outcome to the channel of a `--matrix` run. A
+      # pending or skipped example sends nothing. A test is its spec file, its
+      # full description (the name reports show) and its example id, which
+      # tells apart examples that share a description and stays the same when a
+      # mutant changes a generated description. Example ids need RSpec 3.3 or
+      # later; before that no id tells apart examples on one line, so an older
+      # RSpec sends no `start` and every row stays incomplete.
+      #
+      # It writes only from the process that created it, so an example that runs
+      # an RSpec suite in a forked process cannot add lines. It writes `start`
+      # when the run begins with fail-fast off; a run that could stop early sends
+      # no `start`, and its rows stay incomplete. It also registers an
+      # `after(:suite)` hook that writes `cleanup` ahead of the suite's own hooks.
+      #
+      # After the first failure, a run without `--matrix` (`--fail-fast`) skips
+      # each later example and each example group that starts later, hooks
+      # included, but it still runs the `after(:all)` hooks of the groups it is
+      # in. So once an example has failed, the formatter writes `skip` when a
+      # later example or group starts and `unskip` when it finishes (see
+      # {KillChannel}).
+      class KillFormatter
+        class << self
+          # The formatter of the latest run in this process.
+          #
+          # @return [KillFormatter, nil]
+          attr_accessor :last
+        end
+
+        # Registers the formatter with RSpec for the notifications it handles.
+        # Called at run time, because rspec-core is not loaded with Mutineer.
+        #
+        # @return [Class] this class.
+        def self.registered
+          ::RSpec::Core::Formatters.register(self, :start, :example_started, :example_passed, :example_failed,
+                                             :example_pending, :example_group_started, :example_group_finished)
+          self
+        end
+
+        # @param channel [IO] the write end of the channel.
+        def initialize(channel)
+          @channel = channel
+          @pid = Process.pid
+          @failed = false
+          @example_skipping = false
+          @groups_skipping = []
+          @planned = nil
+          @reported = 0
+          self.class.last = self
+        end
+
+        # True when RSpec reported an outcome for every example it planned to run.
+        #
+        # @return [Boolean]
+        def saw_every_example?
+          !@planned.nil? && @reported == @planned
+        end
+
+        # Sends `start`, unless fail-fast is on or RSpec has no example ids, and
+        # registers the hook that sends `cleanup`. RSpec runs `after(:suite)`
+        # hooks last-defined first, and this runs once the spec files have
+        # loaded, so the hook goes before every hook the suite defines.
+        #
+        # @param notification [RSpec::Core::Notifications::StartNotification]
+        # @return [void]
+        def start(notification)
+          return unless owner?
+          return if ::RSpec.configuration.fail_fast
+          return unless ::RSpec::Core::Example.method_defined?(:id)
+
+          @planned = notification.count
+          KillChannel.write_start(@channel)
+          formatter = self
+          ::RSpec.configuration.after(:suite) { formatter.cleanup_begins }
+        end
+
+        # Sends `cleanup`: every example has run, and the suite's own hooks follow.
+        #
+        # @return [void]
+        def cleanup_begins
+          KillChannel.write_cleanup(@channel) if owner?
+        end
+
+        # Opens a `skip` region for an example that starts after a failure.
+        #
+        # @param _notification [RSpec::Core::Notifications::ExampleNotification]
+        # @return [void]
+        def example_started(_notification)
+          return unless owner? && @failed
+
+          @example_skipping = true
+          KillChannel.write_skip(@channel)
+        end
+
+        # Sends a pass.
+        #
+        # @param notification [RSpec::Core::Notifications::ExampleNotification]
+        # @return [void]
+        def example_passed(notification)
+          send_event(KillChannel::PASS, notification.example)
+          example_finished
+        end
+
+        # Sends a kill.
+        #
+        # @param notification [RSpec::Core::Notifications::FailedExampleNotification]
+        # @return [void]
+        def example_failed(notification)
+          send_event(KillChannel::KILL, notification.example)
+          example_finished
+          @failed = true
+        end
+
+        # A pending or skipped example sends no test line, but it finishes.
+        #
+        # @param _notification [RSpec::Core::Notifications::ExampleNotification]
+        # @return [void]
+        def example_pending(_notification)
+          example_finished
+        end
+
+        # Opens a `skip` region for a group that starts after a failure.
+        #
+        # @param _notification [RSpec::Core::Notifications::GroupNotification]
+        # @return [void]
+        def example_group_started(_notification)
+          return unless owner?
+
+          # The exception in flight now: RSpec can start and finish a group
+          # inside its own `rescue` (a failed `before(:all)` with nested
+          # groups), where `$!` is already set.
+          @groups_skipping.push([@failed, $!])
+          KillChannel.write_skip(@channel) if @failed
+        end
+
+        # Closes the group's `skip` region, if it opened one. RSpec sends this
+        # after the group's `after(:all)` hooks, from an `ensure`, so it also
+        # comes while an exit or a crash unwinds the group. Then `$!` holds an
+        # exception that was not in flight when the group started, and the
+        # region stays open: the run ended inside it.
+        #
+        # @param _notification [RSpec::Core::Notifications::GroupNotification]
+        # @return [void]
+        def example_group_finished(_notification)
+          return unless owner?
+
+          opened, in_flight = @groups_skipping.pop
+          KillChannel.write_unskip(@channel) if opened && $!.equal?(in_flight)
+        end
+
+        private
+
+        # True in the process that created the formatter.
+        #
+        # @return [Boolean]
+        def owner?
+          Process.pid == @pid
+        end
+
+        # Counts an example's outcome and closes its `skip` region, if any.
+        #
+        # @return [void]
+        def example_finished
+          return unless owner?
+
+          @reported += 1
+          return unless @example_skipping
+
+          @example_skipping = false
+          KillChannel.write_unskip(@channel)
+        end
+
+        # Writes one test line for `example`.
+        #
+        # @param event [String] {KillChannel::PASS} or {KillChannel::KILL}.
+        # @param example [RSpec::Core::Example] the example.
+        # @return [void]
+        def send_event(event, example)
+          return unless owner?
+
+          file = example.metadata[:absolute_file_path] || File.expand_path(example.file_path)
+          KillChannel.write(@channel, event, file, example.full_description, identify(example))
+        rescue StandardError
+          # A recorder that raised would change the verdict; the lost line keeps the row incomplete.
+          KillChannel.write_lost(@channel)
+        end
+
+        # What tells `example` apart from the others, and stays the same across
+        # mutants: its id (RSpec 3.3 and later; see {#start}).
+        #
+        # @param example [RSpec::Core::Example] the example.
+        # @return [String]
+        def identify(example)
+          example.id
+        end
+      end
+
+      # Requires rspec-core from the project under test.
+      #
+      # @api private
+      def self.require_rspec!
+        require "rspec/core"
+      rescue LoadError
+        raise Mutineer::FrameworkUnavailable,
+              "framework 'rspec' requested but rspec is not available; " \
+              "add rspec to the project under test (its bundle), then retry"
+      end
+    end
+  end
+end

data/lib/mutineer/test_runners.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "test_runners/minitest"
+require_relative "test_runners/rspec"
+
+module Mutineer
+  # Picks the test-framework runner.
+  #
+  # Each runner responds to
+  # `.run(files, stop_at_first_failure: false, record_to: nil) -> 0/1`
+  # (0 = all passed, 1 = any failure) and is called only inside a forked child.
+  # Only the mutant path passes `stop_at_first_failure: true`; a `--matrix`
+  # mutant run passes `record_to:` instead (a {KillChannel} pipe) and runs every
+  # test. The fork boundary silences stdout (see ChildStdout); the runners do not.
+  module TestRunners
+    # Returns the runner module for a framework name.
+    #
+    # @param framework [String, nil] framework name or nil.
+    # @return [Module] `Mutineer::TestRunners::Minitest` or `::RSpec`.
+    # @raise [Mutineer::ConfigError] when the framework is unknown.
+    def self.for(framework)
+      case framework
+      when "rspec" then RSpec
+      when "minitest", nil, "" then Minitest
+      else
+        raise Mutineer::ConfigError, "unknown framework #{framework.inspect} (expected: minitest, rspec)"
+      end
+    end
+  end
+end

data/lib/mutineer/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Current Mutineer release version.
+  VERSION = "2.0.0"
+end