henitai 0.2.1 → 0.3.0

data/lib/henitai/reports_directory_lock.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+
+module Henitai
+  # Coordinates exclusive access to a reports directory across processes.
+  class ReportsDirectoryLock
+    LOCK_FILENAME = ".henitai-run.lock"
+
+    def initialize(reports_dir:)
+      @reports_dir = File.expand_path(reports_dir)
+    end
+
+    def synchronize
+      FileUtils.mkdir_p(@reports_dir)
+      File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |file|
+        acquire(file)
+        write_owner(file)
+        yield
+      end
+    end
+
+    private
+
+    def lock_path
+      File.join(@reports_dir, LOCK_FILENAME)
+    end
+
+    def acquire(file)
+      return if file.flock(File::LOCK_EX | File::LOCK_NB)
+
+      raise ConcurrentRunError, contention_message(owner_pid(file))
+    end
+
+    def owner_pid(file)
+      file.rewind
+      metadata = JSON.parse(file.read)
+      pid = metadata["pid"] if metadata.is_a?(Hash)
+      pid.is_a?(Integer) ? pid : "unknown"
+    rescue JSON::ParserError, IOError, SystemCallError
+      "unknown"
+    end
+
+    def contention_message(pid)
+      message = "another henitai run is active in #{@reports_dir} " \
+                "(pid #{pid}); use a separate reports_dir or wait"
+      return message unless dead_owner?(pid)
+
+      "#{message}. The recorded owner pid #{pid} is not running — an " \
+        "orphaned child may still hold the lock " \
+        "(check: lsof #{lock_path})"
+    end
+
+    # 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 write_owner(file)
+      file.rewind
+      file.truncate(0)
+      file.write(JSON.generate(pid: Process.pid, started_at: Time.now.iso8601))
+      file.flush
+    end
+  end
+end

data/lib/henitai/result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require_relative "mutant_identity"
 require_relative "unparse_helper"
 
 module Henitai
@@ -22,11 +23,16 @@ module Henitai
     #   already knows the file paths) supplies the contents. The default
     #   provider returns "" for every file — callers that need real source in
     #   the schema (e.g. the runner) inject a provider primed with file content.
+    # @param authoritative [Boolean] whether this run covers the full
+    #   configured mutation scope. Authoritative runs fully replace the
+    #   canonical report; non-authoritative (subject-scoped, --since,
+    #   --survivors-from) runs are merged into it instead — see
+    #   CanonicalReportMerger.
     # rubocop:disable Metrics/ParameterLists
     def initialize(mutants:, started_at:, finished_at:, thresholds: nil,
                    partial_rerun: false, survivor_stats: nil,
                    session_id: SecureRandom.uuid, git_sha: nil,
-                   source_provider: ->(_file) { "" })
+                   source_provider: ->(_file) { "" }, authoritative: true)
       @mutants         = mutants
       @started_at      = started_at
       @finished_at     = finished_at
@@ -36,10 +42,12 @@ module Henitai
       @session_id      = session_id
       @git_sha         = git_sha
       @source_provider = source_provider
+      @authoritative   = authoritative
     end
     # rubocop:enable Metrics/ParameterLists
 
     def partial_rerun? = @partial_rerun
+    def authoritative? = @authoritative
 
     # @return [Integer] number of killed mutants
     def killed   = mutants.count(&:killed?)
@@ -53,7 +61,7 @@ module Henitai
     # Detected = killed + timeout + runtime_error (alle Zustände die einen Fehler beweisen)
     # @return [Integer]
     def detected
-      mutants.count { |m| %i[killed timeout runtime_error].include?(m.status) }
+      detected_in(mutants)
     end
 
     # Mutation Score (MS) — Architektur-Formel aus Abschnitt 6.1:
@@ -66,11 +74,7 @@ module Henitai
     #
     # @return [Float, nil] 0.0–100.0, nil wenn kein valider Mutant vorhanden
     def mutation_score
-      excluded = %i[ignored no_coverage compile_error equivalent]
-      valid = mutants.reject { |m| excluded.include?(m.status) }
-      return nil if valid.empty?
-
-      ((detected.to_f / valid.count) * 100.0).round(2).to_f
+      mutation_score_for(mutants)
     end
 
     # Mutation Score Indicator (MSI) — naive Berechnung ohne Äquivalenz-Bereinigung:
@@ -82,9 +86,23 @@ module Henitai
     #
     # @return [Float, nil]
     def mutation_score_indicator
-      return nil if mutants.empty?
+      mutation_score_indicator_for(mutants)
+    end
 
-      ((killed.to_f / mutants.count) * 100.0).round(2).to_f
+    # Scores over only the mutants actually executed this run — verdicts
+    # reused from the history store (`--incremental`) excluded. nil when
+    # nothing was reused: the combined scores already tell the whole story,
+    # and reporters use nil to suppress the extra line.
+    #
+    # @return [Hash, nil] { mutation_score:, mutation_score_indicator: }
+    def executed_scoring_summary
+      executed = mutants.reject { |m| m.respond_to?(:from_cache?) && m.from_cache? }
+      return nil if executed.size == mutants.size
+
+      {
+        mutation_score: mutation_score_for(executed),
+        mutation_score_indicator: mutation_score_indicator_for(executed)
+      }
     end
 
     # Compact public summary for reporters.
@@ -119,6 +137,24 @@ module Henitai
 
     private
 
+    def detected_in(list)
+      list.count { |m| %i[killed timeout runtime_error].include?(m.status) }
+    end
+
+    def mutation_score_for(list)
+      excluded = %i[ignored no_coverage compile_error equivalent]
+      valid = list.reject { |m| excluded.include?(m.status) }
+      return nil if valid.empty?
+
+      ((detected_in(list).to_f / valid.count) * 100.0).round(2).to_f
+    end
+
+    def mutation_score_indicator_for(list)
+      return nil if list.empty?
+
+      ((list.count(&:killed?).to_f / list.count) * 100.0).round(2).to_f
+    end
+
     def base_schema
       { # : Hash[Symbol, untyped]
         schemaVersion: SCHEMA_VERSION,
@@ -148,10 +184,13 @@ module Henitai
       {
         id: mutant.id,
         stableId: mutant.stable_id,
+        legacyStableId: legacy_stable_id_for(mutant),
         mutatorName: mutant.operator,
         replacement: replacement_for(mutant),
         location: location_for(mutant),
         status: stryker_status(mutant.status),
+        statusReason: status_reason_for(mutant),
+        fromCache: from_cache_for(mutant),
         description: mutant.description,
         duration: duration_for(mutant)
       }.compact.merge(coverage_schema(mutant))
@@ -168,6 +207,8 @@ module Henitai
     end
 
     def replacement_for(mutant)
+      return mutant.mutated_source if mutant.respond_to?(:mutated_source)
+
       safe_unparse(mutant.mutated_node)
     end
 
@@ -190,6 +231,28 @@ module Henitai
       mutant.duration&.then { |d| (d * 1000).round }
     end
 
+    # Serialized as the schema's statusReason so directive reasons show up
+    # next to the Ignored status in the HTML report.
+    def status_reason_for(mutant)
+      return nil unless mutant.respond_to?(:ignore_reason)
+
+      mutant.ignore_reason
+    end
+
+    # Vendored extension field (like stableId): marks verdicts reused from
+    # the history store so reports stay honest about what actually executed.
+    def from_cache_for(mutant)
+      return nil unless mutant.respond_to?(:from_cache?)
+
+      mutant.from_cache? || nil
+    end
+
+    def legacy_stable_id_for(mutant)
+      return if mutant.respond_to?(:precomputed_stable_id) && mutant.precomputed_stable_id
+
+      MutantIdentity.legacy_stable_id(mutant)
+    end
+
     def equivalence_uncertainty
       return nil if mutation_score.nil?
 

data/lib/henitai/runner.rb

@@ -28,11 +28,16 @@ module Henitai
   class Runner
     attr_reader :config, :result
 
-    def initialize(config: Configuration.load, subjects: nil, since: nil, survivors_from: nil)
+    # @param mode [Hash] execution-mode flags: +dry_run:+ stops before Gate 4,
+    #   +incremental:+ reuses still-valid Killed verdicts from history.
+    def initialize(config: Configuration.load, subjects: nil, since: nil, survivors_from: nil,
+                   mode: {})
       @config         = config
       @subjects       = subjects
       @since          = since
       @survivors_from = survivors_from
+      @dry_run        = mode.fetch(:dry_run, false)
+      @incremental    = mode.fetch(:incremental, false)
     end
 
     # Entry point — runs the full pipeline and returns a Result.
@@ -48,21 +53,40 @@ module Henitai
     #
     # @return [Result]
     def run
-      started_at = Time.now
+      ReportsDirectoryLock.new(reports_dir: config.reports_dir).synchronize do
+        started_at = Time.now
 
-      mutants = if survivor_rerun? && (fast_mutants = survivor_strategy.try_recipe_run)
-                  execute_mutants(fast_mutants)
-                else
-                  source_files = self.source_files
-                  subjects = resolve_subjects(source_files)
-                  execute_mutants(mutants_for(subjects, source_files))
-                end
+        mutants = pipeline_mutants
+        return dry_run_result(mutants, started_at, Time.now) if @dry_run
 
-      build_result(mutants, started_at, Time.now)
+        build_result(execute_mutants(mutants), started_at, Time.now)
+      end
     end
 
     private
 
+    # Gates 0–3 only: coverage bootstrap, subject resolution, generation and
+    # static/skip/arid/stillborn filtering — everything short of execution.
+    def pipeline_mutants
+      if survivor_rerun? && (fast_mutants = survivor_strategy.try_recipe_run)
+        return fast_mutants
+      end
+
+      source_files = self.source_files
+      subjects = resolve_subjects(source_files)
+      mutants_for(subjects, source_files)
+    end
+
+    # Dry run stops before Gate 4: prints the post-filter listing and returns
+    # a Result without executing mutants, persisting history or running the
+    # configured reporters. Gate 0 and lock coordination may still write under
+    # reports_dir.
+    def dry_run_result(mutants, started_at, finished_at)
+      @result = build_result_object(mutants, started_at, finished_at)
+      Reporter::DryRun.new(config:).report(@result)
+      @result
+    end
+
     def resolve_subjects(source_files = self.source_files)
       subjects = subject_resolver.resolve_from_files(source_files)
       return subjects if pattern_subjects.empty?
@@ -85,16 +109,27 @@ module Henitai
       bootstrap_thread = bootstrap_mutants(source_files)
       mutants = generate_mutants(subjects)
       bootstrap_thread.value
-      filtered = filter_mutants(mutants)
+      filtered = apply_incremental_filter(filter_mutants(mutants))
       return filtered unless survivor_rerun?
 
       survivor_strategy.apply_selection(filtered)
     end
 
-    def bootstrap_mutants(source_files)
-      Thread.new { bootstrap_coverage(source_files) }
+    # Opt-in verdict reuse (`--incremental`): still-valid Killed and Survived
+    # verdicts from the history store are marked with their stored status +
+    # from_cache before execution. The filter is only ever constructed when
+    # the flag is set; it runs after the coverage bootstrap join in
+    # mutants_for, so the live per-test map it reads is never mid-write.
+    def apply_incremental_filter(mutants)
+      return mutants unless @incremental
+
+      IncrementalFilter.new(history_store:, per_test_coverage:,
+                            dependency_fingerprint: VerdictFingerprint.dependency_fingerprint)
+                       .apply(mutants)
     end
 
+    def bootstrap_mutants(source_files) = Thread.new { bootstrap_coverage(source_files) }
+
     def execute_mutants(mutants)
       execution_engine.run(
         mutants,
@@ -117,7 +152,14 @@ module Henitai
     end
 
     def build_result(mutants, started_at, finished_at)
-      @result = Result.new(
+      @result = build_result_object(mutants, started_at, finished_at)
+      persist_history(@result, finished_at)
+      report(@result)
+      @result
+    end
+
+    def build_result_object(mutants, started_at, finished_at)
+      Result.new(
         mutants:,
         started_at:,
         finished_at:,
@@ -125,11 +167,9 @@ module Henitai
         partial_rerun: survivor_rerun?,
         survivor_stats: survivor_strategy.survivor_stats,
         git_sha: safe_head_sha,
-        source_provider: source_provider
+        source_provider: source_provider,
+        authoritative: full_run?
       )
-      persist_history(@result, finished_at)
-      report(@result)
-      @result
     end
 
     # Reads each source file once and caches it, so Result consumes source
@@ -158,29 +198,17 @@ module Henitai
       coverage_bootstrapper.ensure!(source_files:, config:, integration:, test_files:)
     end
 
-    def subject_resolver
-      @subject_resolver ||= SubjectResolver.new
-    end
+    def subject_resolver = @subject_resolver ||= SubjectResolver.new
 
-    def git_diff_analyzer
-      @git_diff_analyzer ||= GitDiffAnalyzer.new
-    end
+    def git_diff_analyzer = @git_diff_analyzer ||= GitDiffAnalyzer.new
 
-    def mutant_generator
-      @mutant_generator ||= MutantGenerator.new
-    end
+    def mutant_generator = @mutant_generator ||= MutantGenerator.new
 
-    def static_filter
-      @static_filter ||= StaticFilter.new
-    end
+    def static_filter = @static_filter ||= StaticFilter.new
 
-    def execution_engine
-      @execution_engine ||= ExecutionEngine.new
-    end
+    def execution_engine = @execution_engine ||= ExecutionEngine.new
 
-    def coverage_bootstrapper
-      @coverage_bootstrapper ||= CoverageBootstrapper.new
-    end
+    def coverage_bootstrapper = @coverage_bootstrapper ||= CoverageBootstrapper.new
 
     def integration
       @integration ||= Integration.for(config.integration).new
@@ -190,18 +218,26 @@ module Henitai
       @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
-      return nil unless Array(config.reporters).map(&:to_s).include?("terminal")
-
-      Reporter::Terminal.new(config:)
+      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)
+        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 source_files
       @source_files ||= filter_changed(reject_excluded(included_source_files))
     end
@@ -259,6 +295,12 @@ module Henitai
       !@survivors_from.nil?
     end
 
+    # 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?
+    end
+
     def survivor_strategy
       @survivor_strategy ||= SurvivorRerunStrategy.new(
         survivors_from: @survivors_from,

data/lib/henitai/scenario_execution_result.rb

@@ -23,6 +23,18 @@ module Henitai
       @exit_status = exit_status
     end
 
+    # Frees the captured child output once it has been consumed (e.g. by the
+    # progress reporter). The scheduler retains one result per mutant for the
+    # whole run; without this a runaway mutant's multi-hundred-MB output would
+    # stay resident until the run ends. Status/log_path/exit_status are kept so
+    # the result stays usable for scoring and log lookups.
+    def release_output!
+      @stdout = ""
+      @stderr = ""
+      @log_text = nil
+      self
+    end
+
     def survived?
       status == :survived
     end

data/lib/henitai/slot_scheduler/draining.rb

@@ -106,24 +106,30 @@ module Henitai
       # 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
+      def reap_and_remove_draining(draining)
+        draining.each_value { |slot| reap_and_finalize_slot(slot) }
+      end
 
-          pid_to_slot.delete(slot.pid)
-          slots.delete(slot.slot_id)
-          Integration::SchedulerDiagnostics.child_ended(slot.pid)
+      # One last WNOHANG before blocking: catches processes that exited
+      # between SIGKILL and here.
+      def reap_and_finalize_slot(slot)
+        _, final_status = wnohang_reap(slot.pid)
+        reap_pid(slot.pid) unless final_status
 
-          next if slot.forced_outcome == :interrupted
+        pid_to_slot.delete(slot.pid)
+        slots.delete(slot.slot_id)
+        Integration::SchedulerDiagnostics.child_ended(slot.pid)
 
-          result = build_drain_result(slot, final_status)
-          slot.mutant.status = result.status
-          results << result
-          progress_reporter&.progress(slot.mutant, scenario_result: result)
-        end
+        return if slot.forced_outcome == :interrupted
+
+        record_drain_result(slot, final_status)
+      end
+
+      def record_drain_result(slot, final_status)
+        result = build_drain_result(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

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