henitai 0.2.0 → 0.3.0

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
@@ -17,22 +18,36 @@ module Henitai
     attr_reader :mutants, :started_at, :finished_at, :thresholds, :survivor_stats,
                 :session_id, :git_sha
 
+    # @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)
-      @mutants        = mutants
-      @started_at     = started_at
-      @finished_at    = finished_at
-      @thresholds     = DEFAULT_THRESHOLDS.merge(thresholds || {})
-      @partial_rerun  = partial_rerun
-      @survivor_stats = survivor_stats
-      @session_id     = session_id
-      @git_sha        = git_sha
+                   session_id: SecureRandom.uuid, git_sha: nil,
+                   source_provider: ->(_file) { "" }, authoritative: true)
+      @mutants         = mutants
+      @started_at      = started_at
+      @finished_at     = finished_at
+      @thresholds      = DEFAULT_THRESHOLDS.merge(thresholds || {})
+      @partial_rerun   = partial_rerun
+      @survivor_stats  = survivor_stats
+      @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?)
@@ -46,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:
@@ -59,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:
@@ -75,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.
@@ -112,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,
@@ -129,14 +172,9 @@ module Henitai
 
     def build_files_section
       mutants.group_by { |m| m.location[:file] }.transform_values do |file_mutants|
-        source = begin
-          File.read(file_mutants.first.location[:file])
-        rescue StandardError
-          ""
-        end
         {
           language: "ruby",
-          source:,
+          source: @source_provider.call(file_mutants.first.location[:file]),
           mutants: file_mutants.map { |m| mutant_to_schema(m) }
         }
       end
@@ -146,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))
@@ -166,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
 
@@ -188,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

@@ -25,15 +25,19 @@ module Henitai
   #   Gate 5 — Reporting
   #     Write results to configured reporters (terminal, html, json, dashboard).
   #
-  # rubocop:disable Metrics/ClassLength
   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.
@@ -49,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 = 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?
@@ -86,14 +109,27 @@ module Henitai
       bootstrap_thread = bootstrap_mutants(source_files)
       mutants = generate_mutants(subjects)
       bootstrap_thread.value
-      filtered = filter_mutants(mutants)
-      apply_survivor_selection(filtered)
+      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,
@@ -104,7 +140,7 @@ module Henitai
     end
 
     def report(result)
-      Reporter.run_all(names: config.reporters, result:, config:)
+      Reporter.run_all(names: config.reporters, result:, config:, history_store:)
     end
 
     def persist_history(result, recorded_at)
@@ -116,18 +152,38 @@ 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:,
         thresholds: result_thresholds,
         partial_rerun: survivor_rerun?,
-        survivor_stats: @survivor_stats,
-        git_sha: safe_head_sha
+        survivor_stats: survivor_strategy.survivor_stats,
+        git_sha: safe_head_sha,
+        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
+    # 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
@@ -142,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
@@ -174,220 +218,95 @@ 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
 
-    def source_files
-      @source_files ||= begin
-        included_files = Array(config.includes).flat_map do |include_path|
-          Dir.glob(File.join(include_path, "**", "*.rb"))
-        end.uniq
-
-        if @since
-          changed_files = git_diff_analyzer.changed_files(from: @since, to: "HEAD")
-          changed_file_set = changed_files.map { |path| normalize_path(path) }
-
-          included_files.select do |path|
-            changed_file_set.include?(normalize_path(path))
-          end
-        else
-          included_files
-        end
-      end
-    end
-
-    def pattern_subjects
-      Array(@subjects)
-    end
-
-    def unique_subjects(subjects)
-      subjects.uniq { |subject| [subject.expression, subject.source_file] }
-    end
-
-    def normalize_path(path)
-      File.expand_path(path)
-    end
-
-    def result_thresholds
-      return nil unless config.respond_to?(:thresholds)
-
-      config.thresholds
+    # 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 survivor_rerun?
-      !@survivors_from.nil?
+    def source_files
+      @source_files ||= filter_changed(reject_excluded(included_source_files))
     end
 
