henitai 0.4.0 → 0.5.0

data/lib/henitai/runner_dependencies.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Henitai
+  # The collaborators {Runner} drives, built on first use.
+  #
+  # Extracted so each one can be asserted on directly — several are chosen by
+  # configuration (the integration adapter, the operator set, which progress
+  # reporters are composed) and that choice had no test seam while it lived
+  # behind private readers on `Runner`.
+  #
+  # Memoization is not an optimisation here, it is a correctness requirement for
+  # {#per_test_coverage} and {#history_store}: the incremental filter proves
+  # survivor reuse against the same live coverage map the history store records
+  # its intersection set from. Two instances would be two snapshots.
+  class RunnerDependencies
+    def initialize(config:)
+      @config = config
+    end
+
+    def subject_resolver = @subject_resolver ||= SubjectResolver.new
+    def git_diff_analyzer = @git_diff_analyzer ||= GitDiffAnalyzer.new
+    def mutant_generator = @mutant_generator ||= MutantGenerator.new
+    def static_filter = @static_filter ||= StaticFilter.new
+    def execution_engine = @execution_engine ||= ExecutionEngine.new
+    def coverage_bootstrapper = @coverage_bootstrapper ||= CoverageBootstrapper.new
+
+    def integration
+      @integration ||= Integration.for(@config.integration).new
+    end
+
+    def operators
+      @operators ||= Operator.for_set(@config.operators)
+    end
+
+    def per_test_coverage
+      @per_test_coverage ||= PerTestCoverage.new(reports_dir: @config.reports_dir)
+    end
+
+    def history_store
+      @history_store ||= MutantHistoryStore.new(
+        path: File.join(@config.reports_dir, Henitai::HISTORY_STORE_FILENAME),
+        per_test_coverage: per_test_coverage
+      )
+    end
+
+    # Fans progress out to the terminal reporter (when enabled) and the
+    # checkpoint writer (when enabled and a file report is configured), so a
+    # long run persists partial results incrementally.
+    #
+    # Deliberately *not* memoized: `full_run?` is a property of the invocation,
+    # not of the dependency set, and a cached reporter would silently keep the
+    # first answer.
+    def progress_reporter(full_run:)
+      CompositeProgressReporter.for(config: @config, source_provider: source_provider, full_run: full_run)
+    end
+
+    # Reads each source file once and caches it per path, so Result consumes
+    # source content while performing no disk IO of its own. Unreadable files
+    # (recipe stubs with synthetic locations, say) answer "" rather than
+    # aborting the run.
+    #
+    # Not memoized: each call gets its own cache, scoped to one reporter's
+    # lifetime rather than shared across the process.
+    def source_provider
+      cache = {} # : Hash[String, String]
+      lambda do |file|
+        cache[file] ||= begin
+          File.read(file)
+        rescue StandardError
+          ""
+        end
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler/drain_verdict.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Chooses the verdict for a slot that went through the drain path.
+    #
+    # The rule: a real exit status only wins if the process exited *before* any
+    # parent signal was sent. Once SIGTERM has been dispatched, the forced
+    # outcome is authoritative — a child that traps SIGTERM and exits 0 would
+    # otherwise be recorded as `:survived`, turning a timeout into a false
+    # survivor and inflating the survivor list.
+    #
+    # `:timeout` is the fallback when nothing forced the outcome, because the
+    # only way into this path without a forced outcome is a deadline breach.
+    class DrainVerdict
+      def initialize(integration:)
+        @integration = integration
+      end
+
+      def build(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/draining.rb

@@ -16,7 +16,7 @@ module Henitai
       # so that naturally-exited processes are already removed from slots.
       def check_timeouts
         now = monotonic_time
-        slots.each_value do |slot|
+        slot_table.each_value do |slot|
           next if slot.draining
           next unless now >= slot.started_at_monotonic + slot.timeout
 
@@ -32,7 +32,7 @@ module Henitai
       end
 
       def draining_slots?
-        slots.any? { |_, slot| slot.draining }
+        slot_table.any_draining?
       end
 
       # Two-phase broadcast cleanup for all slots that are in draining state.
@@ -56,7 +56,7 @@ module Henitai
       end
 
       def interrupt_active_slots
-        slots.each_value do |slot|
+        slot_table.each_value do |slot|
           next if slot.draining
 
           slot.forced_outcome = :interrupted
@@ -67,7 +67,7 @@ module Henitai
       private
 
       def draining_slots
-        slots.select { |_, slot| slot.draining }
+        slot_table.draining
       end
 
       def prune_raced_draining_slots(draining)
@@ -116,8 +116,8 @@ module Henitai
         _, final_status = wnohang_reap(slot.pid)
         reap_pid(slot.pid) unless final_status
 
-        pid_to_slot.delete(slot.pid)
-        slots.delete(slot.slot_id)
+        slot_table.release_pid(slot.pid)
+        slot_table.delete(slot.slot_id)
         Integration::SchedulerDiagnostics.child_ended(slot.pid)
 
         return if slot.forced_outcome == :interrupted
@@ -126,21 +126,11 @@ module Henitai
       end
 
       def record_drain_result(slot, final_status)
-        result = build_drain_result(slot, final_status)
+        result = drain_verdict.build(slot, final_status)
         slot.mutant.status = result.status
         results << result
         progress_reporter&.progress(slot.mutant, scenario_result: result)
       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/retry_policy.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Decides whether a finished slot earns another attempt.
+    #
+    # A survived verdict is the only retryable one: it is the verdict a flaky
+    # test can fake, whereas a kill cannot be faked by flakiness. A requested
+    # shutdown vetoes retries outright — respawning children while tearing the
+    # run down would leak processes past the drain window.
+    class RetryPolicy
+      def initialize(max_retries:)
+        @max_retries = max_retries.to_i
+      end
+
+      def retry?(slot:, result:, shutdown:)
+        !shutdown && result.survived? && slot.retry_count < @max_retries
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler/slot_deadline.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Seconds left before a slot is due, for the scheduler's event-wait budget.
+    #
+    # A live slot is due at `started_at + timeout`. A draining slot is due at
+    # `term_sent_at + drain_window` instead: once SIGTERM has gone out, the only
+    # remaining question is how long to wait before escalating to SIGKILL.
+    class SlotDeadline
+      def initialize(drain_window:)
+        @drain_window = drain_window
+      end
+
+      def remaining(slot, now)
+        # Invariant: drain_draining_slots runs (and removes draining slots)
+        # before the event wait, so this never observes a draining slot whose
+        # SIGTERM has not been sent. Guarded 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?
+
+        remaining = deadline_for(slot) - now
+        remaining.positive? ? remaining : 0.0
+      end
+
+      private
+
+      def deadline_for(slot)
+        if slot.draining
+          slot.term_sent_at_monotonic + @drain_window
+        else
+          slot.started_at_monotonic + slot.timeout
+        end
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler/slot_table.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # The slot table for one parallel run: live slots by id, the pid -> slot_id
+    # reverse index, and the slot-id sequence.
+    #
+    # Two indexes rather than one because the two lookups have different
+    # lifetimes. A slot survives a flaky retry and keeps its id, but its pid
+    # changes with every respawn, so the reverse index is rebuilt while the
+    # forward entry stays put.
+    class SlotTable
+      def initialize
+        @slots = {}
+        @pid_to_slot = {}
+        @next_slot_id = 0
+      end
+
+      def add(slot)
+        @slots[slot.slot_id] = slot
+      end
+
+      def delete(slot_id)
+        @slots.delete(slot_id)
+      end
+
+      def fetch(slot_id)
+        @slots[slot_id]
+      end
+
+      def empty? = @slots.empty?
+      def size = @slots.size
+      def each_value(&) = @slots.each_value(&)
+
+      def register_pid(pid, slot_id)
+        @pid_to_slot[pid] = slot_id
+      end
+
+      # Removes the mapping and answers the slot id it held, so a reap is a
+      # single operation: a pid can only be claimed once.
+      def release_pid(pid)
+        @pid_to_slot.delete(pid)
+      end
+
+      # Monotonic and never reused. Freed worker indices are recycled; slot ids
+      # are not, which is what makes them safe as hash keys across retries.
+      def next_slot_id!
+        id = @next_slot_id
+        @next_slot_id += 1
+        id
+      end
+
+      # Smallest index in 0...worker_count not held by a live slot, so
+      # concurrently-running children always see distinct values and freed
+      # indices are reused. Slot ids themselves grow monotonically and are
+      # unsuitable as a resource token.
+      #
+      # The `|| used.size` fallback covers a table already holding at least
+      # worker_count slots — reachable when a retry respawns into a table that
+      # a concurrent fill has since topped up.
+      def next_free_worker_index(worker_count)
+        used = @slots.each_value.map(&:worker_index)
+        (0...worker_count).find { |index| !used.include?(index) } || used.size
+      end
+
+      def draining
+        @slots.select { |_, slot| slot.draining }
+      end
+
+      def any_draining?
+        @slots.any? { |_, slot| slot.draining }
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler/test_file_selection.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Resolves the test files a mutant should be run against.
+    #
+    # Three sources, in precedence order: a caller-supplied resolver lambda, a
+    # fixed list, or the integration's own per-subject selection. The first two
+    # exist so a survivor rerun or a per-test-coverage run can narrow the
+    # selection without the integration knowing about it.
+    #
+    # Precedence is by key *presence*, not truthiness: an explicit empty list
+    # means "no tests cover this", which the scheduler turns into
+    # `:no_coverage`. Falling through to the integration there would silently
+    # widen the selection back out.
+    class TestFileSelection
+      def initialize(options:, integration:)
+        @options = options
+        @integration = integration
+      end
+
+      def for(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
+
+      # True when the resolver was asked and came back empty. Only meaningful
+      # for a resolver-driven run: a fixed empty `test_files` list is a
+      # deliberate "run nothing", not an absence of coverage.
+      def resolved_empty?(test_files)
+        @options.key?(:test_file_resolver) && test_files.empty?
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler.rb

@@ -2,6 +2,11 @@
 
 require_relative "slot_scheduler/process_control"
 require_relative "slot_scheduler/draining"
+require_relative "slot_scheduler/drain_verdict"
+require_relative "slot_scheduler/retry_policy"
+require_relative "slot_scheduler/slot_deadline"
+require_relative "slot_scheduler/slot_table"
+require_relative "slot_scheduler/test_file_selection"
 
 module Henitai
   # Owns the process-slot table for a single parallel mutation run.
@@ -40,18 +45,23 @@ module Henitai
     # @return [Array<ScenarioExecutionResult>] verdicts accumulated so far.
     attr_reader :flaky_retry_count, :results
 
-    def initialize(integration:, config:, progress_reporter:, options:, host:)
+    # +slot_table+ is injectable so a spec can seed mid-run state, or assert
+    # against the table through its own public interface, without reaching a
+    # private reader here.
+    # rubocop:disable Metrics/ParameterLists -- every one of these is a distinct
+    # collaborator supplied by ProcessWorkerRunner; bundling them into a context
+    # object would only move the list.
+    def initialize(integration:, config:, progress_reporter:, options:, host:, slot_table: SlotTable.new)
+      # rubocop:enable Metrics/ParameterLists
       @integration = integration
       @config = config
       @progress_reporter = progress_reporter
       @options = options
       @host = host
+      @slot_table = slot_table
       @pending = []
-      @slots = {}
-      @pid_to_slot = {}
       @results = []
       @flaky_retry_count = 0
-      @next_slot_id = 0
     end
 
     # Queues the mutants to be scheduled into worker slots.
@@ -60,11 +70,11 @@ module Henitai
     end
 
     def done?
-      pending.empty? && slots.empty?
+      pending.empty? && slot_table.empty?
     end
 
     def fill_idle_slots
-      while slots.size < worker_count && !pending.empty?
+      while slot_table.size < worker_count && !pending.empty?
         mutant = pending.shift
         spawn_into_slot(mutant)
       end
@@ -83,8 +93,8 @@ module Henitai
 
     def next_event_timeout
       now = monotonic_time
-      slot_timeouts = slots.each_value.filter_map do |slot|
-        remaining_slot_timeout(slot, now)
+      slot_timeouts = slot_table.each_value.filter_map do |slot|
+        slot_deadline.remaining(slot, now)
       end
 
       slot_timeouts.min
@@ -92,7 +102,7 @@ module Henitai
 
     private
 
-    attr_reader :pending, :slots, :pid_to_slot, :integration, :config,
+    attr_reader :pending, :slot_table, :integration, :config,
                 :progress_reporter, :options, :host
 
     def worker_count = host.worker_count
@@ -101,12 +111,12 @@ module Henitai
     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=)
-      return record_no_coverage(mutant) if resolved_selection_empty?(test_files)
+      selection = test_file_selection
+      test_files = selection.for(mutant)
+      annotate_selection(mutant, test_files)
+      return record_no_coverage(mutant) if selection.resolved_empty?(test_files)
 
-      worker_index = next_free_worker_index
+      worker_index = slot_table.next_free_worker_index(worker_count)
       with_worker_slot(worker_index) do
         handle = integration.spawn_mutant(mutant: mutant, test_files: test_files)
         register_slot(handle, mutant, worker_index, slot_timeout(mutant, test_files))
@@ -115,11 +125,18 @@ module Henitai
       record_spawn_failure(mutant, e)
     end
 
+    # Reported back onto the mutant so the report can show which tests were
+    # considered, whether or not any of them ran. Guarded by respond_to? because
+    # specs pass Struct stand-ins without these members.
+    def annotate_selection(mutant, test_files)
+      mutant.covered_by = test_files if mutant.respond_to?(:covered_by=)
+      mutant.tests_completed = test_files.size if mutant.respond_to?(:tests_completed=)
+    end
+
     def register_slot(handle, mutant, worker_index, timeout)
-      slot_id = next_slot_id!
-      slot = build_slot(slot_id, mutant, handle, worker_index, timeout)
-      slots[slot_id] = slot
-      pid_to_slot[handle.pid] = slot_id
+      slot = build_slot(slot_table.next_slot_id!, mutant, handle, worker_index, timeout)
+      slot_table.add(slot)
+      slot_table.register_pid(handle.pid, slot.slot_id)
       Integration::SchedulerDiagnostics.child_started(handle.pid)
     end
 
@@ -137,20 +154,11 @@ module Henitai
       resolver ? resolver.call(mutant, test_files) : config.timeout
     end
 
-    # Smallest index in 0...worker_count not held by a live slot, so
-    # concurrently-running children always see distinct values and freed
-    # indices are reused. Slot ids themselves grow monotonically and are
-    # unsuitable as a resource token.
-    def next_free_worker_index
-      used = slots.each_value.map(&:worker_index)
-      (0...worker_count).find { |index| !used.include?(index) } || used.size
-    end
-
     def complete_slot(pid, wait_result)
-      slot_id = pid_to_slot.delete(pid)
+      slot_id = slot_table.release_pid(pid)
       return unless slot_id
 
-      slot = slots[slot_id]
+      slot = slot_table.fetch(slot_id)
       return unless slot
 
       Integration::SchedulerDiagnostics.child_ended(pid)
@@ -159,29 +167,46 @@ module Henitai
     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)
