henitai 0.2.1 → 0.3.1

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
@@ -15,18 +16,24 @@ module Henitai
     DEFAULT_THRESHOLDS = { high: 80, low: 60 }.freeze
 
     attr_reader :mutants, :started_at, :finished_at, :thresholds, :survivor_stats,
-                :session_id, :git_sha
+                :session_id, :git_sha, :since
 
     # @param source_provider [#call] maps a file path to its source string.
     #   Injected so the domain object performs no disk IO; the caller (which
     #   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,
+                   since: nil)
       @mutants         = mutants
       @started_at      = started_at
       @finished_at     = finished_at
@@ -36,10 +43,13 @@ module Henitai
       @session_id      = session_id
       @git_sha         = git_sha
       @source_provider = source_provider
+      @authoritative   = authoritative
+      @since           = since
     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 +63,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 +76,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 +88,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 +139,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 +186,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 +209,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 +233,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,10 @@ 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?,
+        since: @since
       )
-      persist_history(@result, finished_at)
-      report(@result)
-      @result
     end
 
     # Reads each source file once and caches it, so Result consumes source
@@ -158,29 +199,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 +219,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
@@ -231,12 +268,28 @@ module Henitai
     def filter_changed(files)
       return files unless @since
 
-      changed_file_set = git_diff_analyzer
-                         .changed_files(from: @since, to: "HEAD")
-                         .map { |path| normalize_path(path) }
+      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
@@ -259,6 +312,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