mutineer 0.2.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4020e2cd0e53ac4f406998d2c251d26abee9f75c4e6ceef365f2ffe565be50ab
-  data.tar.gz: f42dbc71077fc802b56f878e27885568f3d128f244875fb678dede5f6940f385
+  metadata.gz: 88e7dbea9ba80b3fed23d634e30830372c89e2f42cf7403d8fa5860d80ba17dd
+  data.tar.gz: ac519c7e8c6e301e46242af5bd6a94672aa0a95f2d8dc46dfbd5e3b2611c366c
 SHA512:
-  metadata.gz: dc24bb60419b7d701a85a09c70495c9d9d7ce2cd2d5b5a10621cb03a940276c3526dc650ee4deb7f93529e09b67b872777c2483419979d5740a83aa9ac9bfd26
-  data.tar.gz: ff59317a64ab0e3478c7dde381ac9752b56c83920d1a63bcf6528ac826f286d787b2d560c1946e897790bd47325ac2209d22b537e3baa146b90f2bedcd2f0c72
+  metadata.gz: 5e49d3e6fef7dddc74b93c6e1216a5740e556f0c9b1ba1d684cc28b61c3f464063669ad04468dc0d0882a1a141050d62c96e6f9995b8b0e541f38e94d9fbac7a
+  data.tar.gz: d70b8231caef83f5b55a9ee840cb77cdf16b8c93c8f227d7f278266db44584577eb17ca589eba677d3896dceae03b8e71a43f8b7747f7046060aa659d9b55d58