-    def apply_survivor_selection(mutants)
-      return mutants unless survivor_rerun?
-
-      dirty_worktree_files = dirty_worktree_changed_files
-      loaded   = SurvivorLoader.new(@survivors_from, include_paths: Array(config.includes)).load
-      selector = SurvivorSelector.new(survivor_ids: loaded.survivor_ids)
-      selected = selector.select(mutants)
-      finalize_survivor_split(
-        selector,
-        selected,
-        test_filter(
-          loaded,
-          dirty_source_files: dirty_source_files?(dirty_worktree_files, git_sha: loaded.git_sha)
-        ).apply(selected)
-      )
+    def included_source_files
+      Array(config.includes).flat_map do |include_path|
+        Dir.glob(File.join(include_path, "**", "*.rb"))
+      end.uniq
     end
 
-    # Attempts to run survivors directly from pre-computed activation recipes,
-    # bypassing source parsing and mutant generation entirely.
-    # Returns the mutant array on success, or nil if recipes are unavailable.
-    def try_recipe_run
-      dirty_worktree_files = dirty_worktree_changed_files
-      loaded = load_survivor_report
-      return nil unless recipe_fast_path_safe?(loaded, dirty_worktree_files)
+    # 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?
 
-      run_from_recipes(loaded, dirty_worktree_files)
+      files.reject { |path| excluded.include?(normalize_path(path)) }
     end
 
-    def load_survivor_report
-      SurvivorLoader.new(@survivors_from, include_paths: Array(config.includes)).load
+    def excluded_source_files
+      Array(config.excludes)
+        .flat_map { |pattern| Dir.glob(pattern) }
+        .map { |path| normalize_path(path) }
     end
 
-    def run_from_recipes(loaded, dirty_worktree_files)
-      recipes = load_activation_recipes(loaded.survivor_ids)
-      return nil if recipes.nil?
+    def filter_changed(files)
+      return files unless @since
 
-      selector, stubs = recipe_selector_and_stubs(loaded.survivor_ids, recipes)
-      split = test_filter(
-        loaded,
-        dirty_source_files: dirty_source_files?(dirty_worktree_files, git_sha: loaded.git_sha)
-      ).apply(stubs)
-      finalize_survivor_split(selector, stubs, split)
+      changed_file_set = git_diff_analyzer
+                         .changed_files(from: @since, to: "HEAD")
+                         .map { |path| normalize_path(path) }
+      files.select { |path| changed_file_set.include?(normalize_path(path)) }
     end
 
-    def recipe_fast_path_safe?(loaded, dirty_worktree_files)
-      !dirty_source_files?(dirty_worktree_files, git_sha: loaded.git_sha)
+    def pattern_subjects
+      Array(@subjects)
     end
 
-    # Builds stub Mutants from recipes and a SurvivorSelector primed with the
-    # survivor ID set. The selector is given a synthetic #select call so that
-    # #drift_warning? / #unmatched_ids are available (all IDs will be matched).
-    def recipe_selector_and_stubs(survivor_ids, recipes)
-      stubs    = survivor_ids.map { |id| build_stub_mutant(id, recipes[id]) }
-      selector = SurvivorSelector.new(survivor_ids:)
-      selector.select(stubs)
-      [selector, stubs]
+    def unique_subjects(subjects)
+      subjects.uniq { |subject| [subject.expression, subject.source_file] }
     end
 
-    # Returns the recipe hash if the file exists and covers every survivor ID;
-    # otherwise returns nil to trigger the normal generation path.
-    def load_activation_recipes(survivor_ids)
-      path    = File.join(File.dirname(@survivors_from), SurvivorActivationCache::FILENAME)
-      recipes = SurvivorActivationCache.load(path)
-      return nil if recipes.nil?
-      return nil unless survivor_ids.all? { |id| recipes.key?(id) }
-
-      recipes
+    def normalize_path(path)
+      File.expand_path(path)
     end
 
