evilution 0.33.0 → 0.35.0

data/lib/evilution/process_supervisor.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "version"
+require_relative "temp_dir_tracker"
+
+# Single owner of the process-lifecycle invariant: every pid spawned here is
+# group-isolated, tracked in a signal-safe registry, group-signalled through a
+# TERM/KILL ladder, and reaped -- with its fds closed and sandbox dir removed.
+#
+# EV-9f3b / EV-5rrh, Track A step 1. Generalizes the lock-free COW
+# WorkerRegistry (EV-jwao) and absorbs ProcessCleanup.safe_kill/safe_wait
+# semantics. Pure unit: no call sites are migrated here -- Isolation::Fork
+# (inner path) and WorkQueue::Worker (outer path) are routed through it in
+# later steps (EV-3aw3, EV-dg69, EV-7a91).
+#
+# Shape: instances own the lifecycle of the children they spawn, but every
+# handle is also recorded in ONE process-global registry so the Runner signal
+# trap can `.signal_all` across every fork-site through a single owner.
+#
+# Signal-safety: under MRI a trap handler runs on the main thread between VM
+# instructions, so it must not acquire a Mutex (the main thread may hold it ->
+# deadlock). register/unregister swap @registry for a freshly built frozen
+# array via a single atomic reference assignment (copy-on-write). The trap
+# reads the current reference once and iterates that complete, immutable
+# snapshot -- no torn reads, no lock.
+class Evilution::ProcessSupervisor
+  GRACE_PERIOD = 2
+
+  # One tracked child: leader pid, its process-group id (== pid for a group
+  # leader), the parent-side fds to close on reap, and an optional sandbox dir
+  # to remove on reap.
+  Handle = Struct.new(:pid, :pgid, :fds, :sandbox_dir, keyword_init: true)
+
+  @registry = [].freeze
+
+  class << self
+    # Frozen snapshot. Safe to read from a signal handler.
+    attr_reader :registry
+
+    def register(handle)
+      @registry = (@registry + [handle]).freeze
+    end
+
+    def unregister(handle)
+      @registry = @registry.reject { |existing| existing.pid == handle.pid }.freeze
+    end
+
+    def signal_all(sig)
+      @registry.each do |handle|
+        Process.kill(sig, -handle.pgid)
+      rescue Errno::ESRCH
+        # Group already gone (leader + subtree reaped) -- nothing to signal.
+        nil
+      end
+    end
+
+    # Drop every inherited entry so a freshly forked child starts owning
+    # nothing. A child inherits a COW copy of this registry, but the handles in
+    # it belong to the PARENT (e.g. sibling workers); if the child later
+    # signalled or reaped them -- via signal_all / kill_and_reap_all in its own
+    # signal handler -- it would tear down processes it never spawned. The child
+    # re-registers only what it spawns itself.
+    def reset_for_child!
+      @registry = [].freeze
+    end
+
+    # Trap-safe teardown of every registered child: SIGKILL each process group
+    # (sweeping grandchildren) and the bare leader pid, then reap the leaders so
+    # they cannot zombie, and clear the registry. Reads the COW snapshot once --
+    # no Mutex, safe from a signal handler.
+    #
+    # EV-7a91: a process about to die on a fatal signal must not leave the
+    # children it OWNS behind. The Runner's group-kill reaches only the worker
+    # groups; the inner per-mutation children left those groups (setpgid, EV-2sh8)
+    # and live in the worker's own registry, so only the worker -- their parent --
+    # can kill AND reap them before it dies. Without the reap they survive as
+    # zombies until some ancestor exits and init collects them, which never comes
+    # when evilution runs embedded in a long-lived host process.
+    def kill_and_reap_all
+      snapshot = @registry
+      snapshot.each do |handle|
+        kill_tolerant("KILL", -handle.pgid)
+        kill_tolerant("KILL", handle.pid)
+      end
+      # Reap only after every group has been signalled, so a slow-to-die child
+      # never delays killing the others' subtrees.
+      snapshot.each { |handle| reap_tolerant(handle.pid) } # rubocop:disable Style/CombinableLoops
+      @registry = (@registry - snapshot).freeze
+    end
+
+    private
+
+    def kill_tolerant(sig, target)
+      Process.kill(sig, target)
+    rescue Errno::ESRCH
+      nil
+    end
+
+    def reap_tolerant(pid)
+      Process.waitpid(pid)
+    rescue Errno::ECHILD
+      nil
+    end
+  end
+
+  # Fork a child that becomes its own process-group leader and runs the block,
+  # returning a Handle. By default the child calls setpgid(0, 0) before
+  # yielding so any grandchildren it forks join its group and can be swept by a
+  # group signal; the parent repeats setpgid(pid, pid) to close the race where
+  # it signals before the child has isolated itself. The handle is registered
+  # BEFORE the parent-side setpgid so the trap can never observe a child that is
+  # already a group leader yet missing from the registry (EV-jwao race).
+  #
+  # isolate_in_child: false suppresses the child-side setpgid for long-lived
+  # workers (the outer path): the child must NOT become its own group leader
+  # until the parent has registered it, otherwise a trap firing between fork and
+  # register would see a leader it cannot signal. With only the parent-side,
+  # post-register setpgid, the child stays in the parent group (reachable by the
+  # terminal signal directly) until the registry already lists it.
+  def spawn(sandbox_dir: nil, fds: [], isolate_in_child: true)
+    pid = ::Process.fork do
+      self.class.reset_for_child!
+      isolate_self if isolate_in_child
+      yield
+    end
+
+    # Track the sandbox first thing after fork: if the parent takes a fatal
+    # signal before isolate_child returns, Runner's trap (TempDirTracker
+    # .cleanup_all) can still see and remove it, narrowing the leak window.
+    Evilution::TempDirTracker.register(sandbox_dir) if sandbox_dir
+    handle = Handle.new(pid: pid, pgid: pid, fds: fds, sandbox_dir: sandbox_dir)
+    self.class.register(handle)
+    isolate_child(pid)
+    handle
+  end
+
+  # Signal the child's whole process group (-pgid) to sweep any grandchildren,
+  # then the bare pid as a fallback for the case where setpgid failed (no group
+  # exists, so the group signal is a harmless Errno::ESRCH).
+  def signal_group(sig, handle)
+    safe_kill(sig, -handle.pgid)
+    safe_kill(sig, handle.pid)
+  end
+
+  # Bounded TERM -> grace -> KILL ladder, then reap. Always ends with the child
+  # reaped and its resources released, whichever rung it dies on.
+  def terminate(handle, grace: GRACE_PERIOD)
+    signal_group("TERM", handle)
+    unless exited?(handle.pid)
+      sleep(grace)
+      signal_group("KILL", handle) unless exited?(handle.pid)
+    end
+    reap(handle)
+  end
+
+  # Reap the leader (ECHILD-tolerant if already reaped), then unconditionally
+  # release the resources the handle owns: close parent-side fds, remove the
+  # sandbox dir, and drop the handle from the registry.
+  def reap(handle)
+    safe_wait(handle.pid)
+  ensure
+    release(handle)
+  end
+
+  # Non-blocking reap for callers that poll a child's liveness as part of a
+  # read protocol (e.g. Isolation::Fork's marshal-pipe loop). Returns false
+  # while the child is still running -- the handle stays registered so a signal
+  # trap can still reach it. Once the child has exited (or was already reaped),
+  # it releases the handle in the same step it reaps, so the process-global
+  # registry never holds a stale, already-reaped pgid.
+  def reap_nonblock(handle)
+    return false unless nonblocking_wait(handle.pid)
+
+    release(handle)
+    true
+  end
+
+  private
+
+  # WNOHANG wait: returns the pid once the child has exited, nil while it is
+  # still running, and -- treating an already-reaped child as exited -- the pid
+  # again on ECHILD so the caller still releases the handle.
+  def nonblocking_wait(pid)
+    ::Process.waitpid(pid, ::Process::WNOHANG)
+  rescue Errno::ECHILD
+    pid
+  end
+
+  def release(handle)
+    close_fds(handle)
+    cleanup_sandbox(handle)
+    self.class.unregister(handle)
+  end
+
+  def isolate_self
+    ::Process.setpgid(0, 0)
+  rescue SystemCallError
+    nil
+  end
+
+  def isolate_child(pid)
+    ::Process.setpgid(pid, pid)
+  rescue Errno::EACCES, Errno::ESRCH
+    # EACCES: child already exec'd/changed group; ESRCH: child already exited.
+    # Both are benign -- reaping handles the child either way.
+    nil
+  rescue SystemCallError => e
+    # Any other setpgid failure (e.g. EPERM) leaves the child in the parent
+    # group: a later group-kill won't sweep its subtree. Don't raise (spawn
+    # must still return a usable handle), but surface it so the leak is
+    # debuggable rather than silent.
+    warn "evilution: could not isolate process #{pid} into its own process " \
+         "group (#{e.class}: #{e.message}); grandchildren may survive a kill."
+  end
+
+  # True once the child has been reaped (now or earlier). WNOHANG returns the
+  # pid for a freshly exited child, nil while it still runs, and raises ECHILD
+  # if it was already reaped -- all of which we treat as "no longer running".
+  def exited?(pid)
+    !::Process.waitpid(pid, ::Process::WNOHANG).nil?
+  rescue Errno::ECHILD
+    true
+  end
+
+  def safe_kill(signal, target)
+    ::Process.kill(signal, target)
+  rescue Errno::ESRCH
+    nil
+  end
+
+  def safe_wait(pid)
+    ::Process.wait(pid)
+  rescue Errno::ECHILD
+    nil
+  end
+
+  def close_fds(handle)
+    handle.fds.each do |io|
+      io.close unless io.closed?
+    rescue IOError
+      nil
+    end
+  end
+
+  # Remove the sandbox first, then drop it from TempDirTracker only on success.
+  # If removal raises, leave the dir tracked so TempDirTracker.cleanup_all /
+  # at_exit can retry it, and swallow the error so reap's ensure-path still
+  # unregisters the handle (no stale entry in the process-global registry).
+  def cleanup_sandbox(handle)
+    dir = handle.sandbox_dir
+    return unless dir
+
+    FileUtils.rm_rf(dir)
+    Evilution::TempDirTracker.unregister(dir)
+  rescue StandardError
+    nil
+  end
+end