data/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.6.1] - 2026-06-29
+
+### Changed
+- **Removed `eval` entirely** — the redefine strategy now `load`s the wrapped
+  method snippet from a tempfile instead of evaluating a string. Behavior is
+  identical (top-level load rebuilds the same `Module.nesting`), but the gem no
+  longer uses dynamic string execution, clearing supply-chain scanner flags.
+  Zero runtime dependencies unchanged.
+
+## [0.6.0] - 2026-06-28
+
+### Added
+- **RSpec support** (#6) — `--framework rspec` (or auto-detected when most
+  `--test` files end in `_spec.rb`) runs RSpec suites instead of Minitest, via a
+  pluggable test-runner abstraction. Both frameworks are loaded lazily, so
+  Mutineer keeps zero runtime gem dependencies and works in an rspec-only
+  project; coverage selection works for both. `.mutineer.yml` accepts `framework:`.
+
+### Fixed
+- **Redefine strategy keeps compact `class A::B` as a single nesting wrapper**
+  (#5) — avoids a constant-resolution disagreement with the reload strategy.
+
+## [0.5.0] - 2026-06-28
+
+### Fixed
+- **`class << self` methods are now discovered and mutated** (#3) — previously
+  they were treated as instance methods, so the redefine strategy mis-targeted
+  them. `class << other_obj` blocks are skipped (not representable).
+- **Worker pool no longer deadlocks on large results** (#4) — pipes are drained
+  with `IO.select` and children reaped on EOF, so a result bigger than the OS
+  pipe buffer (~64KB) can't wedge the run.
+
+## [0.4.0] - 2026-06-28
+
+### Added
+- **`--since <git-ref>`** (#2) — mutate only the lines changed since a git ref
+  (e.g. `--since origin/main`), so CI on a pull request mutation-tests just the
+  new/changed code. Composes with coverage selection; `--dry-run --since`
+  narrows the preview too. Unknown ref / not-a-git-repo exits 2.
+
+## [0.3.0] - 2026-06-28
+
+### Added
+- **Coverage-guided test selection in boot mode** (#1) — `--rails`/`--boot` now
+  captures coverage by forking the booted app and runs only the test files that
+  cover each mutant's line (uncovered lines report `no_coverage`), instead of
+  running every `--test` file for every mutant. Cached like standalone mode.
+
 ## [0.2.0] - 2026-06-28
 
 ### Added
@@ -38,5 +86,10 @@ All notable changes to this project are documented here. The format is based on
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[0.6.1]: https://github.com/davidteren/mutineer/releases/tag/v0.6.1
+[0.6.0]: https://github.com/davidteren/mutineer/releases/tag/v0.6.0
+[0.5.0]: https://github.com/davidteren/mutineer/releases/tag/v0.5.0
+[0.4.0]: https://github.com/davidteren/mutineer/releases/tag/v0.4.0
+[0.3.0]: https://github.com/davidteren/mutineer/releases/tag/v0.3.0
 [0.2.0]: https://github.com/davidteren/mutineer/releases/tag/v0.2.0
 [0.1.0]: https://github.com/davidteren/mutineer/releases/tag/v0.1.0

data/README.md

@@ -1,7 +1,7 @@
 # Mutineer
 
 A clean-room mutation-testing tool for Ruby. Mutineer mutates your source one
-change at a time, runs your Minitest suite against each mutant, and reports the
+change at a time, runs your test suite (Minitest or RSpec) against each mutant, and reports the
 ones your tests failed to catch — the gaps where your suite isn't actually
 testing anything.
 
@@ -45,6 +45,8 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | `--operators LIST` | Comma-separated operator names (default: the Tier-1 set) |
 | `--threshold FLOAT` | Exit 1 when the score is below FLOAT (default: 0 = off) |
 | `--only NAME` | Restrict to one fully-qualified subject, e.g. `Calculator#add` |
+| `--framework NAME` | `minitest` (default) or `rspec`; auto-detected as rspec when most `--test` files end in `_spec.rb` |
+| `--since REF` | Only mutate lines changed since git `REF` (e.g. `origin/main`) — ideal for PR CI |
 | `--jobs N` | Parallel worker count (default: processor count) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
 | `--format human\|json` | Report format (default: human) |
@@ -82,9 +84,9 @@ RAILS_ENV=test bundle exec mutineer run \
 then forks and inherits it), defaults `--strategy` to `redefine` (surgical — it
 avoids reloading files into the app tree), and reconnects ActiveRecord in each
 fork so the database connection is fork-safe. Use `--boot FILE` to boot a
-different entry point. Boot mode requires at least one `--test` file and runs
-those tests for every mutant (coverage-guided selection is not yet available in
-boot mode).
+different entry point. Boot mode requires at least one `--test` file and is
+coverage-guided — each mutant runs only the test files that exercise its line
+(coverage is captured by forking the booted app, then cached).
 
 Add Mutineer to your Gemfile's test group:
 

data/lib/mutineer/changed_lines.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "set"
+require "open3"
+
+module Mutineer
+  # Maps each source file to the set of NEW-side line numbers that changed since a
+  # given git ref, by parsing `git diff --unified=0`. Used to restrict mutations
+  # to only the diff (issue #2): on a PR you care whether the changed code is
+  # tested, so mutating just those lines is fast and actionable.
+  #
+  # git is an external tool, not a gem dependency — shelling out is fine. The pure
+  # `parse` carries the logic; `git_diff` is injectable so it stays testable
+  # without invoking git.
+  module ChangedLines
+    HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/
+
+    module_function
+
+    # Parse `git diff --unified=0` output into the set of NEW-side line numbers
+    # added/modified. With --unified=0 each hunk's `+c,d` block is exactly the
+    # changed lines: c..c+d-1. `d` absent means 1 line; `d == 0` is a pure
+    # deletion and contributes nothing.
+    def parse(diff_text)
+      lines = Set.new
+      diff_text.each_line do |row|
+        m = HUNK.match(row) or next
+        start = m[1].to_i
+        count = m[2].nil? ? 1 : m[2].to_i
+        next if count.zero?
+
+        lines.merge(start...(start + count))
+      end
+      lines
+    end
+
+    # { absolute_file_path => Set<Integer> } of changed new-side lines per file.
+    # `runner` is injected so tests can supply canned diff text per file.
+    def for(ref:, files:, project_root:, runner: method(:git_diff))
+      files.each_with_object({}) do |file, acc|
+        abs = File.expand_path(file, project_root)
+        acc[abs] = parse(runner.call(ref, abs, project_root))
+      end
+    end
+
+    # stdout of `git -C <root> diff --unified=0 <ref> -- <file>`, "" on failure.
+    def git_diff(ref, abs_file, project_root)
+      out, _err, status = Open3.capture3(
+        "git", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file
+      )
+      status.success? ? out : ""
+    rescue StandardError
+      ""
+    end
+  end
+end

data/lib/mutineer/cli.rb

@@ -2,10 +2,12 @@
 
 require "optparse"
 require "set"
+require "open3"
 require_relative "version"
 require_relative "config"
 require_relative "parser"
 require_relative "project"
+require_relative "changed_lines"
 require_relative "runner"
 require_relative "reporter"
 require_relative "mutator_registry"
@@ -32,10 +34,12 @@ module Mutineer
         --operators LIST     Comma-separated operator names (default: Tier 1 set)
         --threshold FLOAT    Fail (exit 1) when score < FLOAT (default: 0 = off)
         --only NAME          Restrict to one fully-qualified subject
+        --since REF          Only mutate lines changed since git REF (e.g. origin/main)
         --jobs N             Parallel worker count (default: processor count)
         --strategy NAME      reload (whole-file) or redefine (surgical); default: reload
+        --framework NAME     minitest or rspec (default: auto-detect from --test names)
         --boot FILE          Require FILE once in the parent to boot the app env, then
-                             fork per mutant (Rails apps; requires --test, no coverage)
+                             fork per mutant (Rails apps; requires --test)
         --rails              Sugar for --boot config/environment --strategy redefine
         --format human|json  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
@@ -71,11 +75,13 @@ module Mutineer
         o.on("--list-operators") { show_operators = true }
         o.on("--dry-run") { opts[:dry_run] = true }
         o.on("--only NAME") { |v| opts[:only] = v; explicit << :only }
+        o.on("--since REF") { |v| opts[:since] = v; explicit << :since }
         o.on("--test FILE") { |v| (opts[:tests] ||= []) << v }
         o.on("--operators LIST") { |v| opts[:operators] = v.split(",").map(&:strip); explicit << :operators }
         o.on("--threshold FLOAT") { |v| opts[:threshold] = v.to_f; explicit << :threshold }
         o.on("--jobs N") { |v| opts[:jobs] = v; explicit << :jobs }
         o.on("--strategy STRAT") { |v| opts[:strategy] = v; explicit << :strategy }
+        o.on("--framework NAME") { |v| opts[:framework] = v; explicit << :framework }
         o.on("--boot FILE") { |v| opts[:boot] = v; explicit << :boot }
         o.on("--rails") { opts[:rails] = true }
         o.on("--format FORMAT") { |v| opts[:format] = v }
@@ -183,6 +189,11 @@ module Mutineer
         exit 2
       end
 
+      unless %w[minitest rspec].include?(config.framework)
+        warn %(mutineer: unknown framework "#{config.framework}". Expected: minitest, rspec)
+        exit 2
+      end
+
       # Boot mode does no coverage selection — every mutant runs the given tests —
       # so at least one --test file is mandatory (there is nothing to select from).
       if config.boot && config.tests.empty?
@@ -190,10 +201,31 @@ module Mutineer
         exit 2
       end
 
+      validate_since!(config) if config.since
       preflight_output!(config.output) if config.output
       validate_paths!(config)
     end
 
+    # --since needs a real git repo and a resolvable ref; either failure is a
+    # usage error (exit 2) so CI sees "bad invocation," not "tests too weak."
+    def self.validate_since!(config)
+      _out, _err, status = Open3.capture3(
+        "git", "-C", config.project_root, "rev-parse", "--verify", "--quiet",
+        "#{config.since}^{commit}"
+      )
+      return if status.success?
+
+      inside, = Open3.capture3(
+        "git", "-C", config.project_root, "rev-parse", "--is-inside-work-tree"
+      )
+      msg = inside.strip == "true" ? "unknown git ref: #{config.since}" : "--since requires a git repository"
+      warn "mutineer: #{msg}"
+      exit 2
+    rescue Errno::ENOENT
+      warn "mutineer: --since requires git on PATH"
+      exit 2
+    end
+
     # R5: validate path existence up front so a typo is a clean usage error (exit
     # 2), not an Errno::ENOENT backtrace from deep in the run. Flag checks run
     # first so a bad flag still reports the flag, not the missing file.
@@ -234,6 +266,13 @@ module Mutineer
       per_operator = Hash.new(0)
       skipped = 0
 
+      # --since narrows the preview to changed lines too, so `--dry-run --since`
+      # shows exactly what a real `--since` run would mutate.
+      changed = if config.since
+                  ChangedLines.for(ref: config.since, files: config.sources,
+                                   project_root: config.project_root)
+                end
+
       Project.discover(config.sources, only: config.only).each do |subject|
         source = (sources[subject.file] ||= Parser.parse_file(subject.file).source.source)
         operator_classes.each do |klass|
@@ -242,6 +281,10 @@ module Mutineer
               skipped += 1
               next
             end
+            if changed
+              line = source.byteslice(0, mutation.start_offset).count("\n") + 1
+              next unless changed[File.expand_path(subject.file, config.project_root)]&.include?(line)
+            end
             per_operator[mutation.operator] += 1
             original = source.byteslice(mutation.start_offset...mutation.end_offset)
             line = source.byteslice(0, mutation.start_offset).count("\n") + 1

data/lib/mutineer/config.rb

@@ -24,12 +24,12 @@ module Mutineer
     :sources, :tests, :operators, :threshold, :only, :dry_run,
     :cache_dir, :project_root, :load_paths,
     :jobs, :format, :output, :strategy, :require_paths,
-    :boot, :rails,
+    :boot, :rails, :since, :framework,
     keyword_init: true
   ) do
     CONFIG_FILE = ".mutineer.yml"
     # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
-    KNOWN_KEYS = %w[operators jobs threshold only require boot rails].freeze
+    KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework].freeze
 
     def initialize(**kwargs)
       super
@@ -109,9 +109,22 @@ module Mutineer
         config.boot ||= "config/environment"
         config.strategy = "redefine" unless explicit.include?(:strategy)
       end
+
+      # Auto-detect the framework only when neither CLI nor config file set it
+      # (explicit value, from either source, is already on config.framework and
+      # always wins). Default minitest unless the test files clearly look RSpec.
+      config.framework ||= detect_framework(config.tests)
       config
     end
 
+    # Pick rspec when a MAJORITY of the given test files end with _spec.rb;
+    # otherwise minitest. Empty/ambiguous -> minitest (the safe default).
+    def self.detect_framework(tests)
+      tests = Array(tests)
+      specs = tests.count { |t| t.to_s.end_with?("_spec.rb") }
+      specs > tests.length / 2.0 ? "rspec" : "minitest"
+    end
+
     def self.field_for(known_key)
       known_key == "require" ? :require_paths : known_key.to_sym
     end
@@ -123,6 +136,7 @@ module Mutineer
       when "threshold" then value.to_f
       when "require"   then Array(value).map(&:to_s)
       when "boot"      then value.to_s
+      when "framework" then value.to_s
       when "rails"     then value == true || value.to_s == "true"
       else value
       end

data/lib/mutineer/coverage_map.rb

@@ -5,6 +5,9 @@ require "json"
 require "digest"
 require "fileutils"
 require "rbconfig"
+require "coverage"
+require_relative "minitest_integration"
+require_relative "test_runners"
 
 module Mutineer
   # Maps `(source_file, line) -> [test_files]` so each mutant runs only against
@@ -21,24 +24,52 @@ module Mutineer
 
     def initialize(source_paths:, test_paths:, cache_dir: ".mutineer",
                    load_paths: ["lib"], project_root: Dir.pwd,
-                   capture_timeout: DEFAULT_CAPTURE_TIMEOUT)
+                   capture_timeout: DEFAULT_CAPTURE_TIMEOUT, boot_path: nil,
+                   framework: "minitest")
       @source_paths = Array(source_paths)
       @test_paths   = Array(test_paths)
       @cache_dir    = cache_dir
       @load_paths   = Array(load_paths)
       @project_root = project_root
       @capture_timeout = capture_timeout
+      @boot_path    = boot_path
+      @framework    = framework || "minitest"
       @map          = {}
       @failed_test_files = []
       @phase_a_ran  = false
     end
 
-    # Phase A entry point: load the cached map when the content digest matches,
-    # otherwise rebuild from subprocesses and overwrite the cache.
+    # Phase A entry point (standalone): load the cached map when the content
+    # digest matches, otherwise rebuild from subprocesses and overwrite the cache.
     def build_or_load
       warn_external_sources
-      @digest = compute_digest
+      cached_or { run_phase_a }
+    end
+
+    # Boot-mode Phase A: Coverage is already running in the parent (started before
+    # the app booted, so booted source lines are instrumented). A clean `ruby`
+    # subprocess has no booted env, so per-test coverage is captured by FORKING
+    # the booted parent instead. Inverts into the same map #tests_for reads, and
+    # reuses the digest cache (the digest mixes in the boot file so a boot cache
+    # never collides with a standalone one).
+    def build_via_fork(rails: false)
+      warn_external_sources
+      cached_or { run_phase_a_via_fork(rails: rails) }
+    end
 
+    # Phase B lookup: the test files that cover `file:line`, or [] when none do.
+    # ponytail: per-file granularity; upgrade to per-method when throughput
+    # warrants (requires Minitest method isolation + finer Coverage tracking).
+    def tests_for(file, line)
+      @map["#{relativize(file)}:#{line}"] || []
+    end
+
+    private
+
+    # Shared cache dance for both build paths: hit the digest-keyed cache, else
+    # yield to populate @map and persist it.
+    def cached_or
+      @digest = compute_digest
       cached = read_cache
       if cached && cached["digest"] == @digest
         @map = cached["map"] || {}
@@ -47,20 +78,11 @@ module Mutineer
         return self
       end
 
-      run_phase_a
+      yield
       save
       self
     end
 
-    # Phase B lookup: the test files that cover `file:line`, or [] when none do.
-    # ponytail: per-file granularity; upgrade to per-method when throughput
-    # warrants (requires Minitest method isolation + finer Coverage tracking).
-    def tests_for(file, line)
-      @map["#{relativize(file)}:#{line}"] || []
-    end
-
-    private
-
     def run_phase_a
       @phase_a_ran = true
       @map = {}
@@ -74,6 +96,65 @@ module Mutineer
       end
     end
 
+    # Boot-mode Phase A. For each test file, fork the booted parent; the child
+    # resets its Coverage delta, runs that ONE test, and marshals back the raw
+    # per-source coverage counts. record() inverts them exactly as the subprocess
+    # path does. ponytail: serial fork (one test at a time) — boot apps fork
+    # cheaply via COW and per-test isolation matters more than throughput here.
+    def run_phase_a_via_fork(rails:)
+      @phase_a_ran = true
+      @map = {}
+      @failed_test_files = []
+      abs_sources = abs_source_paths
+
+      @test_paths.each do |test_path|
+        coverage = fork_capture(absolute(test_path), abs_sources, rails)
+        next fail_test(test_path, "fork capture produced no result") unless coverage
+
+        record(coverage, test_path)
+      end
+    end
+
+    # Fork the booted parent, run one test under the inherited Coverage, and
+    # return its per-source counts hash (or nil on failure). Reuses the same
+    # fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.
+    def fork_capture(abs_test, abs_sources, rails)
+      rd, wr = IO.pipe
+      pid = fork do
+        rd.close
+        payload =
+          begin
+            Runner.send(:reconnect_active_record) if rails
+            Coverage.result(clear: true, stop: false) # discard pre-test delta
+            TestRunners.for(@framework).run([abs_test])
+            # lines:true yields {file => {lines: [...]}}; reduce to the counts
+            # array record() expects, keeping only our source files.
+            Coverage.result(stop: false)
+                    .select { |f, _| abs_sources.include?(f) }
+                    .transform_values { |v| v.is_a?(Hash) ? v[:lines] : v }
+          rescue Exception # rubocop:disable Lint/RescueException
+            nil
+          end
+        begin
+          wr.write(Marshal.dump(payload))
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+          # pipe gone; parent records "no result"
+        ensure
+          wr.close
+          exit!(0) # skip at_exit so the parent suite's autorun never re-fires here
+        end
+      end
+      wr.close
+      data = rd.read
+      rd.close
+      Process.waitpid(pid)
+      return nil if data.empty?
+
+      Marshal.load(data)
+    rescue StandardError
+      nil
+    end
+
     # Spawns a fresh `ruby` reading an inline script from stdin. A fork would
     # miss already-loaded app lines, so Coverage must start in a clean process
     # before any source is loaded (KTD1/KTD2). Returns the parsed Coverage.result
@@ -110,6 +191,10 @@ module Mutineer
     end
 
     def subprocess_script(test_path)
+      @framework == "rspec" ? rspec_subprocess_script(test_path) : minitest_subprocess_script(test_path)
+    end
+
+    def minitest_subprocess_script(test_path)
       <<~RUBY
         require "coverage"
         require "json"
@@ -128,6 +213,35 @@ module Mutineer
       RUBY
     end
 
+    # Same coverage-JSON contract as the minitest path, but driven by RSpec:
+    # require rspec/core lazily, load the sources under Coverage, then run the
+    # one spec via RSpec::Core::Runner with output silenced so only the JSON
+    # reaches stdout. A missing rspec makes `require` raise -> subprocess exits
+    # non-zero -> capture() records a skipped (incomplete-map) test, with a hint.
+    def rspec_subprocess_script(test_path)
+      <<~RUBY
+        require "coverage"
+        require "json"
+        require "stringio"
+        begin
+          require "rspec/core"
+        rescue LoadError
+          warn "[mutineer] framework 'rspec' requested but rspec is not available in the project"
+          exit 3
+        end
+        RSpec::Core::Runner.disable_autorun!
+        Coverage.start(lines: true)
+        $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
+        #{abs_source_paths.inspect}.each { |f| load f }
+        _orig = $stdout
+        _sink = StringIO.new
+        $stdout = _sink
+        RSpec::Core::Runner.run(["--no-color", #{absolute(test_path).inspect}], _sink, _sink)
+        $stdout = _orig
+        puts Coverage.result.to_json
+      RUBY
+    end
+
     # Records every source line with a non-zero execution count as covered by
     # this test file. Coverage.result keys are absolute; relativize and drop any
     # path outside the project (stdlib/gem files).
@@ -154,10 +268,18 @@ module Mutineer
       d = Digest::SHA256.new
       digest_group(d, "source", @source_paths)
       digest_group(d, "test", @test_paths)
+      digest_group(d, "boot", [boot_digest_path]) if @boot_path
       @load_paths.sort.each { |lp| d.update("loadpath\0#{lp}\0") }
+      d.update("framework\0#{@framework}\0")
       d.hexdigest
     end
 
+    # boot_path is a require-style path (e.g. "config/environment", no extension);
+    # resolve it to the real file for reading, appending ".rb" when needed.
+    def boot_digest_path
+      File.exist?(absolute(@boot_path)) ? @boot_path : "#{@boot_path}.rb"
+    end
+
     def digest_group(digest, role, paths)
       paths.sort.each do |p|
         content = File.read(absolute(p))

data/lib/mutineer/isolation.rb

@@ -14,10 +14,10 @@ module Mutineer
   # by the parent's monitor flag, not by status.signaled? (which is true for ANY
   # signal death, e.g. SIGSEGV — it cannot tell our SIGKILL apart from the OS's).
   #
-  # mutineer: the 7a strategy this enables (whole-file `load`) re-executes the
+  # mutineer: the reload strategy this enables (whole-file `load`) re-executes the
   # entire file — any top-level code runs again. Acceptable for POROs; document
-  # if users hit issues with initializers/callbacks. Upgrade path: M5 strategy
-  # 7b (class_eval surgical redefinition).
+  # if users hit issues with initializers/callbacks. Alternative: the redefine
+  # strategy (surgical single-method redefinition).
   class Isolation
     DEFAULT_TIMEOUT = 10 # seconds
 
@@ -78,15 +78,13 @@ module Mutineer
       end
     end
 
-    # Strategy 7b: extract just the enclosing DefNode, apply the mutation to that
-    # snippet, resolve the owner via the namespace path, and class_eval the one
-    # method (KTD6). No file-level side effects re-run. Child-only.
+    # Redefine strategy: extract just the enclosing DefNode, apply the mutation to
+    # that snippet, wrap it in its real namespace, and `load` only that one method
+    # back into the running process. No file-level side effects re-run. Child-only.
     #
-    # ponytail: a single owner.class_eval handles BOTH instance and singleton
-    # methods — the extracted snippet keeps its own `def self.x` for singletons,
-    # so class_eval (self == owner) redefines it correctly. Routing singletons
-    # through singleton_class.class_eval (R17) would double-wrap and define on the
-    # wrong class.
+    # The snippet keeps its own `def self.x` for singletons, so the namespace
+    # wrapper redefines instance and singleton methods correctly without any
+    # special-casing.
     def self.apply_surgical(mutation, subject, source)
       loc = subject.def_node.location
       def_start = loc.start_offset
@@ -97,9 +95,9 @@ module Mutineer
       mutated_def = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
 
       # Rebuild the FULL namespace nesting textually so unqualified enclosing-
-      # namespace constants resolve exactly as a whole-file `load` (7a) would.
-      # class_eval(string) would collapse Module.nesting to [owner] and raise
-      # NameError on such constants (C2 scope-collapse).
+      # namespace constants resolve exactly as the reload strategy would. A bare
+      # redefinition on the owner would collapse Module.nesting to [owner] and
+      # raise NameError on such constants (C2 scope-collapse).
       keywords = nesting_keywords(subject.namespace)
       prefix   = keywords.map { |kw, name| "#{kw} #{name}" }.join("\n")
       prefix  += "\n" unless prefix.empty?
@@ -116,23 +114,33 @@ module Mutineer
       target = subject.singleton ? owner.singleton_class : owner
       vis    = method_visibility(target, subject.name)
 
-      # Byte-correct line number; eval at top level so the textual class/module
-      # wrappers rebuild Module.nesting. Offset the lineno by the wrapper prefix
-      # so the def lands on its real source line.
-      def_line = source.byteslice(0, def_start).count("\n") + 1
-      eval_line = [def_line - prefix.count("\n"), 1].max
-      eval(wrapped, TOPLEVEL_BINDING, subject.file, eval_line) # rubocop:disable Security/Eval
+      # Write the wrapped snippet to a tempfile and `load` it: `load` runs it at
+      # top level, so the textual class/module wrappers rebuild Module.nesting
+      # identically, with no dynamic string execution for scanners to flag. The
+      # input is the project's OWN source (the enclosing method, textually
+      # mutated), loaded only in this forked child.
+      Tempfile.create(["mutineer_surgical", ".rb"]) do |f|
+        f.write(wrapped)
+        f.flush
+        load f.path
+      end
 
       target.send(vis, subject.name) if vis && vis != :public
     end
 
-    # Resolve each segment of the namespace to its live Module and pick the
-    # correct keyword (reopening a class with `module` — or vice versa — raises
+    # Resolve each namespace ELEMENT to its live Module and pick the correct
+    # keyword (reopening a class with `module` — or vice versa — raises
     # TypeError), so the textual wrapper matches the real definitions.
+    #
+    # #5: a compact element like "Foo::Bar" stays a SINGLE wrapper `class Foo::Bar`
+    # (nesting [Foo::Bar]), matching how a whole-file load (reload) sees it.
+    # Splitting it into `module Foo; class Bar` gave nesting [Foo::Bar, Foo], so an
+    # unqualified constant defined only in Foo would resolve under redefine but not
+    # reload — a strategy disagreement.
     def self.nesting_keywords(namespace)
       mod = Object
-      namespace.flat_map { |n| n.split("::") }.map do |name|
-        mod = mod.const_get(name)
+      namespace.map do |name|
+        mod = mod.const_get(name) # const_get resolves a compact "Foo::Bar" too
         [mod.is_a?(Class) ? "class" : "module", name]
       end
     end

data/lib/mutineer/minitest_integration.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "minitest"
 require "stringio"
 
 module Mutineer
@@ -21,6 +20,17 @@ module Mutineer
     # `test_files` is one path or an Array of paths (M3 coverage selection passes
     # the covering subset); each is loaded before the single Minitest.run.
     def self.run(test_files)
+      # minitest is required LAZILY (never at load time) so Mutineer keeps zero
+      # runtime gem deps and loads fine in an rspec-only project; a missing
+      # minitest raises a clear Mutineer error rather than a LoadError backtrace.
+      begin
+        require "minitest"
+      rescue LoadError
+        raise Mutineer::FrameworkUnavailable,
+              "minitest is not available — add minitest to the project under test, " \
+              "or use --framework rspec"
+      end
+
       # Neutralise autorun so a test file's `require "minitest/autorun"`
       # registers no at_exit hook.
       def Minitest.autorun; end # rubocop:disable Lint/NestedMethodDefinition

data/lib/mutineer/project.rb

@@ -28,6 +28,7 @@ module Mutineer
         @file = file
         @namespace_stack = []
         @subjects = []
+        @singleton_depth = 0
         super()
       end
 
@@ -43,12 +44,25 @@ module Mutineer
         @namespace_stack.pop
       end
 
+      # Methods inside `class << self` are class methods of the enclosing
+      # namespace, but their def nodes have no receiver — track the singleton
+      # context so they're recorded as singleton (so redefine targets the
+      # singleton_class, not instances). `class << some_other_obj` can't be
+      # represented against the namespace, so its defs are skipped (not recursed).
+      def visit_singleton_class_node(node)
+        return unless node.expression.is_a?(Prism::SelfNode)
+
+        @singleton_depth += 1
+        super
+        @singleton_depth -= 1
+      end
+
       def visit_def_node(node)
         @subjects << Subject.new(
           file: @file,
           namespace: @namespace_stack.dup,
           name: node.name,
-          singleton: !node.receiver.nil?,
+          singleton: !node.receiver.nil? || @singleton_depth.positive?,
           def_node: node
         )
         super

data/lib/mutineer/runner.rb

@@ -5,7 +5,9 @@ require_relative "project"
 require_relative "result"
 require_relative "isolation"
 require_relative "minitest_integration"
+require_relative "test_runners"
 require_relative "coverage_map"
+require_relative "changed_lines"
 require_relative "mutator_registry"
 require_relative "worker_pool"
 
@@ -38,29 +40,39 @@ module Mutineer
       # parse that needs nothing loaded. Standalone mode requires the sources as
       # before so their classes exist for the children to inherit.
       if config.boot
+        # Coverage instruments only files loaded AFTER it starts. Start it BEFORE
+        # the boot require so the entire app loaded during boot is instrumented;
+        # forked children then measure each test's coverage delta against it.
+        require "coverage"
+        Coverage.start(lines: true) unless Coverage.running?
         require File.expand_path(config.boot, config.project_root)
       else
         config.sources.each { |f| require File.expand_path(f, config.project_root) }
       end
       config.require_paths.each { |f| require File.expand_path(f, config.project_root) }
 
-      # Boot mode skips coverage selection entirely: every mutant runs the given
-      # --test files (precomputed absolute here, used directly by Runner.run).
       if config.boot
-        coverage_map = nil
-        boot_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
         # Rails/Minitest test files do `require "test_helper"`, which needs the
         # test root on $LOAD_PATH (`bin/rails test` adds it). Prepend each test
         # file's helper root here in the parent so loading them in the fork
-        # children resolves. Inherited by every fork.
+        # children (both coverage capture and per-mutant) resolves.
+        boot_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
         test_load_roots(boot_tests).each { |d| $LOAD_PATH.unshift(d) unless $LOAD_PATH.include?(d) }
+
+        # Boot mode now uses coverage selection too: capture each test's coverage
+        # by forking the booted parent, then select covering tests per mutant.
+        coverage_map = CoverageMap.new(
+          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)
+        ).build_via_fork(rails: config.rails)
       else
         coverage_map = CoverageMap.new(
           source_paths: config.sources, test_paths: config.tests,
           cache_dir: config.cache_dir, project_root: config.project_root,
-          load_paths: config.load_paths
+          load_paths: config.load_paths, framework: config.framework
         ).build_or_load
-        boot_tests = nil
       end
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
@@ -75,6 +87,8 @@ module Mutineer
         end
       end
 
+      jobs = filter_since(jobs, source_map, config) if config.since
+
       # C3: 7a writes mutineer_mutant*.rb into each source dir (so require_relative
       # resolves). A SIGKILL'd child skips the tempfile's ensure-unlink, orphaning
       # it. `ensure` is unreliable vs SIGKILL, so the PARENT sweeps each source dir
@@ -86,10 +100,10 @@ module Mutineer
       strategy = config.strategy
       results =
         begin
+          framework = config.framework
           bare = WorkerPool.new(config.jobs).run(jobs) do |subject, mutation|
             run(mutation, source_file: subject.file, coverage_map: coverage_map,
-                subject: subject, strategy: strategy,
-                test_files: boot_tests, rails: config.rails)
+                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.
@@ -101,6 +115,22 @@ module Mutineer
       [AggregateResult.new(results), source_map]
     end
 
+    # --since: keep only jobs whose mutation lands on a line changed since the git
+    # ref. Composes with coverage selection (it only narrows the job list; each
+    # surviving mutant still goes through Runner.run's coverage check). A file with
+    # no changed lines (absent from the diff) contributes no jobs. Line is computed
+    # exactly as Runner.run does, from the already-read source in source_map.
+    def self.filter_since(jobs, source_map, config)
+      changed = ChangedLines.for(ref: config.since, files: config.sources,
+                                 project_root: config.project_root)
+      jobs.select do |subject, mutation|
+        source = source_map[subject.file]
+        line = source.byteslice(0, mutation.start_offset).count("\n") + 1
+        abs = File.expand_path(subject.file, config.project_root)
+        changed.fetch(abs, []).include?(line)
+      end
+    end
+
     # For each test file, the directory to add to $LOAD_PATH so its
     # `require "test_helper"` (or spec_helper) resolves: the nearest ancestor
     # holding that helper, plus the file's own dir as a fallback.
@@ -131,24 +161,21 @@ module Mutineer
     end
 
     def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
-                 timeout: Isolation::DEFAULT_TIMEOUT, test_files: nil, rails: false)
+                 timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest")
       source  = File.read(source_file)
       mutated = mutation.apply(source)
 
       # Validity rule: a mutant that doesn't re-parse is skipped before forking.
       return Result.skipped if Parser.parse_string(mutated).errors.any?
 
-      # Boot mode passes its tests directly (already absolute); standalone mode
-      # selects covering tests from the map and is :no_coverage when none cover it.
-      if test_files
-        abs_tests = test_files
-      else
-        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?
+      # Coverage selection (both standalone and boot mode): a mutation on a line
+      # no test exercises is :no_coverage (no fork); otherwise exactly the
+      # 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?
 
-        abs_tests = chosen.map { |t| File.expand_path(t, coverage_map.project_root) }
-      end
+      abs_tests = chosen.map { |t| File.expand_path(t, coverage_map.project_root) }
 
       Isolation.run(timeout: timeout) do
         # Forking inherits the parent's live DB connection; sharing one socket
@@ -159,7 +186,7 @@ module Mutineer
         else
           Isolation.apply_whole_file(mutated, source_file)
         end
-        MinitestIntegration.run(abs_tests)
+        TestRunners.for(framework).run(abs_tests)
       end
     end
 

data/lib/mutineer/test_runners/minitest.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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.
+    module Minitest
+      def self.run(test_files) = MinitestIntegration.run(test_files)
+    end
+  end
+end

data/lib/mutineer/test_runners/rspec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+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, mirroring MinitestIntegration's contract:
+    # run the given spec files and return 0 (all passed) / 1 (any failure).
+    #
+    # 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.
+    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.
+      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
+        $stdout = sink
+        $stderr = sink
+        begin
+          status = ::RSpec::Core::Runner.run(["--no-color", *Array(spec_files)], sink, sink)
+        ensure
+          $stdout = orig_out
+          $stderr = orig_err
+        end
+
+        status.zero? ? 0 : 1
+      end
+
+      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,19 @@
+# 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) -> 0/1`
+  # (0 = all passed, 1 = any failure) and is called only inside a forked child.
+  module TestRunners
+    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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mutineer
-  VERSION = "0.2.0"
+  VERSION = "0.6.1"
 end

data/lib/mutineer/worker_pool.rb

@@ -10,7 +10,7 @@ module Mutineer
   # 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 evaluated inside the child via `yield(*items[i])`; whatever it
+  # 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.
   class WorkerPool
@@ -70,43 +70,48 @@ module Mutineer
           return
         end
         wr.close
-        running[pid] = [idx, rd]
+        running[pid] = [idx, rd, +""] # idx, read end, accumulated bytes
       end
     end
 
-    # R6: reap exactly one of OUR children. wait2(-1) would reap (steal) any of
-    # the host process's children — fatal when the pool runs under a forking test
-    # suite. Poll our known pids with WNOHANG instead.
+    # 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?
 
       loop do
-        running.each_key do |pid|
-          reaped, = Process.waitpid2(pid, Process::WNOHANG)
-          next unless reaped
+        rds = running.values.map { |v| v[1] }
+        ready, = IO.select(rds, nil, nil)
+        ready.each do |rd|
+          pid, (idx, _io, buf) = running.find { |_, v| v[1].equal?(rd) }
+          chunk = rd.read_nonblock(65_536, exception: false)
+          next if chunk == :wait_readable
 
-          return collect(results, running, pid)
+          if chunk.nil? # EOF: child closed wr; it is done writing and exiting
+            rd.close
+            Process.waitpid(pid) # reap the now-finished child (no zombie)
+            running.delete(pid)
+            results[idx] = decode(buf)
+            return
+          end
+          buf << chunk
         end
-        sleep 0.005
       end
     end
 
-    def collect(results, running, pid)
-      idx, rd = running.delete(pid)
-      data = rd.read
-      rd.close
-      results[idx] =
-        if data.empty?
-          Result.error("worker produced no result")
-        else
-          # R6: a partial/garbage Marshal stream (dead worker) must not crash the
-          # pool — degrade to an error Result.
-          begin
-            Marshal.load(data)
-          rescue StandardError => e
-            Result.error("worker result unreadable: #{e.class}: #{e.message}")
-          end
-        end
+    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}")
     end
   end
 end

