henitai 0.2.1 → 0.3.1

data/lib/henitai/slot_scheduler.rb

@@ -23,11 +23,17 @@ module Henitai
 
     PROCESS_DRAIN_WINDOW = 0.2
 
+    # Environment variable exposing a stable worker-slot index (0..jobs-1) to
+    # each forked child so test suites can isolate shared resources per slot
+    # (e.g. "myapp_test_#{ENV['HENITAI_WORKER_SLOT']}"). A flaky-retry respawn
+    # keeps the original attempt's value.
+    WORKER_SLOT_ENV = "HENITAI_WORKER_SLOT"
+
     # 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
+      :forced_outcome, :worker_index
     )
 
     # @return [Integer] mutants that required at least one retry during the run.
@@ -98,28 +104,48 @@ module Henitai
       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)
+      return record_no_coverage(mutant) if resolved_selection_empty?(test_files)
+
+      worker_index = next_free_worker_index
+      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))
+      end
     rescue StandardError => e
       record_spawn_failure(mutant, e)
     end
 
-    def register_slot(handle, mutant)
+    def register_slot(handle, mutant, worker_index, timeout)
       slot_id = next_slot_id!
-      slot = build_slot(slot_id, mutant, handle)
+      slot = build_slot(slot_id, mutant, handle, worker_index, timeout)
       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)
+    def build_slot(slot_id, mutant, handle, worker_index, timeout)
       Slot.new(
         slot_id, mutant, handle.pid,
         monotonic_time,
-        config.timeout, handle.log_paths, 0, false, nil, nil
+        timeout, handle.log_paths, 0, false, nil, nil,
+        worker_index
       )
     end
 
+    def slot_timeout(mutant, test_files)
+      resolver = options[:timeout_resolver]
+      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)
       return unless slot_id
@@ -140,6 +166,7 @@ module Henitai
         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
     end
 
@@ -147,22 +174,32 @@ module Henitai
       !shutdown? && result.survived? && slot.retry_count < config.max_flaky_retries.to_i
     end
 
-    def retry_slot(slot) # rubocop:disable Metrics/AbcSize
+    def retry_slot(slot)
+      test_files = resolve_test_files(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)
+      record_spawn_failure(slot.mutant, e)
+    end
+
+    def finish_retry(slot, handle)
       @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)
+      reset_slot_for_retry(slot, handle)
+      pid_to_slot[handle.pid] = slot.slot_id
+      Integration::SchedulerDiagnostics.child_started(handle.pid)
+    end
+
+    def reset_slot_for_retry(slot, handle)
       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)
@@ -178,6 +215,15 @@ module Henitai
       progress_reporter&.progress(mutant, scenario_result: result)
     end
 
+    def record_no_coverage(mutant)
+      mutant.status = :no_coverage
+      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
@@ -210,5 +256,17 @@ module Henitai
       @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
+      yield
+    ensure
+      if previous.nil?
+        ENV.delete(WORKER_SLOT_ENV)
+      else
+        ENV[WORKER_SLOT_ENV] = previous
+      end
+    end
   end
 end

data/lib/henitai/static_filter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "coverage_report_reader"
+require_relative "mutation_skip_directives"
 
 module Henitai
   # Applies static, pre-execution filtering to generated mutants.
@@ -8,8 +9,10 @@ module Henitai
     DEFAULT_COVERAGE_REPORT_PATH = CoverageReportReader::DEFAULT_COVERAGE_REPORT_PATH
     DEFAULT_PER_TEST_COVERAGE_REPORT_PATH = CoverageReportReader::DEFAULT_PER_TEST_COVERAGE_REPORT_PATH
 
-    def initialize(coverage_report_reader: CoverageReportReader.new)
+    def initialize(coverage_report_reader: CoverageReportReader.new,
+                   skip_directives: MutationSkipDirectives.new)
       @coverage_report_reader = coverage_report_reader
+      @skip_directives = skip_directives
     end
 
     # This method is the gate-level filter orchestrator.
@@ -18,7 +21,7 @@ module Henitai
       coverage_report_present = coverage_report_present?(config)
 
       Array(mutants).each do |mutant|
