henitai 0.2.0 → 0.2.1

data/lib/henitai/runner.rb

@@ -25,7 +25,6 @@ module Henitai
   #   Gate 5 — Reporting
   #     Write results to configured reporters (terminal, html, json, dashboard).
   #
-  # rubocop:disable Metrics/ClassLength
   class Runner
     attr_reader :config, :result
 
@@ -51,7 +50,7 @@ module Henitai
     def run
       started_at = Time.now
 
-      mutants = if survivor_rerun? && (fast_mutants = try_recipe_run)
+      mutants = if survivor_rerun? && (fast_mutants = survivor_strategy.try_recipe_run)
                   execute_mutants(fast_mutants)
                 else
                   source_files = self.source_files
@@ -87,7 +86,9 @@ module Henitai
       mutants = generate_mutants(subjects)
       bootstrap_thread.value
       filtered = filter_mutants(mutants)
-      apply_survivor_selection(filtered)
+      return filtered unless survivor_rerun?
+
+      survivor_strategy.apply_selection(filtered)
     end
 
     def bootstrap_mutants(source_files)
@@ -104,7 +105,7 @@ module Henitai
     end
 
     def report(result)
-      Reporter.run_all(names: config.reporters, result:, config:)
+      Reporter.run_all(names: config.reporters, result:, config:, history_store:)
     end
 
     def persist_history(result, recorded_at)
@@ -122,14 +123,29 @@ module Henitai
         finished_at:,
         thresholds: result_thresholds,
         partial_rerun: survivor_rerun?,
-        survivor_stats: @survivor_stats,
-        git_sha: safe_head_sha
+        survivor_stats: survivor_strategy.survivor_stats,
+        git_sha: safe_head_sha,
+        source_provider: source_provider
       )
       persist_history(@result, finished_at)
       report(@result)
       @result
     end
 
+    # Reads each source file once and caches it, so Result consumes source
+    # content while performing no disk IO of its own. Returns "" for files that
+    # cannot be read (e.g. recipe stubs with synthetic locations).
+    def source_provider
+      cache = {} # : Hash[String, String]
+      lambda do |file|
+        cache[file] ||= begin
+          File.read(file)
+        rescue StandardError
+          ""
+        end
+      end
+    end
+
     def safe_head_sha
       git_diff_analyzer.head_sha
     rescue StandardError
@@ -187,22 +203,38 @@ module Henitai
     end
 
     def source_files
-      @source_files ||= begin
-        included_files = Array(config.includes).flat_map do |include_path|
-          Dir.glob(File.join(include_path, "**", "*.rb"))
-        end.uniq
-
-        if @since
-          changed_files = git_diff_analyzer.changed_files(from: @since, to: "HEAD")
-          changed_file_set = changed_files.map { |path| normalize_path(path) }
-
-          included_files.select do |path|
-            changed_file_set.include?(normalize_path(path))
-          end
-        else
-          included_files
-        end
-      end
+      @source_files ||= filter_changed(reject_excluded(included_source_files))
+    end
+
+    def included_source_files
+      Array(config.includes).flat_map do |include_path|
+        Dir.glob(File.join(include_path, "**", "*.rb"))
+      end.uniq
+    end
+
+    # Drops files matched by any `excludes:` glob (e.g. standalone entry points
+    # that cannot be mutation-tested in-process). Excludes apply regardless of
+    # the --since filter.
+    def reject_excluded(files)
+      excluded = excluded_source_files
+      return files if excluded.empty?
+
+      files.reject { |path| excluded.include?(normalize_path(path)) }
+    end
+
+    def excluded_source_files
+      Array(config.excludes)
+        .flat_map { |pattern| Dir.glob(pattern) }
+        .map { |path| normalize_path(path) }
+    end
+
+    def filter_changed(files)
+      return files unless @since
+
+      changed_file_set = git_diff_analyzer
+                         .changed_files(from: @since, to: "HEAD")
+                         .map { |path| normalize_path(path) }
+      files.select { |path| changed_file_set.include?(normalize_path(path)) }
     end
 
     def pattern_subjects
