mutineer 1.4.0 → 1.6.0

data/lib/mutineer/daemon_server.rb

@@ -3,15 +3,18 @@
 require "json"
 require "tempfile"
 require_relative "child_stdout"
+require_relative "orphan_guard"
 
 module Mutineer
   # App-side daemon (persistent worker).
   #
   # Runs UNDER THE APP'S OWN BUNDLE/RUBY (the tool's DaemonClient spawns it via
   # `bundle exec ruby`). It boots the app ONCE, then serves per-mutant test-run
-  # requests over stdin/stdout as newline-delimited JSON. For each request it
-  # FORKS a child that loads the mutated source text the tool sent, runs the
-  # covering tests, and exits with a status the parent decodes into a verdict.
+  # requests over stdin/stdout as newline-delimited JSON (the protocol keeps a
+  # private copy of the original stdout; the app's own stdout goes to stderr).
+  # For each request it FORKS a child that loads the mutated source text the
+  # tool sent, runs the covering tests, and exits with a status the parent
+  # decodes into a verdict.
   #
   # HARD CONSTRAINT: this file must be loadable WITHOUT Prism or the rest of
   # mutineer. The app's Ruby may be < 3.4 (no stdlib Prism) and its bundle has no
@@ -21,7 +24,7 @@ module Mutineer
   # tool-side; the daemon only `load`s text.
   #
   # Protocol (one JSON object per line, both directions):
-  #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment",
+  #   boot in  : {"cmd":"boot","project_root":"...","boot":"config/environment","require_paths":[...],
   #               "load_paths":["test"],"framework":"minitest","rails":true,"schema":"db/schema.rb"}
   #   ready out: {"ready":true,"ruby":"3.3.6"}   (or {"ready":false,"error":"..."} then exit)
   #   run  in  : {"id":N,"worker":I,"payload":{"code":"<ruby>","source_file":"app/models/order.rb"},
@@ -49,10 +52,14 @@ module Mutineer
       # Serve the protocol on the given IO pair (defaults to stdio). Returns on quit.
       #
       # @param input [IO] request stream.
-      # @param output [IO] verdict stream.
+      # @param output [IO, nil] verdict stream. nil (the default) reserves the
+      #   process's original stdout for the protocol and points fd 1 at stderr.
       # @param errio [IO] diagnostics stream (never the IPC channel).
       # @return [void]
-      def run(input: $stdin, output: $stdout, errio: $stderr)
+      def run(input: $stdin, output: nil, errio: $stderr)
+        # Only a stream `run` reserved itself is the daemon's to close in a fork.
+        @protocol = output ? nil : reserve_protocol_output
+        output ||= @protocol
         @errio = errio
         @output = output
         boot_line = input.gets
@@ -92,6 +99,21 @@ module Mutineer
 
       private
 
+      # Move the protocol channel off fd 1 before the app boots. The app may
+      # print through `puts`, `STDOUT`, or a raw fd 1 write (a logger, a
+      # subprocess). A line like that ahead of the ready message would break
+      # the client's JSON read. The protocol keeps a private dup of the
+      # original stdout. Fd 1 then points at stderr, so app output stays
+      # visible in the tool's diagnostics.
+      #
+      # @return [IO] the reserved protocol stream.
+      def reserve_protocol_output
+        protocol = STDOUT.dup
+        STDOUT.reopen(STDERR)
+        $stdout = STDOUT
+        protocol
+      end
+
       # BOOT ONCE. chdir + require the app's boot file so the whole app is loaded
       # and inherited by every fork. Never requires mutineer.
       def boot!(cfg)
@@ -105,13 +127,16 @@ module Mutineer
         # instrumented. The map build (build_via_fork) forks this booted parent.
         if cfg["coverage"]
           require "coverage"