data/lib/mutineer.rb

@@ -8,8 +8,10 @@ require_relative "mutineer/mutation"
 require_relative "mutineer/project"
 require_relative "mutineer/result"
 require_relative "mutineer/coverage_map"
+require_relative "mutineer/changed_lines"
 require_relative "mutineer/isolation"
 require_relative "mutineer/minitest_integration"
+require_relative "mutineer/test_runners"
 require_relative "mutineer/mutators/base"
 require_relative "mutineer/mutators/arithmetic"
 require_relative "mutineer/mutators/comparison"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.6.1
 platform: ruby
 authors:
 - David Teren
@@ -52,6 +52,7 @@ files:
 - README.md
 - bin/mutineer
 - lib/mutineer.rb
+- lib/mutineer/changed_lines.rb
 - lib/mutineer/cli.rb
 - lib/mutineer/config.rb
 - lib/mutineer/coverage_map.rb
@@ -74,6 +75,9 @@ files:
 - lib/mutineer/result.rb
 - lib/mutineer/runner.rb
 - lib/mutineer/subject.rb
+- lib/mutineer/test_runners.rb
+- lib/mutineer/test_runners/minitest.rb
+- lib/mutineer/test_runners/rspec.rb
 - lib/mutineer/version.rb
 - lib/mutineer/worker_pool.rb
 homepage: https://github.com/davidteren/mutineer