mutineer 0.6.2 → 0.8.0

data/lib/mutineer/runner.rb

@@ -10,6 +10,8 @@ require_relative "coverage_map"
 require_relative "changed_lines"
 require_relative "mutator_registry"
 require_relative "worker_pool"
+require_relative "mutant_id"
+require "set"
 
 module Mutineer
   # Orchestrates one mutation end-to-end: apply it textually, validate the
@@ -30,6 +32,9 @@ module Mutineer
     # The parent process `require`s each source file so its classes exist; forked
     # children inherit them, so a covering test file's own require_relative of the
     # source is a no-op and does not clobber the mutated `load` (spec §7).
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @return [Array(Mutineer::AggregateResult, Hash<String, String>)] aggregate and source map.
     def self.execute(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
 
@@ -70,7 +75,8 @@ module Mutineer
           source_paths: config.sources, test_paths: config.tests,
           cache_dir: config.cache_dir, project_root: config.project_root,
           load_paths: config.load_paths, framework: config.framework,
-          boot_path: File.expand_path(config.boot, config.project_root)
+          boot_path: File.expand_path(config.boot, config.project_root),
+          verbose: config.verbose
         ).build_via_fork(rails: config.rails)
       else
         coverage_map = CoverageMap.new(
@@ -81,13 +87,28 @@ module Mutineer
       end
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
+      # #10: a mutant the user marked known-equivalent (inline disable-line comment
+      # or .mutineer.yml ignore id) is classified :ignored here and NEVER forked —
+      # it is removed from the killed+survived denominator so a strong file reaches
+      # 100%. The stable id is computed per subject (occurrence needs the full list)
+      # and carried on every job so the parent can reattach it after the run.
       source_map = {}
+      disabled_map = {}
+      ignore_set = config.ignore.to_set
       jobs = []
+      ignored_results = []
       Project.discover(config.sources, only: config.only).each do |subject|
         source = (source_map[subject.file] ||= File.read(subject.file))
-        operator_classes.each do |klass|
-          klass.new.mutations_for(subject, source).each do |mutation|
-            jobs << [subject, mutation]
+        disabled = (disabled_map[subject.file] ||= suppress_map(source))
+        mutations = operator_classes.flat_map { |klass| klass.new.mutations_for(subject, source) }
+        ids = MutantId.for_subject(subject, source, mutations)
+        mutations.each_with_index do |mutation, i|
+          id = ids[i]
+          line = source.byteslice(0, mutation.start_offset).count("\n") + 1
+          if suppressed?(mutation.operator, line, id, disabled, ignore_set)
+            ignored_results << Result.ignored.with(subject: subject, mutation: mutation, id: id)
+          else
+            jobs << [subject, mutation, id]
           end
         end
       end
@@ -111,13 +132,42 @@ module Mutineer
                 subject: subject, strategy: strategy, rails: config.rails, framework: framework)
           end
           # The bare Results carry only status (Subjects hold live AST nodes that
-          # do not marshal); reattach subject+mutation in the parent, in order.
-          bare.each_with_index.map { |r, i| r.with(subject: jobs[i][0], mutation: jobs[i][1]) }
+          # do not marshal); reattach subject+mutation+id in the parent, in order.
+          bare.each_with_index.map { |r, i| r.with(subject: jobs[i][0], mutation: jobs[i][1], id: jobs[i][2]) }
         ensure
           sweep_orphans(source_dirs)
         end
 