data/lib/evilution/runner/baseline_runner.rb

@@ -5,6 +5,9 @@ require_relative "../baseline"
 require_relative "../spec_resolver"
 require_relative "../integration/rspec"
 require_relative "../integration/minitest"
+require_relative "../coverage_example_filter"
+require_relative "../coverage/map_store"
+require_relative "../coverage/map_builder"
 require_relative "../integration/test_unit"
 require_relative "../example_filter"
 require_relative "../spec_ast_cache"
@@ -82,6 +85,13 @@ class Evilution::Runner::BaselineRunner
   def build_example_filter
     return nil unless config.example_targeting?
 
+    lexical = build_lexical_filter
+    return lexical unless config.coverage_targeting?
+
+    build_coverage_filter(lexical)
+  end
+
+  def build_lexical_filter
     Evilution::ExampleFilter.new(
       cache: Evilution::SpecAstCache.new(**config.example_targeting_cache),
       fallback: config.example_targeting_fallback,
@@ -89,6 +99,48 @@ class Evilution::Runner::BaselineRunner
     )
   end
 
+  # The coverage map is built (or loaded from cache) once here, in the parent,
+  # before any mutation fork. Any failure -- unsupported Ruby, suite error,
+  # corrupt cache that cannot rebuild -- degrades to lexical targeting rather
+  # than aborting the run (design: never abort, never silently mis-skip).
+  def build_coverage_filter(lexical)
+    map = resolve_coverage_map
+    return lexical unless map
+
+    Evilution::CoverageExampleFilter.new(map: map, lexical: lexical)
+  rescue StandardError => e
+    warn "evilution: coverage targeting unavailable (#{e.class}: #{e.message}); using lexical targeting"
+    lexical
+  end
+
+  def resolve_coverage_map
+    targets = config.target_files.map { |file| File.expand_path(file, Evilution::PROJECT_ROOT) }
+    return nil if targets.empty?
+
+    specs = resolved_spec_files
+    return nil if specs.empty? # nothing resolves -> no coverage to capture, lexical handles it
+
+    store = Evilution::Coverage::MapStore.new
+    cache_inputs = targets + specs
+    return store.load(targets) if store.stale_files(cache_inputs).empty?
+
+    map = Evilution::Coverage::MapBuilder.new(spec_files: specs, target_files: targets).call
+    store.save(map, cache_inputs)
+    map
+  end
+
+  # The RESOLVED spec files for the target sources -- the same lib-mirrored specs
+  # full-file targeting already runs cleanly -- NOT the whole suite. EV-7uui:
+  # capturing and replaying coverage only within these guarantees the covering
+  # examples load in the per-mutation run (cross-file integration specs, which a
+  # whole-suite map would surface, fail to bootstrap in isolation and lose kills).
+  def resolved_spec_files
+    config.target_files
+          .flat_map { |file| Array(config.spec_selector.call(file)) }
+          .map { |spec| File.expand_path(spec, Evilution::PROJECT_ROOT) }
+          .uniq
+  end
+
   def log_start
     return if config.quiet || !config.text? || !$stderr.tty?
 