-          Coverage.start(lines: true)
+          Coverage.start(lines: true, methods: true)
         end
         # Clear any mutant tempfile a prior SIGKILLed timeout child orphaned in a
         # source dir BEFORE the app boots. Zeitwerk would otherwise choke on the
         # tempfile's non-constant name during autoload setup.
         sweep_temps
         require File.expand_path(cfg["boot"]) if cfg["boot"]
+        # The --require files, after the boot as in-process (Runner.execute), so
+        # the coverage peek sees what they ran at load.
+        Array(cfg["require_paths"]).each { |f| require File.expand_path(f) }
         setup_worker_db(cfg) if cfg["rails"]
       rescue Exception => e # rubocop:disable Lint/RescueException
         # Boot failed (bad boot path, app error). Tell the client and exit so it
@@ -131,15 +156,15 @@ module Mutineer
         @worker_db = RailsWorkerDb.available? ? RailsWorkerDb : nil
         schema = cfg["schema"] && File.expand_path(cfg["schema"])
         @schema_path = schema if schema && File.exist?(schema)
-        # Schema is loaded once per worker slot on first use (not every mutant fork).
-        @schema_ready = {}
+        # Each worker slot is seeded once, on first use (not every mutant fork).
+        @slot_ready = {}
       rescue LoadError => e
         @errio.puts("[daemon] worker-DB routing unavailable: #{e.message}")
         @worker_db = nil
       end
 
       # Build the coverage map app-side (Coverage was started at boot) and return
-      # it as `{map, failed_test_files}` for the tool to select covering tests.
+      # it as `{map, failed_test_files, load_lines, load_methods}` for the tool to select covering tests.
       # Capture forks route to worker 0's DB (isolated, serial). On any failure
       # return an empty map + an error string. The tool then falls back to the
       # full test set rather than mis-scoring everything as no_coverage.
@@ -149,41 +174,61 @@ module Mutineer
         cmap = CoverageMap.new(
           source_paths: Array(@cfg["sources"]), test_paths: Array(@cfg["tests"]),
           load_paths: Array(@cfg["load_paths"]), project_root: root,
-          boot_path: @cfg["boot"], framework: @framework, cache_dir: File.join(root, ".mutineer")
+          boot_path: @cfg["boot"], require_paths: Array(@cfg["require_paths"]),
+          framework: @framework, cache_dir: @cfg["cache_dir"] || File.join(root, ".mutineer"),
+          capture_timeout: @cfg["capture_timeout"] || CoverageMap::DEFAULT_CAPTURE_TIMEOUT
         ).build_via_fork(after_fork: coverage_after_fork)
+        # Nothing reads Coverage after the map, so a mutant forked from this
+        # daemon does not pay for it (#228).
+        Coverage.suspend if Coverage.running?
         { "map" => cmap.map, "failed_test_files" => cmap.failed_test_files,
-          "failed_clean_tests" => cmap.failed_clean_tests }
+          "failed_clean_tests" => cmap.failed_clean_tests, "load_lines" => cmap.load_lines.to_a,
+          "load_methods" => cmap.load_methods.to_a }
       rescue Exception => e # rubocop:disable Lint/RescueException
         @errio.puts("[daemon] coverage build failed: #{e.class}: #{e.message}")
         { "map" => {}, "failed_test_files" => [], "error" => "#{e.class}: #{e.message}" }
       end
 
-      # Fork-safety hook for coverage capture: route each capture fork to worker
-      # 0's isolated DB (captures run serially, so one worker is enough). Nil when
-      # the app has no worker-DB adapter (non-Rails). Capture then runs as before.
+      # Fork-safety hook for coverage capture. Each capture fork drops its copy
+      # of the protocol channel (see close_protocol) and, when the app has a
+      # worker-DB adapter, routes to a fresh copy of the base DB in worker 0's
+      # slot (captures run serially, so one worker is enough).
       def coverage_after_fork
-        return nil unless @worker_db
-
+        worker_db = @worker_db
         schema = @schema_path