-      [AggregateResult.new(results), source_map]
+      [AggregateResult.new(results + ignored_results), source_map]
+    end
+
+    # Scan a source once into { line_number => :all | Set[operator_syms] } from
+    # inline `# mutineer:disable-line [ops]` markers (RuboCop semantics: the marker
+    # sits on the same physical line as the code it silences). A bare marker
+    # disables every operator on that line; `disable-line a, b` only the listed
+    # operators. Block-form disable/enable ranges are intentionally not supported.
+    def self.suppress_map(source)
+      map = {}
+      source.each_line.with_index(1) do |text, line|
+        next unless (m = text.match(/#\s*mutineer:disable-line(?:\s+([\w,\s]+))?/))
+
+        ops = m[1]
+        map[line] = ops ? ops.split(",").map { |o| o.strip.to_sym }.reject(&:empty?).to_set : :all
+      end
+      map
+    end
+
+    # True when this mutant is suppressed: its line bears a disable-line marker
+    # (bare, or scoped to its operator), OR its stable id is in the config ignore
+    # list. Checked at job-build time so a suppressed mutant is never forked.
+    def self.suppressed?(operator, line, id, disabled, ignore_set)
+      return true if ignore_set.include?(id)
+
+      case (entry = disabled[line])
+      when :all then true
+      when Set  then entry.include?(operator)
+      else false
+      end
     end
 
     # --since: keep only jobs whose mutation lands on a line changed since the git
@@ -168,6 +218,11 @@ module Mutineer
       warn "[mutineer] RAILS_ENV was unset; defaulting to 'test' for --rails."
     end
 
+    # Removes stale mutant tempfiles from the given directories.
+    #
+    # @api private
+    # @param dirs [Array<String>] directories to sweep.
+    # @return [void]
     def self.sweep_orphans(dirs)
       dirs.each do |dir|
         Dir.glob(File.join(dir, "mutineer_mutant*.rb")).each do |f|
@@ -176,6 +231,17 @@ module Mutineer
       end
     end
 
+    # Runs a single mutation through isolation.
+    #
+    # @param mutation [Mutineer::Mutation] mutation to run.
+    # @param source_file [String] source file path.
+    # @param coverage_map [Mutineer::CoverageMap, nil] coverage map.
+    # @param subject [Mutineer::Subject, nil] subject for surgical strategy.
+    # @param strategy [String] mutation strategy.
+    # @param timeout [Integer] child timeout in seconds.
+    # @param rails [Boolean] whether Rails reconnect handling is enabled.
+    # @param framework [String] test framework name.
+    # @return [Mutineer::Result] mutant result.
     def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
                  timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest")
       source  = File.read(source_file)
@@ -189,7 +255,11 @@ module Mutineer
       # covering test files run in the child.
       line   = source.byteslice(0, mutation.start_offset).count("\n") + 1
       chosen = coverage_map.tests_for(source_file, line)
-      return Result.no_coverage if chosen.empty?
+      # #9: distinguish a genuine coverage gap from a line whose would-be test
+      # errored during capture (coverage lost) — the latter is :uncapturable.
+      if chosen.empty?
+        return coverage_map.uncapturable_source?(source_file) ? Result.uncapturable : Result.no_coverage
+      end
 
       abs_tests = chosen.map { |t| File.expand_path(t, coverage_map.project_root) }
 
@@ -206,13 +276,35 @@ module Mutineer
       end
     end
 
+    # Reconnects ActiveRecord in a forked child when available.
+    #
+    # @api private
+    # @return [void]
     def self.reconnect_active_record
       return unless defined?(ActiveRecord::Base)
 
-      ActiveRecord::Base.connection_handler.clear_all_connections!
+      base = ActiveRecord::Base
+      # #8: clearing connections here drops an open transactional-fixture
+      # transaction, so the test loses its fixture rows and fails. Skip the clear
+      # when a transaction is open; otherwise clear (v0.2 per-fork write-safety).
+      return if fixture_transaction_open?(base)
+
+      base.connection_handler.clear_all_connections!
     rescue StandardError
       nil
     end
     private_class_method :reconnect_active_record
+
+    # Pure, injectable predicate: true when a transactional-fixture transaction is
+    # already open on the connection. Keys off open_transactions (KTD-2) so it is
+    # correct whenever the transaction exists, regardless of when it opened. Any
+    # probe error degrades safe to false -> caller clears (existing behaviour).
+    def self.fixture_transaction_open?(base)
+      pool = base.connection_pool
+      pool.active_connection? && base.connection.open_transactions.positive?
+    rescue StandardError
+      false
+    end
+    private_class_method :fixture_transaction_open?
   end
 end

data/lib/mutineer/subject.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # One discoverable method: its location, namespace context, and the live
-  # Prism::DefNode mutators walk. Struct (not Data) because def_node is a live
-  # AST node — value-equality would be hollow, so we don't promise it.
+  # 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.
   Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, keyword_init: true) do
-    # e.g. "Billing::Invoice#total", "Billing::Invoice.build".
-    # Top-level (empty namespace) -> "#name" (no :: prefix).
+    # 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
 
-    # nil for empty methods (def empty; 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

data/lib/mutineer/test_runners/minitest.rb

@@ -4,11 +4,12 @@ require_relative "../minitest_integration"
 
 module Mutineer
   module TestRunners
-    # Uniform wrapper over the existing MinitestIntegration impl so the runner
-    # selection (TestRunners.for) has one method shape across frameworks.
-    # MinitestIntegration stays the implementation — all its behaviour (autorun
-    # neutralisation, Runnable.reset, load, Minitest.run -> 0/1) is preserved.
+    # 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.
+      # @return [Integer] 0 on success, 1 on failure.
       def self.run(test_files) = MinitestIntegration.run(test_files)
     end
   end

data/lib/mutineer/test_runners/rspec.rb

@@ -8,31 +8,21 @@ module Mutineer
   class FrameworkUnavailable < StandardError; end
 
   module TestRunners
-    # Child-process-only RSpec runner, mirroring MinitestIntegration's contract:
-    # run the given spec files and return 0 (all passed) / 1 (any failure).
+    # Child-process-only RSpec runner.
     #
-    # rspec-core is required LAZILY here, never at load time, so Mutineer keeps
-    # zero runtime gem deps; a missing rspec raises a clear Mutineer error.
-    #
-    # No `rescue` around the run itself: Isolation.run's fork block is the single
-    # exception boundary (any exception there -> exit 2), keeping the 0/1 contract.
+    # Mirrors MinitestIntegration's contract: run the given spec files and
+    # return 0 (all passed) or 1 (any failure).
     module RSpec
-      # `spec_files` is one path or an Array of paths (coverage selection passes
-      # the covering subset). All are loaded+run in a single RSpec invocation.
+      # Runs the given RSpec files.
+      #
+      # @param spec_files [String, Array<String>] one file or many files.
+      # @return [Integer] 0 on success, 1 on failure.
       def self.run(spec_files)
         require_rspec!
 
-        # rspec/autorun (if a spec_helper required it) installs an at_exit run;
-        # neutralise it like Minitest.autorun so it never double-fires.
         ::RSpec::Core::Runner.disable_autorun!
-
-        # Drop any RSpec world/configuration inherited across runs in one process
-        # (e.g. successive forks of a booted parent) so examples never accumulate.
         ::RSpec.reset
 
-        # Silence RSpec's formatter output (and any stray puts/deprecations) so it
-        # never pollutes Mutineer's report streams. The formatter writes to the
-        # passed IO; $stdout/$stderr are redirected to catch everything else.
         sink = StringIO.new
         orig_out = $stdout
         orig_err = $stderr
@@ -48,6 +38,9 @@ module Mutineer
         status.zero? ? 0 : 1
       end
 
+      # Requires rspec-core from the project under test.
+      #
+      # @api private
       def self.require_rspec!
         require "rspec/core"
       rescue LoadError

data/lib/mutineer/test_runners.rb

@@ -4,9 +4,16 @@ require_relative "test_runners/minitest"
 require_relative "test_runners/rspec"
 
 module Mutineer
-  # Picks the test-framework runner. Each runner responds to `.run(files) -> 0/1`
-  # (0 = all passed, 1 = any failure) and is called only inside a forked child.
+  # Picks the test-framework runner.
+  #
+  # Each runner responds to `.run(files) -> 0/1` (0 = all passed, 1 = any
+  # failure) and is called only inside a forked child.
   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

data/lib/mutineer/version.rb

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

data/lib/mutineer/worker_pool.rb

@@ -3,21 +3,30 @@
 require_relative "result"
 
 module Mutineer
-  # Fixed-size fork pool (KTD1/KTD2). `run` forks up to `size` children at once;
-  # each child runs the block on one work item, marshals its Result to a private
-  # pipe, and exits. The parent reaps any finished child with Process.wait2(-1),
-  # opening exactly one slot per reap, then refills. Results are returned in the
-  # SAME ORDER as `items` regardless of finish order, so verdicts are identical to
-  # a serial run (R4) and downstream output is stable.
+  # Fixed-size fork pool (KTD1/KTD2). `run` forks up to `size` children at
+  # once; each child runs the block on one work item, marshals its Result to a
+  # private pipe, and exits. The parent reaps any finished child with
+  # Process.wait2(-1), opening exactly one slot per reap, then refills.
+  # Results are returned in the SAME ORDER as `items` regardless of finish
+  # order, so verdicts are identical to a serial run (R4) and downstream output
+  # is stable.
   #
   # The block is run inside the child via `yield(*items[i])`; whatever it
-  # returns (a Result) is the marshaled payload. Per-mutant timeout is handled one
-  # level down by Isolation (KTD2) — the pool adds no separate wall clock.
+  # returns (a Result) is the marshaled payload. Per-mutant timeout is handled
+  # one level down by Isolation (KTD2) — the pool adds no separate wall clock.
   class WorkerPool
+    # Builds a pool.
+    #
+    # @param size [Integer] desired pool size.
     def initialize(size)
       @size = [size.to_i, 1].max
     end
 
+    # Runs the work items through the pool.
+    #
+    # @param items [Array<Array>] work items.
+    # @yieldparam item [Array] one work item.
+    # @return [Array<Mutineer::Result>] results in input order.
     def run(items)
       results = Array.new(items.size)
       queue   = (0...items.size).to_a
@@ -33,17 +42,19 @@ module Mutineer
 
     private
 
+    # R1: the child must ALWAYS hard-exit. If yield raises, marshal an error
+    # Result and exit! in `ensure` — otherwise the child unwinds normally and
+    # our Minitest at_exit autorun re-runs the parent suite inside the worker,
+    # losing the real error.
     def fill(items, queue, running)
       while running.size < @size && !queue.empty?
         idx = queue.shift
         rd, wr = IO.pipe
+        rd.binmode # #19: Marshal output is binary — keep the pipe byte-exact
+        wr.binmode
         begin
           pid = fork do
             rd.close
-            # R1: the child must ALWAYS hard-exit. If yield raises, marshal an
-            # error Result and exit! in `ensure` — otherwise the child unwinds
-            # normally and our Minitest at_exit autorun re-runs the parent suite
-            # inside the worker, losing the real error.
             payload =
               begin
                 yield(*items[idx])
@@ -74,13 +85,13 @@ module Mutineer
       end
     end
 
-    # Drain pipes with IO.select and reap a child only on EOF (#4). The old code
-    # reaped first and read after — but a child whose payload exceeds the OS pipe
-    # buffer (~64KB) blocks on `write` before it can exit, so it was never reaped
-    # and the pool deadlocked. Reading concurrently keeps the pipe drained so the
-    # child can finish and exit; EOF means it closed its write end (done writing).
-    # We waitpid only OUR known pids (R6: never wait2(-1), which would steal the
-    # host suite's children).
+    # Drain pipes with IO.select and reap a child only on EOF (#4). The old
+    # code reaped first and read after — but a child whose payload exceeds the
+    # OS pipe buffer (~64KB) blocks on `write` before it can exit, so it was
+    # never reaped and the pool deadlocked. Reading concurrently keeps the
+    # pipe drained so the child can finish and exit; EOF means it closed its
+    # write end (done writing). We waitpid only OUR known pids (R6: never
+    # wait2(-1), which would steal the host suite's children).
     def reap(results, running)
       return if running.empty?
 
@@ -104,11 +115,13 @@ module Mutineer
       end
     end
 
+    # R6: a partial/garbage Marshal stream (dead worker) must not crash the
+    # pool — degrade to an error Result.
+    # @param data [String] marshaled payload.
+    # @return [Mutineer::Result] decoded result or error result.
     def decode(data)
       return Result.error("worker produced no result") if data.empty?
 
-      # R6: a partial/garbage Marshal stream (dead worker) must not crash the
-      # pool — degrade to an error Result.
       Marshal.load(data)
     rescue StandardError => e
       Result.error("worker result unreadable: #{e.class}: #{e.message}")

data/lib/mutineer.rb

@@ -6,6 +6,7 @@ require_relative "mutineer/parser"
 require_relative "mutineer/subject"
 require_relative "mutineer/mutation"
 require_relative "mutineer/project"
+require_relative "mutineer/pairing"
 require_relative "mutineer/result"
 require_relative "mutineer/coverage_map"
 require_relative "mutineer/changed_lines"
@@ -25,7 +26,9 @@ require_relative "mutineer/mutator_registry"
 require_relative "mutineer/worker_pool"
 require_relative "mutineer/runner"
 require_relative "mutineer/reporter"
+require_relative "mutineer/baseline"
 require_relative "mutineer/cli"
 
+# Mutineer is the top-level namespace for the mutation-testing library.
 module Mutineer
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.8.0
 platform: ruby
 authors:
 - David Teren
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Mutineer mutates your source one change at a time and runs your Minitest
   suite against each mutant to find tests that don't actually test anything. Prism-based,
   fork-isolated, zero runtime dependencies.
@@ -52,12 +66,14 @@ files:
 - README.md
 - bin/mutineer
 - lib/mutineer.rb
+- lib/mutineer/baseline.rb
 - lib/mutineer/changed_lines.rb
 - lib/mutineer/cli.rb
 - lib/mutineer/config.rb
 - lib/mutineer/coverage_map.rb
 - lib/mutineer/isolation.rb
 - lib/mutineer/minitest_integration.rb
+- lib/mutineer/mutant_id.rb
 - lib/mutineer/mutation.rb
 - lib/mutineer/mutator_registry.rb
 - lib/mutineer/mutators/arithmetic.rb
@@ -69,6 +85,7 @@ files:
 - lib/mutineer/mutators/literal_mutation.rb
 - lib/mutineer/mutators/return_nil.rb
 - lib/mutineer/mutators/statement_removal.rb
+- lib/mutineer/pairing.rb
 - lib/mutineer/parser.rb
 - lib/mutineer/project.rb
 - lib/mutineer/reporter.rb