@@ -227,167 +259,12 @@ module Henitai
       !@survivors_from.nil?
     end
 
-    def apply_survivor_selection(mutants)
-      return mutants unless survivor_rerun?
-
-      dirty_worktree_files = dirty_worktree_changed_files
-      loaded   = SurvivorLoader.new(@survivors_from, include_paths: Array(config.includes)).load
-      selector = SurvivorSelector.new(survivor_ids: loaded.survivor_ids)
-      selected = selector.select(mutants)
-      finalize_survivor_split(
-        selector,
-        selected,
-        test_filter(
-          loaded,
-          dirty_source_files: dirty_source_files?(dirty_worktree_files, git_sha: loaded.git_sha)
-        ).apply(selected)
+    def survivor_strategy
+      @survivor_strategy ||= SurvivorRerunStrategy.new(
+        survivors_from: @survivors_from,
+        config:,
+        git_diff_analyzer:
       )
     end
-
-    # Attempts to run survivors directly from pre-computed activation recipes,
-    # bypassing source parsing and mutant generation entirely.
-    # Returns the mutant array on success, or nil if recipes are unavailable.
-    def try_recipe_run
-      dirty_worktree_files = dirty_worktree_changed_files
-      loaded = load_survivor_report
-      return nil unless recipe_fast_path_safe?(loaded, dirty_worktree_files)
-
-      run_from_recipes(loaded, dirty_worktree_files)
-    end
-
-    def load_survivor_report
-      SurvivorLoader.new(@survivors_from, include_paths: Array(config.includes)).load
-    end
-
-    def run_from_recipes(loaded, dirty_worktree_files)
-      recipes = load_activation_recipes(loaded.survivor_ids)
-      return nil if recipes.nil?
-
-      selector, stubs = recipe_selector_and_stubs(loaded.survivor_ids, recipes)
-      split = test_filter(
-        loaded,
-        dirty_source_files: dirty_source_files?(dirty_worktree_files, git_sha: loaded.git_sha)
-      ).apply(stubs)
-      finalize_survivor_split(selector, stubs, split)
-    end
-
-    def recipe_fast_path_safe?(loaded, dirty_worktree_files)
-      !dirty_source_files?(dirty_worktree_files, git_sha: loaded.git_sha)
-    end
-
-    # Builds stub Mutants from recipes and a SurvivorSelector primed with the
-    # survivor ID set. The selector is given a synthetic #select call so that
-    # #drift_warning? / #unmatched_ids are available (all IDs will be matched).
-    def recipe_selector_and_stubs(survivor_ids, recipes)
-      stubs    = survivor_ids.map { |id| build_stub_mutant(id, recipes[id]) }
-      selector = SurvivorSelector.new(survivor_ids:)
-      selector.select(stubs)
-      [selector, stubs]
-    end
-
-    # Returns the recipe hash if the file exists and covers every survivor ID;
-    # otherwise returns nil to trigger the normal generation path.
-    def load_activation_recipes(survivor_ids)
-      path    = File.join(File.dirname(@survivors_from), SurvivorActivationCache::FILENAME)
-      recipes = SurvivorActivationCache.load(path)
-      return nil if recipes.nil?
-      return nil unless survivor_ids.all? { |id| recipes.key?(id) }
-
-      recipes
-    end
-
-    def build_stub_mutant(stable_id, recipe)
-      mutant = Mutant.new(
-        subject: stub_subject_from_recipe(recipe),
-        operator: recipe.fetch("operator"),
-        nodes: { original: nil, mutated: nil },
-        description: recipe.fetch("description"),
-        location: recipe_location(recipe["location"]),
-        precomputed_stable_id: stable_id,
-        precomputed_activation_source: recipe.fetch("activationSource")
-      )
-      mutant.covered_by = recipe["coveredBy"]
-      mutant
-    end
-
-    def stub_subject_from_recipe(recipe)
-      Subject.new(
-        namespace: recipe["namespace"],
-        method_name: recipe["methodName"],
-        method_type: (recipe["methodType"] || "instance").to_sym,
-        source_location: { file: recipe["sourceFile"], range: nil }
-      )
-    end
-
-    def recipe_location(loc)
-      return {} unless loc.is_a?(Hash)
-
-      {
-        file: loc["file"],
-        start_line: loc["startLine"],
-        end_line: loc["endLine"],
-        start_col: loc["startCol"],
-        end_col: loc["endCol"]
-      }.compact
-    end
-
-    def finalize_survivor_split(selector, selected, split)
-      split[:stable].each { |m| m.status = :survived }
-      warn_survivor_drift(selector) if selector.drift_warning?
-      @survivor_stats = build_survivor_stats(selector, selected, split)
-      split[:stable] + split[:pending]
-    end
-
-    def test_filter(loaded, dirty_source_files: false)
-      SurvivorTestFilter.new(
-        coverage_map: loaded.coverage_map,
-        git_sha: loaded.git_sha,
-        dirty_source_files:,
-        worktree_changed_files: Array(dirty_worktree_changed_files),
-        diff_analyzer: git_diff_analyzer
-      )
-    end
-
-    def dirty_worktree_changed_files
-      @dirty_worktree_changed_files ||= git_diff_analyzer.working_tree_changed_files
-    rescue StandardError
-      nil
-    end
-
-    def dirty_source_files?(dirty_worktree_files, git_sha: nil)
-      return true if dirty_worktree_files.nil?
-
-      all_changed = dirty_worktree_files + committed_changed_files(git_sha)
-      include_roots = Array(config.includes).map { |path| normalize_path(path) }
-      all_changed.any? { |path| in_include_root?(normalize_path(path), include_roots) }
-    rescue StandardError
-      true
-    end
-
-    def committed_changed_files(git_sha)
-      return [] unless git_sha
-
-      git_diff_analyzer.changed_files(from: git_sha, to: "HEAD")
-    end
-
-    def in_include_root?(path, include_roots)
-      include_roots.any? { |root| path == root || path.start_with?("#{root}/") }
-    end
-
-    def warn_survivor_drift(selector)
-      warn "henitai: WARNING: #{selector.unmatched_ids.size} prior survivors " \
-           "could not be matched; the source may have drifted - consider a full run"
-    end
-
-    def build_survivor_stats(selector, selected, split)
-      {
-        matched: selected.size,
-        unmatched_count: selector.unmatched_ids.size,
-        unmatched_ids: selector.unmatched_ids,
-        skipped_count: split[:stable].size,
-        drift_warning: selector.drift_warning?
-      }
-    end
   end
-  # rubocop:enable Metrics/ClassLength
 end

data/lib/henitai/slot_scheduler/draining.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Drain/timeout state machine for in-flight slots.
+    #
+    # A slot enters the draining state either when it exceeds its timeout
+    # ({#check_timeouts}) or when a shutdown is requested
+    # ({#interrupt_active_slots}). {#drain_draining_slots} then performs the
+    # two-phase SIGTERM/SIGKILL broadcast and the final blocking reap.
+    #
+    # Mixed into {SlotScheduler}; relies on its slot table, +integration+,
+    # +progress_reporter+, +wakeup+ and the {ProcessControl} primitives.
+    module Draining
+      # Per-slot timeout check. Must be called after reap_all_completed_children
+      # so that naturally-exited processes are already removed from slots.
+      def check_timeouts
+        now = monotonic_time
+        slots.each_value do |slot|
+          next if slot.draining
+          next unless now >= slot.started_at_monotonic + slot.timeout
+
+          # Final targeted reap: if the child already exited, classify it normally.
+          pid, status = wnohang_reap(slot.pid)
+          if pid
+            complete_slot(pid, status)
+          else
+            slot.forced_outcome = :timeout
+            slot.draining = true
+          end
+        end
+      end
+
+      def draining_slots?
+        slots.any? { |_, slot| slot.draining }
+      end
+
+      # Two-phase broadcast cleanup for all slots that are in draining state.
+      #
+      # Precision rule: before signalling, do one final WNOHANG pass to catch
+      # processes that exited naturally in the window between check_timeouts and
+      # now. If SIGTERM gets ESRCH, the process is already gone — we must not
+      # force-label those as :timeout.
+      def drain_draining_slots
+        draining = draining_slots
+        return if draining.empty?
+
+        prune_raced_draining_slots(draining)
+
+        return if draining.empty?
+
+        broadcast_term(draining)
+        wait_for_drain_window
+        signal_draining_slots(draining)
+        reap_and_remove_draining(draining)
+      end
+
+      def interrupt_active_slots
+        slots.each_value do |slot|
+          next if slot.draining
+
+          slot.forced_outcome = :interrupted
+          slot.draining = true
+        end
+      end
+
+      private
+
+      def draining_slots
+        slots.select { |_, slot| slot.draining }
+      end
+
+      def prune_raced_draining_slots(draining)
+        draining.reject! do |_, slot|
+          pid, status = wnohang_reap(slot.pid)
+          next false unless pid
+
+          complete_slot(pid, status)
+          true
+        end
+      end
+
+      def wait_for_drain_window
+        wakeup&.wait(PROCESS_DRAIN_WINDOW)
+        wakeup&.drain
+      end
+
+      def signal_draining_slots(draining)
+        draining.each_value { |slot| signal_process_group(slot.pid, :SIGKILL) }
+      end
+
+      def broadcast_term(draining)
+        now = monotonic_time
+        draining.each_value do |slot|
+          slot.term_sent_at_monotonic = now
+          signal_process_group(slot.pid, :SIGTERM)
+        end
+      end
+
+      # After SIGKILL window: blocking reap each slot, then build its result.
+      #
+      # Interrupted slots are cleaned up but produce no result — the scheduler
+      # is shutting down and does not emit verdicts for in-flight mutants.
+      #
+      # For timeout slots: a real exit status only wins if observed before any
+      # parent signal was sent. Once SIGTERM has been dispatched, the forced
+      # outcome is authoritative — a child handling SIGTERM and exiting 0 must
+      # not be misclassified as :survived.
+      def reap_and_remove_draining(draining) # rubocop:disable Metrics/AbcSize
+        draining.each_value do |slot|
+          # One last WNOHANG before blocking: catches processes that exited
+          # between SIGKILL and here.
+          _, final_status = wnohang_reap(slot.pid)
+          reap_pid(slot.pid) unless final_status
+
+          pid_to_slot.delete(slot.pid)
+          slots.delete(slot.slot_id)
+          Integration::SchedulerDiagnostics.child_ended(slot.pid)
+
+          next if slot.forced_outcome == :interrupted
+
+          result = build_drain_result(slot, final_status)
+          slot.mutant.status = result.status
+          results << result
+          progress_reporter&.progress(slot.mutant, scenario_result: result)
+        end
+      end
+
+      # Choose result: use real exit status only if observed before any parent
+      # signal was sent. After SIGTERM, the forced outcome is authoritative.
+      def build_drain_result(slot, final_status)
+        if final_status&.exited? && slot.term_sent_at_monotonic.nil?
+          integration.build_result(final_status, slot.log_paths)
+        else
+          integration.build_result(slot.forced_outcome || :timeout, slot.log_paths)
+        end
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler/process_control.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Low-level bridge to the OS process and signal primitives.
+    #
+    # Every Process.wait*/kill call routes through +runtime+ so that the
+    # scheduler remains the single caller of the process table. Mixed into
+    # {SlotScheduler}; relies on its +runtime+ reader.
+    module ProcessControl
+      private
+
+      def monotonic_time
+        runtime.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def wnohang_reap(pid)
+        runtime.wait2(pid, Process::WNOHANG)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+
+      def signal_process_group(pid, signal)
+        runtime.kill(signal, -pid)
+      rescue Errno::ESRCH
+        nil
+      rescue Errno::EPERM
+        # Process group not yet established; fall back to signalling the pid.
+        begin
+          runtime.kill(signal, pid)
+        rescue Errno::ESRCH
+          nil
+        end
+      end
+
+      def reap_pid(pid)
+        runtime.wait(pid)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative "slot_scheduler/process_control"
+require_relative "slot_scheduler/draining"
+
+module Henitai
+  # Owns the process-slot table for a single parallel mutation run.
+  #
+  # {ProcessWorkerRunner} drives the event loop and OS signal handling and
+  # delegates every slot operation here: filling idle slots, reaping completed
+  # children, retrying flaky survivors, detecting timeouts and running the
+  # drain/broadcast state machine. Keeping the table behind one collaborator
+  # means Process.wait* has a single caller, so there are no races between
+  # threads reaping the same child.
+  #
+  # The drain/timeout state machine lives in {Draining}; the low-level process
+  # and signal primitives live in {ProcessControl}. +host+ is the owning
+  # {ProcessWorkerRunner}, which supplies +runtime+, +wakeup+, +worker_count+
+  # and the shutdown flag.
+  class SlotScheduler
+    include ProcessControl
+    include Draining
+
+    PROCESS_DRAIN_WINDOW = 0.2
+
+    # Tracks one in-flight mutant child process.
+    Slot = Struct.new(
+      :slot_id, :mutant, :pid, :started_at_monotonic, :timeout,
+      :log_paths, :retry_count, :draining, :term_sent_at_monotonic,
+      :forced_outcome
+    )
+
+    # @return [Integer] mutants that required at least one retry during the run.
+    # @return [Array<ScenarioExecutionResult>] verdicts accumulated so far.
+    attr_reader :flaky_retry_count, :results
+
+    def initialize(integration:, config:, progress_reporter:, options:, host:)
+      @integration = integration
+      @config = config
+      @progress_reporter = progress_reporter
+      @options = options
+      @host = host
+      @pending = []
+      @slots = {}
+      @pid_to_slot = {}
+      @results = []
+      @flaky_retry_count = 0
+      @next_slot_id = 0
+    end
+
+    # Queues the mutants to be scheduled into worker slots.
+    def enqueue(mutants)
+      @pending = mutants.dup
+    end
+
+    def done?
+      pending.empty? && slots.empty?
+    end
+
+    def fill_idle_slots
+      while slots.size < worker_count && !pending.empty?
+        mutant = pending.shift
+        spawn_into_slot(mutant)
+      end
+    end
+
+    def reap_all_completed_children
+      loop do
+        pid, status = runtime.wait2(-1, Process::WNOHANG)
+        break unless pid
+
+        complete_slot(pid, status)
+      end
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def next_event_timeout
+      now = monotonic_time
+      slot_timeouts = slots.each_value.filter_map do |slot|
+        remaining_slot_timeout(slot, now)
+      end
+
+      slot_timeouts.min
+    end
+
+    private
+
+    attr_reader :pending, :slots, :pid_to_slot, :integration, :config,
+                :progress_reporter, :options, :host
+
+    def worker_count = host.worker_count
+    def runtime = host.runtime
+    def wakeup = host.wakeup
+    def shutdown? = host.shutdown_requested?
+
+    def spawn_into_slot(mutant)
+      test_files = resolve_test_files(mutant)
+      mutant.covered_by = test_files if mutant.respond_to?(:covered_by=)
+      mutant.tests_completed = test_files.size if mutant.respond_to?(:tests_completed=)
+      handle = integration.spawn_mutant(mutant: mutant, test_files: test_files)
+      register_slot(handle, mutant)
+    rescue StandardError => e
+      record_spawn_failure(mutant, e)
+    end
+
+    def register_slot(handle, mutant)
+      slot_id = next_slot_id!
+      slot = build_slot(slot_id, mutant, handle)
+      slots[slot_id] = slot
+      pid_to_slot[handle.pid] = slot_id
+      Integration::SchedulerDiagnostics.child_started(handle.pid)
+    end
+
+    def build_slot(slot_id, mutant, handle)
+      Slot.new(
+        slot_id, mutant, handle.pid,
+        monotonic_time,
+        config.timeout, handle.log_paths, 0, false, nil, nil
+      )
+    end
+
+    def complete_slot(pid, wait_result)
+      slot_id = pid_to_slot.delete(pid)
+      return unless slot_id
+
+      slot = slots[slot_id]
+      return unless slot
+
+      Integration::SchedulerDiagnostics.child_ended(pid)
+      result = integration.build_result(wait_result, slot.log_paths)
+      dispatch_slot_result(slot, result)
+    end
+
+    def dispatch_slot_result(slot, result)
+      if should_retry?(slot, result)
+        retry_slot(slot)
+      else
+        slots.delete(slot.slot_id)
+        slot.mutant.status = result.status
+        results << result
+        progress_reporter&.progress(slot.mutant, scenario_result: result)
+      end
+    end
+
+    def should_retry?(slot, result)
+      !shutdown? && result.survived? && slot.retry_count < config.max_flaky_retries.to_i
+    end
+
+    def retry_slot(slot) # rubocop:disable Metrics/AbcSize
+      @flaky_retry_count += 1 if slot.retry_count.zero?
+      slot.retry_count += 1
+      test_files = resolve_test_files(slot.mutant)
+      handle = integration.spawn_mutant(mutant: slot.mutant, test_files: test_files)
+      slot.pid = handle.pid
+      slot.log_paths = handle.log_paths
+      slot.started_at_monotonic = monotonic_time
+      slot.draining = false
+      slot.term_sent_at_monotonic = nil
+      slot.forced_outcome = nil
+      pid_to_slot[handle.pid] = slot.slot_id
+      Integration::SchedulerDiagnostics.child_started(handle.pid)
+    rescue StandardError => e
+      slots.delete(slot.slot_id)
+      record_spawn_failure(slot.mutant, e)
+    end
+
+    def record_spawn_failure(mutant, error)
+      result = ScenarioExecutionResult.new(
+        status: :compile_error,
+        stdout: "",
+        stderr: "spawn failed: #{error.message}",
+        log_path: "/dev/null",
+        exit_status: nil
+      )
+      mutant.status = result.status
+      results << result
+      progress_reporter&.progress(mutant, scenario_result: result)
+    end
+
+    def remaining_slot_timeout(slot, now)
+      # Invariant: drain_draining_slots runs (and removes draining slots) before
+      # the event wait, so next_event_timeout never observes a draining slot
+      # whose SIGTERM has not been sent. Guard term_sent_at_monotonic defensively
+      # against a future ordering change: an unsignalled draining slot is due now.
+      return 0.0 if slot.draining && slot.term_sent_at_monotonic.nil?
+
+      deadline =
+        if slot.draining
+          slot.term_sent_at_monotonic + PROCESS_DRAIN_WINDOW
+        else
+          slot.started_at_monotonic + slot.timeout
+        end
+      remaining = deadline - now
+      remaining.positive? ? remaining : 0.0
+    end
+
+    def resolve_test_files(mutant)
+      if @options.key?(:test_file_resolver)
+        @options[:test_file_resolver].call(mutant)
+      elsif @options.key?(:test_files)
+        @options[:test_files]
+      else
+        integration.select_tests(mutant.subject)
+      end
+    end
+
+    def next_slot_id!
+      id = @next_slot_id
+      @next_slot_id += 1
+      id
+    end
+  end
+end