-        result.release_output! if result.respond_to?(:release_output!)
-      end
+      return retry_slot(slot) if retry_policy.retry?(slot: slot, result: result, shutdown: shutdown?)
+
+      finalize_slot(slot, result)
+    end
+
+    def finalize_slot(slot, result)
+      slot_table.delete(slot.slot_id)
+      slot.mutant.status = result.status
+      results << result
+      progress_reporter&.progress(slot.mutant, scenario_result: result)
+      result.release_output! if result.respond_to?(:release_output!)
+    end
+
+    # Memoized lazily, not built in #initialize: specs (and the no-op scheduler
+    # the runner builds when nothing is pending) pass `config: nil`, and this
+    # is only reached once a slot has actually finished.
+    def retry_policy
+      @retry_policy ||= RetryPolicy.new(max_retries: config.max_flaky_retries)
+    end
+
+    def drain_verdict
+      @drain_verdict ||= DrainVerdict.new(integration: integration)
+    end
+
+    def slot_deadline
+      @slot_deadline ||= SlotDeadline.new(drain_window: PROCESS_DRAIN_WINDOW)
     end
 
-    def should_retry?(slot, result)
-      !shutdown? && result.survived? && slot.retry_count < config.max_flaky_retries.to_i
+    def test_file_selection
+      @test_file_selection ||= TestFileSelection.new(options: options, integration: integration)
     end
 
     def retry_slot(slot)
