henitai 0.3.1 → 0.5.0

data/lib/henitai/process_liveness.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Answers whether a process id is still running.
+  #
+  # Extracted so the one subtle rule here lives in a single place: EPERM means
+  # the process exists but belongs to someone else, so it counts as *alive*.
+  # Only ESRCH proves it is gone. Getting that backwards would let
+  # OrphanWatchdog kill live children, and would make the reports-directory
+  # lock report a running owner as dead.
+  module ProcessLiveness
+    # Captured at load time, before any test double can replace
+    # `Process.kill`. A `Method` object keeps pointing at the original
+    # definition even after the singleton method is redefined, which is what
+    # makes this immune to stubbing.
+    #
+    # This is not defensiveness for its own sake: a mutant child runs the host
+    # project's own suite, and a spec in that suite stubbing `Process.kill` to
+    # raise ESRCH made this answer "parent is dead" while the parent was very
+    # much alive. OrphanWatchdog then exited the child, which the scheduler
+    # recorded as CompileError. Observed on henitai's own dogfood run.
+    KILL = Process.method(:kill)
+
+    # @param pid [Integer, nil] process id to probe
+    # @param kill [#call] signalling primitive; injected only by specs, which
+    #   cannot reach {KILL} by stubbing and must not be able to
+    # @return [Boolean] false only when the pid provably does not exist
+    def self.alive?(pid, kill: KILL)
+      return false unless pid.is_a?(Integer)
+
+      kill.call(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue StandardError
+      # EPERM and anything unexpected: assume alive, the conservative answer
+      # for every caller.
+      true
+    end
+  end
+end

data/lib/henitai/reports_directory_lock.rb

@@ -18,7 +18,17 @@ module Henitai
       File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |file|
         acquire(file)
         write_owner(file)
-        yield
+        # Registered so a forked mutant child can close its inherited copy: the
+        # flock lives on the shared open file description, so a child that
+        # outlives its parent would otherwise keep this lock held. Unregistered
+        # inside the File.open block, keeping the registration's lifetime a
+        # subset of the handle's.
+        InheritedFdRegistry.register(file)
+        begin
+          yield
+        ensure
+          InheritedFdRegistry.unregister(file)
+        end
       end
     end
 
@@ -55,16 +65,7 @@ module Henitai
 
     # True only when the recorded owner pid provably no longer exists. EPERM
     # means the process is alive but owned by someone else — treated as alive.
-    def dead_owner?(pid)
-      return false unless pid.is_a?(Integer)
-
-      Process.kill(0, pid)
-      false
-    rescue Errno::ESRCH
-      true
-    rescue StandardError
-      false
-    end
+    def dead_owner?(pid) = !ProcessLiveness.alive?(pid)
 
     def write_owner(file)
       file.rewind

data/lib/henitai/result.rb

@@ -15,8 +15,28 @@ module Henitai
     SCHEMA_VERSION = "1.0"
     DEFAULT_THRESHOLDS = { high: 80, low: 60 }.freeze
 
+    # Which outcomes count as "the test suite detected this mutant" for the MS
+    # numerator. Duplicated from Configuration rather than read from it: Result
+    # is a domain object and must not depend on configuration loading. The same
+    # arrangement already exists for DEFAULT_THRESHOLDS, and result_spec asserts
+    # the two constants stay equal.
+    DEFAULT_COVERAGE_CRITERIA = {
+      test_result: true,
+      timeout: true,
+      process_abort: true
+    }.freeze
+
+    # Maps each criterion to the mutant status it governs. process_abort has no
+    # producer in lib/ yet -- nothing classifies a mutant as :runtime_error --
+    # so that entry is forward-looking wiring rather than a live code path.
+    CRITERION_STATUSES = {
+      test_result: :killed,
+      timeout: :timeout,
+      process_abort: :runtime_error
+    }.freeze
+
     attr_reader :mutants, :started_at, :finished_at, :thresholds, :survivor_stats,
-                :session_id, :git_sha, :since
+                :session_id, :git_sha, :since, :coverage_criteria
 
     # @param source_provider [#call] maps a file path to its source string.
     #   Injected so the domain object performs no disk IO; the caller (which
@@ -33,7 +53,7 @@ module Henitai
                    partial_rerun: false, survivor_stats: nil,
                    session_id: SecureRandom.uuid, git_sha: nil,
                    source_provider: ->(_file) { "" }, authoritative: true,
-                   since: nil)
+                   since: nil, coverage_criteria: nil)
       @mutants         = mutants
       @started_at      = started_at
       @finished_at     = finished_at
@@ -45,6 +65,7 @@ module Henitai
       @source_provider = source_provider
       @authoritative   = authoritative
       @since           = since
+      @coverage_criteria = DEFAULT_COVERAGE_CRITERIA.merge(coverage_criteria || {})
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -140,7 +161,13 @@ module Henitai
     private
 
     def detected_in(list)
-      list.count { |m| %i[killed timeout runtime_error].include?(m.status) }
+      list.count { |m| detected_statuses.include?(m.status) }
+    end
+
+    def detected_statuses
+      @detected_statuses ||= CRITERION_STATUSES.filter_map do |criterion, status|
+        status if @coverage_criteria[criterion]
+      end
     end
 
     def mutation_score_for(list)

data/lib/henitai/runner.rb