-        -> { @worker_db.after_fork(0, schema) }
+        lambda do
+          close_protocol
+          worker_db&.after_fork(0, schema, seed: true)
+        end
+      end
+
+      # A forked child never answers on the protocol channel. Closing its
+      # inherited copy lets a daemon crash read as EOF on the client at once,
+      # not only after a slow or hung child exits. A caller-supplied output
+      # (for example STDOUT) is left open.
+      def close_protocol
+        @protocol&.close rescue nil # rubocop:disable Style/RescueModifier
       end
 
       # Fork a child to run one mutant in isolation; decode its exit into a verdict.
       def run_mutant(req)
         timeout = req.fetch("timeout", 30)
         worker  = req.fetch("worker", 0)
-        # Load schema until the first killed/survived fork for this worker slot.
-        schema_for_fork = (@worker_db && @schema_path && !@schema_ready[worker]) ? @schema_path : nil
+        # Seed the slot's DB until the first killed/survived fork for this worker slot.
+        first_use = @worker_db && !@slot_ready[worker]
+        daemon = Process.pid
         pid = fork do
           # New process group so a per-fork timeout can SIGKILL the whole subtree,
-          # and silence the child's stdout so test output never corrupts the IPC pipe.
+          # and silence the child's stdout so test output stays out of the diagnostics.
           Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier
+          OrphanGuard.start(daemon)
           code =
             begin
               ChildStdout.silence
+              close_protocol
               # Route THIS fork at its own worker database before any test loads.
               # A routing failure raises here and is scored `error`, never a false verdict.
-              @worker_db&.after_fork(worker, schema_for_fork)
+              @worker_db&.after_fork(worker, first_use ? @schema_path : nil, seed: first_use)
               apply_payload(req["payload"])
               run_tests(Array(req["tests"]))
             rescue Exception => e # rubocop:disable Lint/RescueException
@@ -193,10 +238,10 @@ module Mutineer
           exit!(code)
         end
         verdict = wait_verdict(pid, timeout)
-        # Mark ready only when the child finished cleanly after schema load
-        # (killed/survived). Timeout can interrupt mid-load_schema; error is a
-        # routing failure. Both leave the slot unready so the next fork reloads.
-        @schema_ready[worker] = true if schema_for_fork && %w[killed survived].include?(verdict)
+        # Mark ready only when the child finished cleanly after seeding
+        # (killed/survived). Timeout can interrupt mid-copy; error is a routing
+        # failure. Both leave the slot unready so the next fork seeds again.
+        @slot_ready[worker] = true if first_use && %w[killed survived].include?(verdict)
         # A SIGKILLed timeout child skipped its Tempfile unlink. Sweep the orphan
         # so it cannot outlive the run or trip Zeitwerk on a later fork.
         sweep_temps if verdict == "timeout"
@@ -204,7 +249,7 @@ module Mutineer
       end
 
       # Remove orphaned mutant tempfiles from the source dirs (parent-side; the
-      # SIGKILL path cannot run the child's ensure). Mirrors Runner.sweep_orphans.
+      # SIGKILL path cannot run the child's ensure). Mirrors JobPlan.sweep_orphans.
       def sweep_temps
         @source_dirs.to_a.each do |dir|
           Dir.glob(File.join(dir, "mutineer_daemon*.rb")).each do |f|
@@ -218,6 +263,8 @@ module Mutineer
       # pulls in Prism which is forbidden app-side). NOTE: this is the 3rd copy of
       # the waitpid2(WNOHANG)+deadline+pgroup-SIGKILL+decode discipline. A fix to
       # the kill/reap/decode logic must be applied to all three in lockstep.
+      # CoverageMap#await_child applies the same deadline and group kill to
+      # coverage capture.
       # SIGKILL the child's process group past the deadline; a signalled child
       # (nil exitstatus) is `error`.
       def wait_verdict(pid, timeout)

data/lib/mutineer/external_backend.rb

@@ -52,11 +52,11 @@ module Mutineer
     ].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