-      test_files = resolve_test_files(slot.mutant)
+      test_files = test_file_selection.for(slot.mutant)
       with_worker_slot(slot.worker_index) do
         handle = integration.spawn_mutant(mutant: slot.mutant, test_files: test_files)
         finish_retry(slot, handle)
       end
     rescue StandardError => e
-      slots.delete(slot.slot_id)
+      slot_table.delete(slot.slot_id)
       record_spawn_failure(slot.mutant, e)
     end
 
@@ -189,7 +214,7 @@ module Henitai
       @flaky_retry_count += 1 if slot.retry_count.zero?
       slot.retry_count += 1
       reset_slot_for_retry(slot, handle)
-      pid_to_slot[handle.pid] = slot.slot_id
+      slot_table.register_pid(handle.pid, slot.slot_id)
       Integration::SchedulerDiagnostics.child_started(handle.pid)
     end
 
@@ -220,43 +245,6 @@ module Henitai
       progress_reporter&.progress(mutant, scenario_result: nil)
     end
 
-    def resolved_selection_empty?(test_files)
-      options.key?(:test_file_resolver) && test_files.empty?
-    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
-
     def with_worker_slot(worker_index)
       previous = ENV.fetch(WORKER_SLOT_ENV, nil)
       ENV[WORKER_SLOT_ENV] = worker_index.to_s

