mutineer 0.3.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51400ef0019b1a18f5c4b548e7789d072cbd744bd7918aa402de83052b37d5b6
-  data.tar.gz: 31d84ebaf51dbed8a5fc9273aece37f2ea288af9e41efd8006c939439c318125
+  metadata.gz: b549b3640aa316aa715732f4e91f3be669b7ab8e7ad877b8207d0e31ac12b4aa
+  data.tar.gz: a626241007cf47b4fb0ef3c68dc1fba7f0c8679d0c41db516dca888893fc5f51
 SHA512:
-  metadata.gz: 3907408aad53671313f88203fefc9da64f6ee76bffc57b7754ed13b31f19f7a0311c61f6d7a074a21eea78ab6bd74d3143d51e3b25fa9a03eba49901b71c3d5f
-  data.tar.gz: e67bfedd8a82c97496e9ab2189c390826cc6e55678c6c88ab4f40df0b784f92237986e9651668c512839d9803d0f921308228722e2552f6886ead65597d7acfb
+  metadata.gz: ba4d45a6ba52ead7da7f580452eb610bfc23b368501c496e80ffa56e2e364a62fcf896a1e9d37c50b1216727eb8a6a02386ba0917c85397ac61a3f2a9f41d694
+  data.tar.gz: 6be383459b367be9b72135b1672d57c63bd4e4a6c032c3301532f50a1bcb96dff2cc6ecf764979d6009fab9e4c1e4d327fbb1e81cf3652232cb38a2eb6a82558

data/CHANGELOG.md

@@ -4,6 +4,60 @@ 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.2] - 2026-06-29
+
+### Fixed
+- **`--rails` defaults `RAILS_ENV` to `test`** (#7) — an unset `RAILS_ENV` booted
+  development, where the suite isn't loaded, so every mutant was falsely reported
+  `no_coverage` (score N/A, exit 0). An explicit `RAILS_ENV` is respected.
+- **`--rails` defaults to `--jobs 1`** (#12) — parallel mutant forks share one
+  database and deadlock on transactional fixtures; explicit `--jobs N` opts back
+  into parallelism.
+
+### Added
+- **Tier-2 operator discoverability** (#14) — the human-format run summary now
+  lists the available opt-in tier-2 operators and how to enable them.
+
+## [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
@@ -46,6 +100,11 @@ 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.2]: https://github.com/davidteren/mutineer/releases/tag/v0.6.2
+[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,9 @@
 # Mutineer
 
+[![Socket Badge](https://badge.socket.dev/rubygems/package/mutineer/0.6.2?platform=ruby)](https://socket.dev/rubygems/package/mutineer/overview/0.6.2?platform=ruby)
+
 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 +47,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) |

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.
@@ -225,15 +257,40 @@ module Mutineer
       reporter = Reporter.new(aggregate, source_map)
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
                       format: config.format, output: config.output)
+
+      # #14: nudge toward the opt-in tier-2 operators (human report only — never
+      # pollute JSON output).
+      if config.format != "json" && (hint = tier2_hint(config.operators))
+        puts hint
+      end
+
       exit reporter.exit_code(threshold: config.threshold)
     end
 
+    # The tier-2 operators not in the active set, as a one-line hint (or nil when
+    # they're all already enabled). `active` nil means the default (Tier-1) set.
+    def self.tier2_hint(active)
+      active ||= MutatorRegistry::DEFAULT_NAMES
+      unused = MutatorRegistry::TIER2_NAMES - active
+      return if unused.empty?
+
+      "#{unused.size} tier-2 operators available (#{unused.join(', ')}) — " \
+        "enable with --operators <list>."
+    end
+
     def self.dry_run(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
       sources = {}
       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 +299,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
@@ -108,10 +108,28 @@ module Mutineer
       if config.rails
         config.boot ||= "config/environment"
         config.strategy = "redefine" unless explicit.include?(:strategy)
+        # #12: parallel mutant forks share one database; transactional-fixture
+        # setup/teardown across processes contends and deadlocks. Default to
+        # serial under --rails; an explicit --jobs N opts back into parallelism
+        # (with the per-worker DB-isolation that implies).
+        config.jobs = 1 unless explicit.include?(:jobs)
       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 +141,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

@@ -7,6 +7,7 @@ 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
@@ -23,7 +24,8 @@ module Mutineer
 
     def initialize(source_paths:, test_paths:, cache_dir: ".mutineer",
                    load_paths: ["lib"], project_root: Dir.pwd,
-                   capture_timeout: DEFAULT_CAPTURE_TIMEOUT, boot_path: nil)
+                   capture_timeout: DEFAULT_CAPTURE_TIMEOUT, boot_path: nil,
+                   framework: "minitest")
       @source_paths = Array(source_paths)
       @test_paths   = Array(test_paths)
       @cache_dir    = cache_dir
@@ -31,6 +33,7 @@ module Mutineer
       @project_root = project_root
       @capture_timeout = capture_timeout
       @boot_path    = boot_path
+      @framework    = framework || "minitest"
       @map          = {}
       @failed_test_files = []
       @phase_a_ran  = false
@@ -123,7 +126,7 @@ module Mutineer
           begin
             Runner.send(:reconnect_active_record) if rails
             Coverage.result(clear: true, stop: false) # discard pre-test delta
-            MinitestIntegration.run([abs_test])
+            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)
@@ -188,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"
@@ -206,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).
@@ -234,6 +270,7 @@ module Mutineer
       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
 

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,6 +40,11 @@ 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
+        # #7: under --rails an unset RAILS_ENV boots development, where the test
+        # suite isn't loaded — coverage comes back empty and EVERY mutant is
+        # falsely reported no_coverage (score N/A, exit 0). Default it to test.
+        ensure_rails_env(config)
+
         # 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.
@@ -62,14 +69,14 @@ module Mutineer
         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,
           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
       end
 
@@ -85,6 +92,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
@@ -96,9 +105,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, 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.
@@ -110,6 +120,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,6 +157,17 @@ module Mutineer
       end.uniq
     end
 
+    # #7: when --rails is on and RAILS_ENV is unset, default it to "test" (and
+    # say so) before the app boots — otherwise it boots development and nothing
+    # is measured. An explicitly-set RAILS_ENV is always respected.
+    def self.ensure_rails_env(config)
+      return unless config.rails
+      return unless ENV["RAILS_ENV"].nil? || ENV["RAILS_ENV"].empty?
+
+      ENV["RAILS_ENV"] = "test"
+      warn "[mutineer] RAILS_ENV was unset; defaulting to 'test' for --rails."
+    end
+
     def self.sweep_orphans(dirs)
       dirs.each do |dir|
         Dir.glob(File.join(dir, "mutineer_mutant*.rb")).each do |f|
@@ -140,7 +177,7 @@ module Mutineer
     end
 
     def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
-                 timeout: Isolation::DEFAULT_TIMEOUT, rails: false)
+                 timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest")
       source  = File.read(source_file)
       mutated = mutation.apply(source)
 
@@ -165,7 +202,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.3.0"
+  VERSION = "0.6.2"
 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.3.0
+  version: 0.6.2
 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