mutineer 0.11.1 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42d278a96730cdf9616492a720c701ba9119195299f64fa74b339b3737e4e545
-  data.tar.gz: ef2148e5752ea9790403ca256e4bc6672b5e8c2656289d74b9cd3ffcd067f475
+  metadata.gz: 457a9cdee5d5291635fb56dd01caf17293bc500443ca2e43e298a81c0c1f73bf
+  data.tar.gz: ffe7d126be066573d5c9c42969f994e7a9be71ecb8d301643a6deab3de5d7af3
 SHA512:
-  metadata.gz: 82879be78e820ef184dca76bf52ad883298f3c0e8becdb6344061b32321f44945464025c6f7d8064e9b649486b6b5f258b60b43baf0ec6f0d38356b314af5793
-  data.tar.gz: 67399daaa12b9b312a4ad0fcad144ae763783d2f5994e474b1303ad7ed0ddd5c5d42fba5b39c750115a0614356b4e4a2593238b91e39eee38edd96981c4afa5a
+  metadata.gz: 63e9df1191cdc62802dcd9dd674eb2954c416b8016017aa3bb9e689f777859f547450416e4a62f23b34f9c9171b063ff12a6639e3cda1ceb9180c48bbea673df
+  data.tar.gz: 0ace3fd9df09a67b535d55ee25f0e30d60f1dd3f03ca1027600cc216d11d9dd468f320e9b11190d595e204d6310bfe05f61ec80e6eeb33f36c123e0981ed1810