data/lib/evilution/runner/canary.rb

@@ -76,13 +76,30 @@ class Evilution::Runner::Canary
   end
 
   def write_spec(dir)
-    minitest = @config.integration == :minitest
-    name = minitest ? "canary_#{suffix}_test.rb" : "canary_#{suffix}_spec.rb"
-    path = File.join(dir, name)
-    File.write(path, minitest ? minitest_spec_source : rspec_spec_source)
+    path = File.join(dir, spec_filename)
+    File.write(path, spec_source)
     path
   end
 
+  # minitest and test-unit both live under a `_test.rb` file; rspec uses
+  # `_spec.rb`. Picking the wrong shape makes the integration load nothing (or
+  # raise), so the synthetic mutation scores :error and aborts the run.
+  def spec_filename
+    test_framework? ? "canary_#{suffix}_test.rb" : "canary_#{suffix}_spec.rb"
+  end
+
+  def test_framework?
+    %i[minitest test_unit].include?(@config.integration)
+  end
+
+  def spec_source
+    case @config.integration
+    when :minitest then minitest_spec_source
+    when :test_unit then test_unit_spec_source
+    else rspec_spec_source
+    end
+  end
+
   def rspec_spec_source
     <<~RUBY
       RSpec.describe("evilution proof-of-life canary") do