+    # injection). The <tt>%{files}</tt> token expands IN PLACE to N separate argv
     # elements — one per path, unescaped — so a path containing a space stays a
     # single argument. It is not a space-joined string.
     #
-    # @param command [String] the --test-command template (contains %{files}).
+    # @param command [String] the --test-command template (contains <tt>%{files}</tt>).
     # @param files [Array<String>] test file paths to substitute.
     # @return [Array<String>] argv.
     def self.build_argv(command, files)

data/lib/mutineer/file_swap.rb

@@ -21,7 +21,7 @@ module Mutineer
   # which makes leaving the file mutated the one genuinely dangerous failure mode.
   #
   # Defense in depth, mirroring the tempfile-orphan discipline
-  # (`Runner.sweep_orphans`, `isolation.rb` tempfiles):
+  # (`JobPlan.sweep_orphans`, `isolation.rb` tempfiles):
   #   - exclusive OS ownership (flock) is acquired before swap or recovery;
   #   - the original bytes are held in memory AND written to a sibling backup;
   #   - `ensure` restores from memory around every mutant;

data/lib/mutineer/isolation.rb

@@ -4,6 +4,7 @@ require "tempfile"
 require_relative "result"
 require_relative "parser"
 require_relative "child_stdout"
+require_relative "kill_channel"
 
 module Mutineer
   # Fork-based isolation for running one mutant. The block runs in a child
@@ -23,6 +24,9 @@ module Mutineer
   class Isolation
     DEFAULT_TIMEOUT = 10 # seconds
 
+    # Seconds between the parent's checks on a running child.
+    POLL_INTERVAL = 0.005
+
     # Runs the block in a forked child. The block's return value (an Integer
     # exit code) or any explicit `exit` is honoured; an unhandled exception
     # becomes exit 2 with the cause written to STDERR.
@@ -30,18 +34,30 @@ module Mutineer
     # The child silences its stdout (see {ChildStdout.silence}) before the
     # block runs, so test output never reaches the user. Stderr stays open.
     #
+    # With `channel: true` (a `--matrix` run) the block gets the write end of a
+    # pipe for {KillChannel} lines. The parent reads it while it waits, so a
+    # child with more than a pipe buffer to say never blocks, and attaches the
+    # lines to the Result as {Kills}. The verdict is the one a run without
+    # `--matrix` gives (see {.finish}).
+    #
     # @param timeout [Integer] timeout in seconds.
+    # @param channel [Boolean] open a {KillChannel} pipe for the block.
+    # @yieldparam channel [IO, nil] the pipe's write end, or nil without `channel`.
     # @yieldreturn [Integer] child exit status.
     # @return [Mutineer::Result] result from the child process.
-    def self.run(timeout: DEFAULT_TIMEOUT)
+    def self.run(timeout: DEFAULT_TIMEOUT, channel: false)
+      rd, wr = IO.pipe if channel
+      wr&.sync = true
       pid = fork do
+        rd&.close
         # Own process group so a timeout kill can reap grandchildren (match
         # daemon/external backends). Best-effort: if setpgid fails, kill the pid.
         Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier
         code = 0
         begin
           ChildStdout.silence
-          result = yield
+          # A block that takes no channel (a zero-arity lambda) still runs.
+          result = channel ? yield(wr) : yield
           code = result.is_a?(Integer) ? result : 0
         rescue SystemExit => e
           code = e.status
@@ -57,13 +73,17 @@ module Mutineer
         exit!(code)
       end
 
+      wr&.close
+      buffer = +"" if rd
+      reading = !rd.nil?
+
       # Single-threaded deadline poll: we are the ONLY caller of waitpid on this
       # pid, so we never reap-then-kill. SIGKILL the process group only after
       # WNOHANG shows the child is still alive past the deadline.
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       loop do
         reaped, status = Process.waitpid2(pid, Process::WNOHANG)
-        return decode(status) if reaped
+        return finish(decode(status), rd, buffer, finished: true) if reaped
 
         if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
           begin