data/lib/henitai/source_file_selection.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Resolves which source files a run mutates: everything under `includes:`,
+  # minus anything matched by `excludes:`, optionally narrowed to what changed
+  # since a git ref.
+  #
+  # Excludes are absolute, not a tiebreak: an excluded file (a standalone entry
+  # point that cannot be mutation-tested in-process, say) stays excluded even
+  # when it is the only thing that changed. Both stages are filters over the
+  # same list, so they commute — excludes run first only to keep the
+  # per-test-coverage lookups in `filter_changed` off files that are already
+  # out of scope.
+  class SourceFileSelection
+    def initialize(config:, since:, git_diff_analyzer:, per_test_coverage:)
+      @config = config
+      @since = since
+      @git_diff_analyzer = git_diff_analyzer
+      @per_test_coverage = per_test_coverage
+    end
+
+    def call
+      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. Compared as expanded paths so
+    # a relative glob and an absolute candidate still match.
+    def reject_excluded(files)
+      excluded = excluded_source_files
+      return files if excluded.empty?
+
+      files.reject { |path| excluded.include?(normalize_path(path)) }
+    end
+
+    def filter_changed(files)
+      return files unless @since
+
+      changed = changed_paths_since.map { |path| normalize_path(path) }
+      changed += covered_sources_for_changed_tests(changed)
+      files.select { |path| changed.include?(normalize_path(path)) }
+    end
+
+    private
+
+    def excluded_source_files
+      Array(@config.excludes)
+        .flat_map { |pattern| Dir.glob(pattern) }
+        .map { |path| normalize_path(path) }
+    end
+
+    # Committed changes since the ref plus the current working tree (tracked
+    # dirty and untracked files): the working tree is what gets tested, so it is
+    # always part of "changed since REF".
+    def changed_paths_since
+      @git_diff_analyzer.changed_files(from: @since, to: "HEAD") +
+        @git_diff_analyzer.working_tree_changed_files
+    end
+
+    # Changed test files select the source files they cover, so an edited test
+    # re-tests the subjects it can kill. Uses the per-test map from the previous
+    # run — Gate 1 runs before this run's bootstrap finishes.
+    def covered_sources_for_changed_tests(changed_paths)
+      changed_paths
+        .flat_map { |path| @per_test_coverage.source_files_covered_by(path) }
+        .map { |path| normalize_path(path) }
+    end
+
+    def normalize_path(path) = File.expand_path(path)
+  end
+end