data/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-07-24
+
+### Fixed
+- **`--test-command` under version managers** — scrub Mutineer's rbenv/asdf
+  version bins and bundler/gem env from the child so the suite can resolve the
+  app's Ruby via shims / `.ruby-version`. Smoke check prints a targeted hint on
+  `Bundler::RubyVersionMismatch` instead of only blaming DB/migrations. Docs
+  cover a wrapper recipe for stubborn setups (#32).
+
 ## [0.11.1] - 2026-07-23
 
 ### Fixed
@@ -244,6 +253,7 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[0.11.2]: https://github.com/davidteren/mutineer/releases/tag/v0.11.2
 [0.11.1]: https://github.com/davidteren/mutineer/releases/tag/v0.11.1
 [0.11.0]: https://github.com/davidteren/mutineer/releases/tag/v0.11.0
 [0.10.0]: https://github.com/davidteren/mutineer/releases/tag/v0.10.0

data/README.md

@@ -151,11 +151,46 @@ RAILS_ENV=test mutineer run app/models/order.rb \
 
 - **`%{files}`** is required; it expands to the `--test` paths as separate
   arguments (a path with a space stays one argument — there is no shell).
-- **Environment** is inherited by the subprocess, so set it on the Mutineer
-  command (e.g. the leading `RAILS_ENV=test` above). Don't put `KEY=val` inside
-  `--test-command`.
+- **Environment:** vars like `RAILS_ENV` / `DATABASE_URL` set on the Mutineer
+  command are inherited. Mutineer **unsets** `BUNDLE_*`, `GEM_*`, `RUBY*`,
+  `RBENV_VERSION`, `ASDF_RUBY_VERSION`, and `RBENV_DIR` in the child (so
+  Mutineer's own Ruby cannot pin the suite), and drops version-manager
+  **version bins** (e.g. `~/.rbenv/versions/3.4.x/bin`) from `PATH`, then
+  prepends rbenv/asdf shims when a pin was scrubbed. Do not rely on
+  `RBENV_VERSION=…` on the Mutineer command for the suite; use `.ruby-version`
+  or a wrapper. Don't put `KEY=val` prefixes *inside* `--test-command` (no shell;
+  that would be treated as the program name).
+
+#### Under a version manager (rbenv / asdf / chruby)
+
+Automatic scrub targets **rbenv** and **asdf** (shims + version bins). **chruby**
+has no shims: Mutineer still strips `…/rubies/…/bin` so it cannot leave Mutineer's
+Ruby pinned, but you need a wrapper that sources chruby and selects the app
+version. If the smoke check still reports a **Ruby version mismatch**, wrap the
+suite. Example rbenv wrapper (`bin/mutineer-test` in the app):
 
-Tradeoffs (Phase 1) — this path is correct but not free:
+```sh
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.."
+unset GEM_HOME GEM_PATH RUBYLIB RUBYOPT BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLER_VERSION
+export RBENV_VERSION="$(cat .ruby-version 2>/dev/null || true)"
+export RAILS_ENV="${RAILS_ENV:-test}"
+export PATH="${HOME}/.rbenv/shims:${PATH}"
+exec bundle exec rails test "$@"
+```
+
+```sh
+# Mutineer on 3.4+; suite on the app's Ruby via the wrapper
+mutineer run app/models/order.rb \
+  --test test/models/order_test.rb \
+  --test-command "bin/mutineer-test %{files}"
+```
+
+Mutineer also surfaces a targeted smoke-check message when Bundler prints
+`RubyVersionMismatch`, instead of only blaming DB/migrations.
+
+Tradeoffs — this path is correct but not free:
 
 - **Slower:** your app re-boots for every mutant (no shared boot yet).
 - **No coverage narrowing:** every mutant runs the *full* `--test` set, so the

data/lib/mutineer/cli.rb

@@ -49,8 +49,8 @@ module Mutineer
         --rails              Sugar for --boot config/environment --strategy redefine
         --test-command CMD   Run the target suite in the app's own runtime as a
                              subprocess (for apps on Ruby < 3.4). CMD must contain
-                             %{files} (expands to the --test paths). Env is inherited,
-                             e.g. RAILS_ENV=test mutineer run ... --test-command "..."
+                             %{files}. Scrubs Mutineer Ruby PATH pins; set RAILS_ENV
+                             on the mutineer command (not as KEY=val inside CMD)
         --daemon             Boot the app ONCE in a persistent daemon and fork per
                              mutant, with per-worker DB isolation so --jobs N is safe
                              under Rails (needs --rails/--boot; not with --test-command)

data/lib/mutineer/external_backend.rb

@@ -10,17 +10,21 @@ module Mutineer
   # tests. The CLI maps this to a runtime error (exit 1), not a usage error.
   class SmokeCheckError < StandardError; end
 
-  # #27 (U3): the external execution backend. Runs the user's `--test-command` as a
-  # subprocess in the app's OWN runtime (whatever Ruby its bundle resolves to), so
-  # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
+  # External execution backend. Runs the user's `--test-command` as a subprocess
+  # in the app's own runtime (whatever Ruby its bundle resolves to), so mutineer
+  # (Ruby ≥ 3.4) can mutation-test apps pinned to an older Ruby.
   #
   # This is deliberately NOT a `TestRunners` framework adapter: those return an
   # Integer 0/1 from inside a fork and are dispatched by framework name. This is a
   # whole backend — it spawns a process, enforces a wall-clock timeout, and maps
-  # the exit status to a Result. The mapping is the SAME direction as in-process
+  # the exit status to a Result. The mapping is the same direction as in-process
   # (suite passes => survived, suite fails => killed) but coarser: it cannot tell an
   # infrastructure error from a genuine kill, so the smoke check (below) guards the
-  # persistent case and the score is disclosed as an upper bound (KTD-3/KTD-6).
+  # persistent case and the score is disclosed as an upper bound.
+  #
+  # Child environment: bundler/gem env injected by Mutineer's Ruby is stripped, and
+  # version-manager concrete version bins (e.g. `~/.rbenv/versions/3.4.9/bin`) are
+  # removed from PATH so shims / `.ruby-version` can select the app's Ruby (#32).
   module ExternalBackend
     # Generous ceiling for the one-off smoke/calibration run (a cold app boot plus
     # the full suite). The per-mutant timeout is derived from how long this took.
@@ -29,6 +33,24 @@ module Mutineer
     # this backend waits on an external process TREE, not an in-process fork.
     POLL = 0.02
 
+    # PATH entries that pin a concrete Ruby under a version manager (ahead of
+    # shims). Optional trailing slash; normal bins are left alone.
+    VERSION_BIN_PATH = %r{
+      (?:
+        /\.rbenv/versions/[^/]+/bin
+        |/\.asdf/installs/ruby/[^/]+/bin
+        |/\.rubies/[^/]+/bin
+        |/rubies/[^/]+/bin
+      )/?\z
+    }x
+
+    # Env keys Process.spawn must unset (nil value) so Mutineer's Ruby/bundler
+    # context does not leak. Spawn merges env onto the parent; omitting a key
+    # does NOT clear it.
+    CLEAR_ENV_KEYS = %w[
+      BUNDLER_VERSION RBENV_VERSION ASDF_RUBY_VERSION RBENV_DIR
+    ].freeze
+
     # Turn a command template into an argv array (no shell → no eval, no
     # injection). The `%{files}` token expands IN PLACE to N separate argv
     # elements — one per path, unescaped — so a path containing a space stays a
@@ -41,10 +63,63 @@ module Mutineer
       Shellwords.split(command).flat_map { |tok| tok == "%{files}" ? files : [tok] }
     end
 
+    # Environment delta for the test-command child. Process.spawn merges this
+    # onto the parent env: set a key to +nil+ to unset it. Scrubs Mutineer/bundler
+    # injection and version-manager PATH pins so shims / `.ruby-version` can win.
+    # Keeps other vars (e.g. `RAILS_ENV`) so setting them on the Mutineer command
+    # still reaches the suite.
+    #
+    # @api private
+    # @return [Hash{String => String, nil}] env for Process.spawn.
+    def self.child_env
+      env = {}
+      cleared_pin = false
+      ENV.each_key do |k|
+        next unless clear_env_key?(k)
+
+        env[k] = nil
+        cleared_pin = true
+      end
+      path = ENV["PATH"].to_s.split(File::PATH_SEPARATOR)
+      kept = path.reject { |p| p.match?(VERSION_BIN_PATH) }
+      scrubbed_bin = kept.size != path.size
+      # Only reorder PATH when we scrubbed a pin; otherwise leave the user's PATH alone.
+      path = if cleared_pin || scrubbed_bin
+               (version_manager_shim_dirs + kept).uniq
+             else
+               kept
+             end
+      env["PATH"] = path.join(File::PATH_SEPARATOR)
+      env
+    end
+
+    # True when the key must be unset in the child (bundler/gem/version-manager).
+    #
+    # @api private
+    # @param key [String] environment variable name.
+    # @return [Boolean]
+    def self.clear_env_key?(key)
+      key.start_with?("BUNDLE_", "RUBY", "GEM_") || CLEAR_ENV_KEYS.include?(key)
+    end
+
+    # Existing shim directories for rbenv / asdf (chruby uses PATH without shims).
+    #
+    # @api private
+    # @return [Array<String>] absolute shim paths that exist.
+    def self.version_manager_shim_dirs
+      home = ENV["HOME"]
+      return [] if home.nil? || home.empty?
+
+      [
+        File.join(home, ".rbenv", "shims"),
+        File.join(home, ".asdf", "shims")
+      ].select { |d| File.directory?(d) }
+    end
+
     # Runs the command for ONE mutant against whatever is currently on disk (the
     # caller has already swapped the mutant in via FileSwap). Maps the outcome to a
-    # Result. Env is inherited by the subprocess, so `RAILS_ENV=test mutineer …`
-    # reaches the child with no parsing here.
+    # Result. Uses {child_env} so version-manager PATH pins from Mutineer's Ruby do
+    # not force the suite onto the wrong interpreter.
     #
     # @param command [String] the --test-command template.
     # @param files [Array<String>] test file paths.
@@ -93,10 +168,42 @@ module Mutineer
         else                      "exited #{code}"
         end
       detail = output.empty? ? "" : "\n--- last output ---\n#{tail(output)}"
+      hint = ruby_version_mismatch_hint(output)
       raise SmokeCheckError,
-            "the test command #{reason} against the UNMUTATED source — the " \
-            "environment looks broken (check DB, RAILS_ENV, migrations), not the " \
-            "tests weak.#{detail}"
+            "the test command #{reason} against the UNMUTATED source — " \
+            "#{hint || generic_env_hint}.#{detail}"
+    end
+
+    # Generic smoke-failure framing when no Ruby-version mismatch is detected.
+    #
+    # @api private
+    # @return [String]
+    def self.generic_env_hint
+      "the unmutated suite is not green (failing tests, or a broken environment: " \
+        "DB, RAILS_ENV, migrations) — fix that before scoring"
+    end
+
+    # Targeted hint when Bundler reports a RubyVersionMismatch (common under
+    # rbenv/asdf/chruby when Mutineer's version bin sits ahead of shims on PATH).
+    #
+    # @api private
+    # @param output [String] captured child stdout+stderr.
+    # @return [String, nil] hint text, or nil when not a version mismatch.
+    def self.ruby_version_mismatch_hint(output)
+      return nil if output.nil? || output.empty?
+      return nil unless output.match?(/RubyVersionMismatch|Your Ruby version is .* but your Gemfile specified/i)
+
+      ran = output[/Your Ruby version is ([0-9.]+)/i, 1]
+      want = output[/Gemfile specified ([0-9.]+)/i, 1]
+      parts = +"Detected a Ruby version mismatch"
+      parts << ": the test command ran under #{ran}" if ran
+      parts << " but the app expects #{want}" if want
+      parts << ". Mutineer already scrubbed version-manager bins and RBENV_VERSION/" \
+               "ASDF_RUBY_VERSION from the child env; the suite still picked the wrong " \
+               "Ruby. Use a wrapper that re-selects the app Ruby and ensure " \
+               ".ruby-version / .tool-versions is present " \
+               "(see README: Apps on Ruby < 3.4 → Under a version manager)"
+      parts
     end
 
     # Spawns the command to a captured combined-output tempfile, enforces a
@@ -122,7 +229,8 @@ module Mutineer
       # explicit [program, argv0] form guarantees the no-shell exec path even for a
       # degenerate single-element argv (Process.spawn(*argv) would route a lone
       # metachar-bearing string through /bin/sh, breaking the argv-only invariant).
-      pid = Process.spawn([argv.first, argv.first], *argv[1..], out: out, err: %i[child out], pgroup: true)
+      pid = Process.spawn(child_env, [argv.first, argv.first], *argv[1..],
+                          out: out, err: %i[child out], pgroup: true)
       kind, code = wait_with_timeout(pid, timeout)
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
       out.rewind

data/lib/mutineer/version.rb

@@ -2,5 +2,5 @@
 
 module Mutineer
   # Current Mutineer release version.
-  VERSION = "0.11.1"
+  VERSION = "0.11.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.11.2
 platform: ruby
 authors:
 - David Teren