@@ -30,9 +30,16 @@ module Henitai
 
     # @param mode [Hash] execution-mode flags: +dry_run:+ stops before Gate 4,
     #   +incremental:+ reuses still-valid Killed verdicts from history.
+    # +deps+ is assigned in the body, not defaulted in the signature: the
+    # default needs @config, and `config:` itself defaults to a load.
+    #
+    # rubocop:disable Metrics/ParameterLists -- these are the CLI's own flags
+    # plus the dependency seam; a params object would only move the list.
     def initialize(config: Configuration.load, subjects: nil, since: nil, survivors_from: nil,
-                   mode: {})
+                   mode: {}, deps: nil)
+      # rubocop:enable Metrics/ParameterLists
       @config         = config
+      @deps           = deps || RunnerDependencies.new(config: @config)
       @subjects       = subjects
       @since          = since
       @survivors_from = survivors_from
@@ -88,13 +95,13 @@ module Henitai
     end
 
     def resolve_subjects(source_files = self.source_files)
-      subjects = subject_resolver.resolve_from_files(source_files)
-      return subjects if pattern_subjects.empty?
+      subject_selection.resolve(source_files)
+    end
 
-      selected_subjects = pattern_subjects.flat_map do |pattern|
-        subject_resolver.apply_pattern(subjects, pattern.expression)
-      end
-      unique_subjects(selected_subjects)
+    def subject_selection
+      @subject_selection ||= SubjectSelection.new(
+        subject_resolver: subject_resolver, patterns: @subjects
+      )
     end
 
     def generate_mutants(subjects)
@@ -164,6 +171,7 @@ module Henitai
         started_at:,
         finished_at:,
         thresholds: result_thresholds,
+        coverage_criteria: result_coverage_criteria,
         partial_rerun: survivor_rerun?,
         survivor_stats: survivor_strategy.survivor_stats,
         git_sha: safe_head_sha,
@@ -173,20 +181,6 @@ module Henitai
       )
     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
@@ -199,123 +193,47 @@ module Henitai
       coverage_bootstrapper.ensure!(source_files:, config:, integration:, test_files:)
     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
+    attr_reader :deps
 
-    def coverage_bootstrapper = @coverage_bootstrapper ||= CoverageBootstrapper.new
+    def subject_resolver = deps.subject_resolver
+    def git_diff_analyzer = deps.git_diff_analyzer
+    def mutant_generator = deps.mutant_generator
+    def static_filter = deps.static_filter
+    def execution_engine = deps.execution_engine
+    def coverage_bootstrapper = deps.coverage_bootstrapper
+    def integration = deps.integration
+    def operators = deps.operators
+    def history_store = deps.history_store
+    def per_test_coverage = deps.per_test_coverage
+    def source_provider = deps.source_provider
 
-    def integration
-      @integration ||= Integration.for(config.integration).new
-    end
-
-    def operators
-      @operators ||= Operator.for_set(config.operators)
-    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.
-    def progress_reporter
-      CompositeProgressReporter.for(config:, source_provider:, full_run: full_run?)
-    end
-
-    def history_store
-      @history_store ||= MutantHistoryStore.new(
-        path: File.join(config.reports_dir, Henitai::HISTORY_STORE_FILENAME), per_test_coverage:
-      )
-    end
-
-    # One shared live view of the per-test coverage map: the incremental
-    # filter proves survivor reuse against it and the history store records
-    # the same intersection set — one implementation, one snapshot.
-    def per_test_coverage
-      @per_test_coverage ||= PerTestCoverage.new(reports_dir: config.reports_dir)
-    end
+    def progress_reporter = deps.progress_reporter(full_run: full_run?)
 
     def source_files
-      @source_files ||= filter_changed(reject_excluded(included_source_files))
+      @source_files ||= source_file_selection.call
     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 = changed_paths_since.map { |path| normalize_path(path) }
-      changed_file_set += covered_sources_for_changed_tests(changed_file_set)
-      files.select { |path| changed_file_set.include?(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 pattern_subjects
-      Array(@subjects)
-    end
-
-    def unique_subjects(subjects)
-      subjects.uniq { |subject| [subject.expression, subject.source_file] }
+    def source_file_selection
+      @source_file_selection ||= SourceFileSelection.new(
+        config: config, since: @since,
+        git_diff_analyzer: git_diff_analyzer, per_test_coverage: per_test_coverage
+      )
     end
 
-    def normalize_path(path)
-      File.expand_path(path)
-    end
+    def result_thresholds = optional_config(:thresholds)
 
-    def result_thresholds
-      return nil unless config.respond_to?(:thresholds)
+    def result_coverage_criteria = optional_config(:coverage_criteria)
 
-      config.thresholds
-    end
+    # Specs pass bare config doubles that expose only what the example needs, so
+    # scoring inputs are read defensively rather than assumed present.
+    def optional_config(name) = config.respond_to?(name) ? config.public_send(name) : nil
 
-    def survivor_rerun?
-      !@survivors_from.nil?
-    end
+    def survivor_rerun? = !@survivors_from.nil?
 
     # Mutation-scope full run, controlling Result#authoritative? — distinct
     # from the per-test-coverage plan's test-suite-scope "full run".
     def full_run?
-      pattern_subjects.empty? && @since.nil? && !survivor_rerun?
+      Array(@subjects).empty? && @since.nil? && !survivor_rerun?
     end
 
     def survivor_strategy

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