-        next if ignored_mutant?(mutant, config)
+        next if ignored_mutant?(mutant, config) || skip_directive_mutant?(mutant)
 
         mark_equivalent_mutant(mutant)
         mark_no_coverage_mutant(
@@ -61,7 +64,7 @@ module Henitai
 
     private
 
-    attr_reader :coverage_report_reader
+    attr_reader :coverage_report_reader, :skip_directives
 
     def ignored?(mutant, config)
       source = source_for(mutant)
@@ -79,6 +82,15 @@ module Henitai
       true
     end
 
+    def skip_directive_mutant?(mutant)
+      directive = skip_directives.directive_for(mutant)
+      return false unless directive
+
+      mutant.status = :ignored
+      mutant.ignore_reason = directive.reason if mutant.respond_to?(:ignore_reason=)
+      true
+    end
+
     def mark_equivalent_mutant(mutant)
       return unless mutant.pending?
 
@@ -96,9 +108,7 @@ module Henitai
     def covered?(mutant, coverage_lines)
       file = normalize_path(mutant.location[:file])
       covered = Array(coverage_lines[file])
-      (mutant.location[:start_line]..mutant.location[:end_line]).any? do |line|
-        covered.include?(line)
-      end
+      covered.any? { |line| (mutant.location[:start_line]..mutant.location[:end_line]).cover?(line) }
     end
 
     def source_for(mutant)

data/lib/henitai/survivor_rerun_strategy.rb

@@ -137,7 +137,7 @@ module Henitai
       split[:stable] + split[:pending]
     end
 
-    def test_filter(loaded, dirty_source_files: false)
+    def test_filter(loaded, dirty_source_files:)
       SurvivorTestFilter.new(
         coverage_map: loaded.coverage_map,
         git_sha: loaded.git_sha,

data/lib/henitai/survivor_test_filter.rb

@@ -57,7 +57,7 @@ module Henitai
       covering = @coverage_map[mutant.stable_id]
       return false if covering.nil? || covering.empty?
 
-      covering.none? { |test_file| changed.include?(test_file) }
+      !changed.intersect?(covering)
     end
 
     # Returns a Set of changed test file paths, or nil on any git error

data/lib/henitai/test_prioritizer.rb

@@ -2,15 +2,41 @@
 
 module Henitai
   # Orders test files so previously effective tests run first.
+  #
+  # Primary key: kill-history count (a test that killed neighbouring mutants
+  # probably kills this one). Tiebreaker: measured per-test-file runtime,
+  # ascending, so the first kill costs as little wall-clock as possible.
+  # Untimed tests sort after timed ones by original inventory order; with no
+  # timing source at all the ordering is exactly the historical behavior.
   class TestPrioritizer
+    # @param timing_source [#call, nil] returns a Hash of test file path to
+    #   wall-clock seconds; resolved lazily on first sort.
+    def initialize(timing_source: nil)
+      @timing_source = timing_source
+    end
+
     def sort(tests, _mutant, history)
       Array(tests).each_with_index.sort_by do |test, index|
-        [-history_count(history, test), index]
+        [-history_count(history, test), runtime(test), index]
       end.map(&:first)
     end
 
     private
 
+    def runtime(test)
+      durations = timing_durations
+      history_key_candidates(test).each do |key|
+        value = durations[key]
+        return value.to_f unless value.nil?
+      end
+
+      Float::INFINITY
+    end
+
+    def timing_durations
+      @timing_durations ||= @timing_source&.call || {}
+    end
+
     def history_count(history, test)
       return 0 unless history.respond_to?(:fetch)
 
@@ -45,7 +71,7 @@ module Henitai
 
     def relative_history_key(path)
       pathname = Pathname.new(path)
-      return unless pathname.absolute?
+      return path unless pathname.absolute?
 
       pathname.relative_path_from(Pathname.pwd).to_s
     rescue StandardError

data/lib/henitai/timeout_calibrator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Derives a per-mutant timeout from measured per-test-file durations.
+  #
+  # The calibrated value is `multiplier × sum(durations of the selected test
+  # files)`, clamped to a floor so a near-instant baseline doesn't flag normal
+  # jitter as a timeout. Returns nil — caller falls back to the static
+  # default — when any selected test lacks timing data, so a partially
+  # measured run is treated as uncalibratable rather than under-estimated.
+  class TimeoutCalibrator
+    FLOOR_SECONDS = 2.0
+
+    # @param timing_source [#call] returns a Hash of test file path to
+    #   wall-clock seconds; resolved lazily on first use.
+    # @param multiplier [Numeric]
+    def initialize(timing_source:, multiplier:)
+      @timing_source = timing_source
+      @multiplier = multiplier
+    end
+
+    # @param test_files [Array<String>]
+    # @return [Float, nil]
+    def timeout_for(test_files)
+      files = Array(test_files)
+      return nil if files.empty? || durations.empty?
+
+      baselines = files.map { |file| durations[normalize(file)] }
+      return nil if baselines.any?(&:nil?)
+
+      [@multiplier * baselines.sum, FLOOR_SECONDS].max
+    end
+
+    private
+
+    def durations
+      @durations ||= (@timing_source.call || {}).transform_keys { |key| normalize(key) }
+    end
+
+    def normalize(path)
+      File.expand_path(path.to_s)
+    end
+  end
+end

data/lib/henitai/verdict_fingerprint.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "digest"
+require "find"
+require "json"
+
+require_relative "generated_artifacts"
+
+module Henitai
+  # Content fingerprints that decide whether a stored verdict is still
+  # trustworthy: the subject's source (method body) and the covering test
+  # files must both be byte-identical to what was recorded. Survived verdicts
+  # additionally record the full-map covering-set membership plus a run-level
+  # dependency fingerprint (ADR-11). Any read failure yields nil / a mismatch
+  # — conservative, never reuse on doubt.
+  module VerdictFingerprint
+    # Files that influence test behavior but never appear in any covering
+    # set: helpers, support code, fixtures/factories, lockfile and tool
+    # config. One combined hash over all of them gates survivor reuse.
+    DEPENDENCY_GLOBS = %w[
+      spec/spec_helper.rb
+      spec/rails_helper.rb
+      spec/support/**/*
+      spec/fixtures/**/*
+      spec/factories/**/*
+      test/test_helper.rb
+      test/support/**/*
+      test/fixtures/**/*
+      test/factories/**/*
+      Gemfile.lock
+      .henitai.yml
+      .rspec
+    ].freeze
+
+    module_function
+
+    # SHA256 of the subject's source lines. nil when the subject has no
+    # source range or the file cannot be read.
+    def subject_source_hash(mutant)
+      subject = mutant.subject
+      return nil unless subject.respond_to?(:source_file) && subject.respond_to?(:source_range)
+
+      range = subject.source_range
+      return nil unless range
+
+      lines = File.readlines(subject.source_file)
+      Digest::SHA256.hexdigest(lines[(range.begin - 1)..(range.end - 1)].to_a.join)
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    # JSON fingerprint of the covering test files: their sorted paths plus a
+    # combined content hash. nil when no tests are known or any is unreadable.
+    def tests_fingerprint(test_files)
+      paths = Array(test_files).map(&:to_s).sort
+      return nil if paths.empty?
+
+      sha = combined_content_sha(paths)
+      return nil unless sha
+
+      JSON.generate("paths" => paths, "sha" => sha)
+    end
+
+    # True when every recorded test file still exists with identical content.
+    def tests_fingerprint_current?(fingerprint_json)
+      return false if fingerprint_json.nil?
+
+      fingerprint = JSON.parse(fingerprint_json)
+      combined_content_sha(fingerprint.fetch("paths")) == fingerprint.fetch("sha")
+    rescue StandardError
+      false
+    end
+
+    # Existing dependency files resolved against +root+, sorted. Shared by
+    # the fingerprint below and by the coverage freshness watch — a stale
+    # per-test map after a dependency edit would let the test selector omit
+    # a newly covering test. Uses Find with pruning instead of Dir.glob so
+    # generated subtrees (thousands of mutation-log files under fixture
+    # projects) are never walked at all.
+    def dependency_files(root = Dir.pwd)
+      files = DEPENDENCY_GLOBS.flat_map do |pattern|
+        base = File.join(root, pattern)
+        pattern.include?("*") ? pruned_tree_files(File.dirname(base.sub("/**/*", "/x"))) : [base]
+      end
+      files.select { |path| File.file?(path) }.uniq.sort
+    end
+
+    def pruned_tree_files(dir)
+      return [] unless File.directory?(dir)
+
+      collected = [] # : Array[String]
+      Find.find(dir) do |path|
+        Find.prune if File.directory?(path) && GeneratedArtifacts.generated_dir?(path)
+        collected << path if File.file?(path)
+      end
+      collected
+    end
+
+    # Run-level combined SHA over the dependency file set. Missing files are
+    # simply excluded (not an error); a read failure yields nil — no reuse.
+    def dependency_fingerprint(root = Dir.pwd) = combined_content_sha(dependency_files(root))
+
+    # Fingerprint recorded for a Survived verdict: the sorted full-map
+    # intersection set (paths + combined content sha) plus the run-level
+    # dependency sha. nil when any input is unavailable — the verdict is
+    # then never reusable.
+    def survivor_tests_fingerprint(test_files, dependency_sha:)
+      return nil if dependency_sha.nil?
+
+      paths = Array(test_files).map(&:to_s).sort
+      return nil if paths.empty?
+
+      sha = combined_content_sha(paths)
+      return nil unless sha
+
+      JSON.generate("paths" => paths, "sha" => sha, "dependencies" => dependency_sha)
+    end
+
+    # True when the recorded covering set still equals the live one in
+    # membership AND content, and the dependency fingerprint is unchanged.
+    # Any parse/read failure or missing field resolves to stale.
+    def survivor_fingerprint_current?(fingerprint_json, live_paths:, dependency_sha:)
+      return false if fingerprint_json.nil? || dependency_sha.nil?
+
+      survivor_fingerprint_matches?(JSON.parse(fingerprint_json), live_paths, dependency_sha)
+    rescue StandardError
+      false
+    end
+
+    def survivor_fingerprint_matches?(fingerprint, live_paths, dependency_sha)
+      recorded_paths = fingerprint.fetch("paths")
+      return false if recorded_paths.empty?
+
+      recorded_paths == Array(live_paths).map(&:to_s).sort &&
+        fingerprint.fetch("dependencies") == dependency_sha &&
+        combined_content_sha(recorded_paths) == fingerprint.fetch("sha")
+    end
+
+    def combined_content_sha(paths)
+      digest = Digest::SHA256.new
+      paths.each do |path|
+        content = File.read(path)
+        digest.update(path.bytesize.to_s)
+        digest.update(":")
+        digest.update(path)
+        digest.update(content.bytesize.to_s)
+        digest.update(":")
+        digest.update(content)
+      end
+      digest.hexdigest
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/henitai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Henitai
-  VERSION = "0.2.1"
+  VERSION = "0.3.1"
 end

data/lib/henitai.rb

@@ -20,9 +20,13 @@ module Henitai
   # Raised when coverage data cannot be bootstrapped or validated.
   class CoverageError < StandardError; end
 
+  # Raised when another process is using the configured reports directory.
+  class ConcurrentRunError < StandardError; end
+
   autoload :Configuration, "henitai/configuration"
   autoload :CoverageBootstrapper, "henitai/coverage_bootstrapper"
   autoload :CoverageReportReader, "henitai/coverage_report_reader"
+  autoload :PerTestCoverage, "henitai/per_test_coverage"
   autoload :PerTestCoverageSelector, "henitai/per_test_coverage_selector"
   autoload :Subject, "henitai/subject"
   autoload :Mutant, "henitai/mutant"
@@ -31,15 +35,24 @@ module Henitai
   autoload :Operators, "henitai/operators"
   autoload :SourceParser, "henitai/source_parser"
   autoload :SubjectResolver, "henitai/subject_resolver"
+  autoload :GeneratedArtifacts, "henitai/generated_artifacts"
   autoload :GitDiffAnalyzer, "henitai/git_diff_analyzer"
   autoload :GitDiffError, "henitai/git_diff_analyzer"
   autoload :MutantGenerator, "henitai/mutant_generator"
   autoload :MutantHistoryStore, "henitai/mutant_history_store"
+  autoload :MutationSkipDirectives, "henitai/mutation_skip_directives"
   autoload :AridNodeFilter, "henitai/arid_node_filter"
   autoload :AvailableCpuCount, "henitai/available_cpu_count"
   autoload :EquivalenceDetector, "henitai/equivalence_detector"
   autoload :StaticFilter, "henitai/static_filter"
+  autoload :IncrementalFilter, "henitai/incremental_filter"
+  autoload :VerdictFingerprint, "henitai/verdict_fingerprint"
   autoload :StillbornFilter, "henitai/stillborn_filter"
+  autoload :CanonicalReportMerger, "henitai/canonical_report_merger"
+  autoload :CanonicalReportWriter, "henitai/canonical_report_writer"
+  autoload :CheckpointReporter, "henitai/checkpoint_reporter"
+  autoload :CompositeProgressReporter, "henitai/composite_progress_reporter"
+  autoload :ReportsDirectoryLock, "henitai/reports_directory_lock"
   autoload :SurvivorLoader,          "henitai/survivor_loader"
   autoload :SurvivorSelector,        "henitai/survivor_selector"
   autoload :SurvivorTestFilter,      "henitai/survivor_test_filter"
@@ -52,8 +65,8 @@ module Henitai
   autoload :SyntaxValidator, "henitai/syntax_validator"
   autoload :SamplingStrategy, "henitai/sampling_strategy"
   autoload :TestPrioritizer, "henitai/test_prioritizer"
+  autoload :TimeoutCalibrator, "henitai/timeout_calibrator"
   autoload :ExecutionEngine, "henitai/execution_engine"
-  autoload :ParallelExecutionRunner, "henitai/parallel_execution_runner"
   autoload :ProcessWorkerRunner, "henitai/process_worker_runner"
   autoload :SlotScheduler, "henitai/slot_scheduler"
   autoload :ProcessWakeup, "henitai/process_wakeup"