-    def build_stub_mutant(stable_id, recipe)
-      mutant = Mutant.new(
-        subject: stub_subject_from_recipe(recipe),
-        operator: recipe.fetch("operator"),
-        nodes: { original: nil, mutated: nil },
-        description: recipe.fetch("description"),
-        location: recipe_location(recipe["location"]),
-        precomputed_stable_id: stable_id,
-        precomputed_activation_source: recipe.fetch("activationSource")
-      )
-      mutant.covered_by = recipe["coveredBy"]
-      mutant
-    end
+    def result_thresholds
+      return nil unless config.respond_to?(:thresholds)
 
-    def stub_subject_from_recipe(recipe)
-      Subject.new(
-        namespace: recipe["namespace"],
-        method_name: recipe["methodName"],
-        method_type: (recipe["methodType"] || "instance").to_sym,
-        source_location: { file: recipe["sourceFile"], range: nil }
-      )
+      config.thresholds
     end
 
-    def recipe_location(loc)
-      return {} unless loc.is_a?(Hash)
-
-      {
-        file: loc["file"],
-        start_line: loc["startLine"],
-        end_line: loc["endLine"],
-        start_col: loc["startCol"],
-        end_col: loc["endCol"]
-      }.compact
+    def survivor_rerun?
+      !@survivors_from.nil?
     end
 
-    def finalize_survivor_split(selector, selected, split)
-      split[:stable].each { |m| m.status = :survived }
-      warn_survivor_drift(selector) if selector.drift_warning?
-      @survivor_stats = build_survivor_stats(selector, selected, split)
-      split[:stable] + split[:pending]
+    # 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 test_filter(loaded, dirty_source_files: false)
-      SurvivorTestFilter.new(
-        coverage_map: loaded.coverage_map,
-        git_sha: loaded.git_sha,
-        dirty_source_files:,
-        worktree_changed_files: Array(dirty_worktree_changed_files),
-        diff_analyzer: git_diff_analyzer
+    def survivor_strategy
+      @survivor_strategy ||= SurvivorRerunStrategy.new(
+        survivors_from: @survivors_from,
+        config:,
+        git_diff_analyzer:
       )
     end
-
-    def dirty_worktree_changed_files
-      @dirty_worktree_changed_files ||= git_diff_analyzer.working_tree_changed_files
-    rescue StandardError
-      nil
-    end
-
-    def dirty_source_files?(dirty_worktree_files, git_sha: nil)
-      return true if dirty_worktree_files.nil?
-
-      all_changed = dirty_worktree_files + committed_changed_files(git_sha)
-      include_roots = Array(config.includes).map { |path| normalize_path(path) }
-      all_changed.any? { |path| in_include_root?(normalize_path(path), include_roots) }
-    rescue StandardError
-      true
-    end
-
-    def committed_changed_files(git_sha)
-      return [] unless git_sha
-
-      git_diff_analyzer.changed_files(from: git_sha, to: "HEAD")
-    end
-
-    def in_include_root?(path, include_roots)
-      include_roots.any? { |root| path == root || path.start_with?("#{root}/") }
-    end
-
-    def warn_survivor_drift(selector)
-      warn "henitai: WARNING: #{selector.unmatched_ids.size} prior survivors " \
-           "could not be matched; the source may have drifted - consider a full run"
-    end
-
-    def build_survivor_stats(selector, selected, split)
-      {
-        matched: selected.size,
-        unmatched_count: selector.unmatched_ids.size,
-        unmatched_ids: selector.unmatched_ids,
-        skipped_count: split[:stable].size,
-        drift_warning: selector.drift_warning?
-      }
-    end
   end
-  # rubocop:enable Metrics/ClassLength
 end

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