@@ -103,6 +120,16 @@ class Evilution::Runner::Canary
     RUBY
   end
 
+  def test_unit_spec_source
+    <<~RUBY
+      class EvilutionCanaryTest_#{suffix} < Test::Unit::TestCase
+        def test_pipeline_is_alive
+          assert(true)
+        end
+      end
+    RUBY
+  end
+
   def build_mutation(class_path)
     Evilution::Mutation.new(
       subject: Evilution::Subject.new(

data/lib/evilution/runner/isolation_resolver.rb

@@ -5,6 +5,7 @@ require_relative "../isolation/fork"
 require_relative "../isolation/in_process"
 require_relative "../rails_detector"
 require_relative "../gem_detector"
+require_relative "../integration/loading/test_load_path"
 
 class Evilution::Runner::IsolationResolver
   PRELOAD_CANDIDATES = [
@@ -12,6 +13,14 @@ class Evilution::Runner::IsolationResolver
     File.join("spec", "spec_helper.rb"),
     File.join("test", "test_helper.rb")
   ].freeze
+  # Conventional helpers for a non-Rails gem (no rails_helper). Ordered rspec
+  # then minitest/test-unit; test/helper.rb covers the flat-layout convention
+  # (rack, connection_pool, rake).
+  GEM_PRELOAD_CANDIDATES = [
+    File.join("spec", "spec_helper.rb"),
+    File.join("test", "test_helper.rb"),
+    File.join("test", "helper.rb")
+  ].freeze
 
   def initialize(config, target_files:, hooks:)
     @config = config
@@ -36,7 +45,7 @@ class Evilution::Runner::IsolationResolver
     path = resolve_preload_path
     return unless path
 
-    prepare_load_path_for_preload
+    prepare_load_path_for_preload(path)
     prepare_integration_for_preload
     require File.expand_path(path)
   rescue Evilution::ConfigError
@@ -82,24 +91,64 @@ class Evilution::Runner::IsolationResolver
       warn_in_process_under_rails if rails_root_detected?
       :in_process
     else # :auto
-      rails_root_detected? ? :fork : :in_process
+      fork_isolation_default? ? :fork : :in_process
     end
   end
 
+  # Auto-isolation picks :fork for both Rails apps and packaged gems. A gem has
+  # a spec/test suite whose helper (and the gem's own deps) must be preloaded in
+  # the parent before forking; in_process can't preload without polluting the
+  # host, so a plain non-Rails gem run with the in_process default scored 0.0
+  # out-of-box (every mutation errored with 0 examples / NameError). Detecting
+  # the gemspec and defaulting to :fork lets auto-preload fire.
+  def fork_isolation_default?
+    rails_root_detected? || gem_root_detected?
+  end
+
+  def gem_root_detected?
+    !detected_gem_root.nil?
+  end
+
   def detected_rails_root
     return @detected_rails_root if defined?(@detected_rails_root)
 
     @detected_rails_root = Evilution::RailsDetector.rails_root_for_any(target_files)
   end
 
-  # Preload files (e.g. spec/rails_helper.rb) typically `require 'spec_helper'`
-  # which needs spec/ on $LOAD_PATH, and use `RSpec.configure` which needs
-  # rspec/core loaded. The RSpec CLI normally sets this up, but evilution
-  # calls Runner.run directly.
-  def prepare_load_path_for_preload
+  def detected_gem_root
+    return @detected_gem_root if defined?(@detected_gem_root)
+
+    @detected_gem_root = Evilution::GemDetector.gem_root_for_any(target_files)
+  end
+
+  # Preload files `require` a sibling helper relative to the test root, which
+  # the suite's own runner satisfies via -Ispec/-Itest; evilution calls
+  # Runner.run directly, so it must mirror that on $LOAD_PATH. The policy is
+  # integration-specific so it does not over-widen the path:
+  # - rspec: spec/rails_helper.rb / spec/spec_helper.rb need spec/ only (and
+  #   rspec/core for RSpec.configure). Kept spec-only to match the RSpec
+  #   FrameworkLoader and avoid prepending test/ ahead of spec/ in apps that
+  #   have both (a bare `require "support/foo"` must still resolve from spec/).
+  # - minitest/test-unit: a test/test_helper.rb doing a non-relative
+  #   `require "support/..."` needs test/ on $LOAD_PATH. Route through
+  #   TestLoadPath -- the same policy the per-mutation test load uses  -- so preload and mutation paths agree.
+  def prepare_load_path_for_preload(preload_path)
+    if config.integration == :rspec
+      prepare_rspec_preload_load_path
+    else
+      prepare_test_preload_load_path(preload_path)
+    end
+  end
+
+  def prepare_rspec_preload_load_path
     spec_dir = File.expand_path(resolve_spec_dir)
     $LOAD_PATH.unshift(spec_dir) unless $LOAD_PATH.include?(spec_dir)
-    require "rspec/core" if config.integration == :rspec
+    require "rspec/core"
+  end
+
+  def prepare_test_preload_load_path(preload_path)
+    base = detected_rails_root || Evilution.project_base_dir
+    Evilution::Integration::Loading::TestLoadPath.add!([preload_path], base: base)
   end
 
   def resolve_spec_dir
@@ -145,21 +194,55 @@ class Evilution::Runner::IsolationResolver
       raise Evilution::ConfigError, autodetect_missing_message
     end
 
-    detected_gem_entry
+    resolve_autodetected_gem_preload
+  end
+
+  # For a non-Rails gem, prefer the conventional test helper (which loads the
+  # gem's library AND the suite's framework/support setup) over the bare gem
+  # entry, so example groups actually register. Fall back to the gem entry, and
+  # flag a non-standard test layout so the user can pass --preload.
+  def resolve_autodetected_gem_preload
+    helper = find_first_existing_gem_helper
+    return helper if helper
+
+    entry = detected_gem_entry
+    warn_unconventional_test_layout(entry) if detected_gem_root
+    entry
   end
 
   def detected_gem_entry
     return @detected_gem_entry if defined?(@detected_gem_entry)
 
-    root = Evilution::GemDetector.gem_root_for_any(target_files)
+    root = detected_gem_root
     @detected_gem_entry = root && Evilution::GemDetector.gem_entry_for(root, target_paths: target_files)
   end
 
   def find_first_existing_candidate
-    root = detected_rails_root
+    find_first_existing_under(detected_rails_root, PRELOAD_CANDIDATES)
+  end
+
+  def find_first_existing_gem_helper
+    find_first_existing_under(detected_gem_root, GEM_PRELOAD_CANDIDATES) ||
+      find_first_existing_under(detected_gem_root, nested_gem_helper_candidates)
+  end
+
+  # Gems that namespace their suite keep the helper at test/<gem>/helper.rb
+  # (ruby/csv: test/csv/helper.rb) rather than the flat test/helper.rb, so the
+  # conventional chain misses it and autodetect would fall back to the bare gem
+  # entry — which never sets up the test framework, aborting the canary.
+  # Derive the namespace dir from the gem name (dotted for dash-named gems, plus
+  # the flat form).
+  def nested_gem_helper_candidates
+    name = detected_gem_root && Evilution::GemDetector.gem_name(detected_gem_root, target_paths: target_files)
+    return [] unless name
+
+    [name.tr("-", "/"), name].uniq.map { |ns| File.join("test", ns, "helper.rb") }
+  end
+
+  def find_first_existing_under(root, candidates)
     return nil unless root
 
-    PRELOAD_CANDIDATES.each do |rel|
+    candidates.each do |rel|
       abs = File.join(root, rel)
       return abs if File.file?(abs)
     end
@@ -209,6 +292,31 @@ class Evilution::Runner::IsolationResolver
     )
   end
 
+  # A gem was detected but none of the conventional test helpers exist, so the
+  # suite likely uses a non-standard layout. Point at the expected locations and
+  # the --preload escape hatch. The fallback wording reflects what will actually
+  # happen: preload the gem entry when one was found, otherwise nothing is
+  # preloaded (gem_entry can be nil when the gemspec name has no on-disk lib
+  # entry) — without a helper, the gem entry alone may not register example
+  # groups and mutations can error with 0 examples.
+  def warn_unconventional_test_layout(gem_entry)
+    return if config.quiet
+
+    fallback =
+      if gem_entry
+        "Falling back to the gem entry (#{gem_entry})"
+      else
+        "No gem entry found to fall back to, so nothing will be preloaded"
+      end
+
+    $stderr.write(
+      "[evilution] warning: no conventional test helper found under " \
+      "#{detected_gem_root.inspect} (looked for #{GEM_PRELOAD_CANDIDATES.join(", ")}). " \
+      "#{fallback}. If mutations error with '0 examples loaded' or NameError, " \
+      "your test layout is non-standard — pass --preload <your helper>.\n"
+    )
+  end
+
   # When the user explicitly requests InProcess on a Rails project, warn once
   # per run. Rails wraps ActiveRecord transactions in
   # Thread.handle_interrupt(Exception => :never), which defers Timeout's

data/lib/evilution/runner.rb

@@ -182,7 +182,8 @@ class Evilution::Runner
       # terminal Ctrl-C reaches only the parent's group. Forward to each worker
       # group here -- the parent's fatal-signal death skips work_queue#map's
       # `ensure cleanup_workers`, so this trap is the reliable forwarding hook.
-      Evilution::Parallel::WorkQueue::WorkerRegistry.signal_all(sig)
+      # EV-dg69: the signal-safe registry is now owned by ProcessSupervisor.
+      Evilution::ProcessSupervisor.signal_all(sig)
 
       case prev_handler
       when Proc, Method
@@ -231,7 +232,7 @@ require_relative "result/summary"
 require_relative "baseline"
 require_relative "cache"
 require_relative "parallel/pool"
-require_relative "parallel/work_queue/worker_registry"
+require_relative "process_supervisor"
 require_relative "session/store"
 require_relative "temp_dir_tracker"
 require_relative "rails_detector"