@@ -74,14 +94,79 @@ module Mutineer
           begin
             _reaped, status = Process.waitpid2(pid)
             # Child may have finished cleanly between WNOHANG and kill; honor it.
-            return decode(status) if status && status.exited? && !status.signaled?
+            return finish(decode(status), rd, buffer, finished: true) if status && status.exited? && !status.signaled?
           rescue Errno::ECHILD
             # already reaped
           end
-          return Result.timeout
+          return finish(Result.timeout, rd, buffer, finished: false)
+        end
+        if reading
+          IO.select([rd], nil, nil, POLL_INTERVAL)
+          reading = drain(rd, buffer)
+        else
+          sleep POLL_INTERVAL
         end
-        sleep 0.005
       end
+    ensure
+      rd&.close
+      # Closed after the fork in the normal path; still open if fork raised.
+      wr.close if wr && !wr.closed?
+    end
+
+    # Reads what the channel holds now, without blocking.
+    #
+    # @api private
+    # @param rd [IO] the channel's read end.
+    # @param buffer [String] bytes read so far; appended to.
+    # @return [Boolean] false once the channel is at end of file.
+    def self.drain(rd, buffer)
+      loop do
+        chunk = rd.read_nonblock(65_536, exception: false)
+        return true if chunk == :wait_readable
+        return false if chunk.nil?
+
+        buffer << chunk
+      end
+    end
+
+    # The Result to return. Without a channel it is `result` itself. With one,
+    # the rest of the channel is read, and the Result carries the {Kills} it
+    # names.
+    #
+    # The verdict matches a run without `--matrix`, which skips everything after
+    # the first failing serial test except the code around it (see
+    # {KillChannel}). So when a serial test has named a kill and the child then
+    # ended inside a region that run would skip (an exit, a crash or the
+    # timeout in a later test, class or group), the mutant is `killed`: the
+    # plain run never reached that point. An end anywhere else keeps the exit
+    # status, because the plain run reaches that code too: the rest of the
+    # failing test's class wrapper or group hooks, or the suite hooks. A kill in
+    # the parallel tests of a Minitest run also keeps it, because the stop
+    # cannot skip tests already queued.
+    #
+    # The row is complete only when the child ended before the timeout, sent a
+    # valid stream with both `start` and `end`, lost no line, and its kills
+    # agree with the verdict (a killed mutant names a killer; a survivor names
+    # none). An invalid stream promotes nothing, and its tests are dropped: an
+    # out-of-order line means the parent cannot tell which outcomes are real.
+    #
+    # @api private
+    # @param result [Mutineer::Result] the verdict from the exit status or the timeout.
+    # @param rd [IO, nil] the channel's read end.
+    # @param buffer [String, nil] bytes read so far.
+    # @param finished [Boolean] the child ended before the timeout.
+    # @return [Mutineer::Result]
+    def self.finish(result, rd, buffer, finished:)
+      return result unless rd
+
+      drain(rd, buffer)
+      report = KillChannel.parse(buffer)
+      return result.with(kills: Kills.new(killed_by: [], ran: [], complete: false)) if report.invalid
+
+      result = Result.killed if report.started && report.serial_kill && report.skipping.positive?
+      agrees = result.killed? ? report.killed.any? : result.survived? && report.killed.empty?
+      complete = finished && report.started && report.finished && report.lost.zero? && agrees
+      result.with(kills: Kills.new(killed_by: report.killed, ran: report.ran, complete: complete))
     end
 
     # Strategy 7a (default): write the whole mutated file and `load` it, which
@@ -149,6 +234,7 @@ module Mutineer
         else
           mutated_def
         end
+      inner = "#{subject.block_owner}.class_eval do\n#{inner}\nend" if subject.block_owner
       wrapped = "#{prefix}#{inner}#{"\nend" * keywords.size}"
 
       # A snippet that fails to reparse must NOT silently fall through to