henitai 0.1.8 → 0.2.0

data/lib/henitai/runner.rb

@@ -25,28 +25,39 @@ 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)
-      @config   = config
-      @subjects = subjects
-      @since    = since
+    def initialize(config: Configuration.load, subjects: nil, since: nil, survivors_from: nil)
+      @config         = config
+      @subjects       = subjects
+      @since          = since
+      @survivors_from = survivors_from
     end
 
     # Entry point — runs the full pipeline and returns a Result.
     #
-    # Coverage bootstrap (Gate 0) runs in a background thread so that Gate 1
-    # (subject resolution) and Gate 2 (mutant generation) proceed concurrently.
-    # The thread is joined before Gate 3 (static filtering), which is the first
-    # phase that requires coverage data.
+    # Fast path (recipe rerun): when +--survivors-from+ is given and an
+    # +activation-recipes.json+ file exists beside the report with entries for
+    # all survivor IDs, stub Mutants are built from the recipes and the full
+    # source-parse / mutant-generation pipeline is skipped entirely.
+    #
+    # Normal path: Coverage bootstrap (Gate 0) runs in a background thread so
+    # that Gate 1 (subject resolution) and Gate 2 (mutant generation) proceed
+    # concurrently. The thread is joined before Gate 3 (static filtering).
     #
     # @return [Result]
     def run
       started_at = Time.now
-      source_files = self.source_files
-      subjects = resolve_subjects(source_files)
-      mutants = execute_mutants(mutants_for(subjects, source_files))
+
+      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
 
       build_result(mutants, started_at, Time.now)
     end
@@ -75,8 +86,8 @@ module Henitai
       bootstrap_thread = bootstrap_mutants(source_files)
       mutants = generate_mutants(subjects)
       bootstrap_thread.value
-
-      filter_mutants(mutants)
+      filtered = filter_mutants(mutants)
+      apply_survivor_selection(filtered)
     end
 
     def bootstrap_mutants(source_files)
@@ -109,13 +120,24 @@ module Henitai
         mutants:,
         started_at:,
         finished_at:,
-        thresholds: result_thresholds
+        thresholds: result_thresholds,
+        partial_rerun: survivor_rerun?,
+        survivor_stats: @survivor_stats,
+        git_sha: safe_head_sha
       )
       persist_history(@result, finished_at)
       report(@result)
       @result
     end
 
+    def safe_head_sha
+      git_diff_analyzer.head_sha
+    rescue StandardError
+      # `head_sha` rescues Errno::ENOENT. This extra rescue is defensive for
+      # unexpected Open3/git runtime errors; conservative fallback is `nil`.
+      nil
+    end
+
     def bootstrap_coverage(source_files, test_files = nil)
       coverage_bootstrapper.ensure!(source_files:, config:, integration:, test_files:)
     end
@@ -200,5 +222,172 @@ module Henitai
 
       config.thresholds
     end
+
+    def survivor_rerun?
+      !@survivors_from.nil?
+    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)
+      )
+    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)
+
+      run_from_recipes(loaded, dirty_worktree_files)
+    end
+
+    def load_survivor_report
+      SurvivorLoader.new(@survivors_from, include_paths: Array(config.includes)).load
+    end
+
+    def run_from_recipes(loaded, dirty_worktree_files)
+      recipes = load_activation_recipes(loaded.survivor_ids)
+      return nil if recipes.nil?
+
+      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)
+    end
+
+    def recipe_fast_path_safe?(loaded, dirty_worktree_files)
+      !dirty_source_files?(dirty_worktree_files, git_sha: loaded.git_sha)
+    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]
+    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
+    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 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 }
+      )
+    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
+    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]
+    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
+      )
+    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

@@ -7,7 +7,7 @@ module Henitai
 
     def self.build(wait_result:, stdout:, stderr:, log_path:)
       new(
-        status: status_for(wait_result),
+        status: status_for(wait_result, stdout:, stderr:),
         stdout: stdout,
         stderr: stderr,
         log_path: log_path,
@@ -62,7 +62,7 @@ module Henitai
     end
 
     def should_show_logs?(all_logs: nil)
-      all_logs || timeout?
+      all_logs || timeout? || status == :compile_error
     end
 
     def failure_tail(all_logs: nil, lines: 12)
@@ -77,8 +77,10 @@ module Henitai
     class << self
       private
 
-      def status_for(wait_result)
+      def status_for(wait_result, stdout:, stderr:)
         return :timeout if wait_result == :timeout
+        return :compile_error if no_examples_found?(stdout, stderr)
+        return :compile_error if zero_examples_failure?(wait_result, stdout, stderr)
         return :compile_error if exit_status_for(wait_result) == 2
         return :survived if wait_result.respond_to?(:success?) && wait_result.success?
 
@@ -91,6 +93,17 @@ module Henitai
 
         wait_result.exitstatus
       end
+
+      def no_examples_found?(stdout, stderr)
+        stdout.to_s.include?("No examples found.") || stderr.to_s.include?("No examples found.")
+      end
+
+      def zero_examples_failure?(wait_result, stdout, stderr)
+        return false unless exit_status_for(wait_result) == 1
+
+        output = [stdout.to_s, stderr.to_s].join("\n")
+        output.include?("0 examples, 0 failures")
+      end
     end
 
     def stream_section(name, content)

data/lib/henitai/static_filter.rb

@@ -37,11 +37,18 @@ module Henitai
 
       coverage_lines = coverage_lines_by_file(coverage_report_path)
       coverage_lines = merge_method_coverage(coverage_lines, coverage_report_path)
-      return coverage_lines unless coverage_lines.empty?
-
-      coverage_lines_from_test_lines(
+      per_test_lines = coverage_lines_from_test_lines(
         test_lines_by_file(per_test_coverage_report_path)
       )
+
+      return per_test_lines if coverage_lines.empty?
+
+      # Merge per-test coverage into the standard coverage map.
+      # Standard coverage may be incomplete when child processes fork before
+      # all files are loaded; per-test coverage widens the result set.
+      per_test_lines.each_with_object(coverage_lines) do |(file, lines), merged|
+        merged[file] = ((merged[file] || []) + lines).uniq.sort
+      end
     end
 
     def coverage_lines_by_file(path = DEFAULT_COVERAGE_REPORT_PATH)

data/lib/henitai/survivor_activation_cache.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Henitai
+  # Stores and retrieves pre-computed +define_method+ activation sources for
+  # survived mutants, enabling survivor reruns to skip the full mutant-generation
+  # pipeline.
+  #
+  # The cache artifact (+activation-recipes.json+) is written alongside the
+  # session snapshot in +reports/sessions/<session_id>/+. When a survivor rerun
+  # finds this file next to the report it was given, it can build stub Mutant
+  # objects directly and execute them without re-parsing source files.
+  #
+  # A recipe entry encodes everything needed to activate and re-report a mutant:
+  # the +define_method+ source, subject coordinates, operator, description,
+  # location, and the coveredBy test list.
+  class SurvivorActivationCache
+    FILENAME = "activation-recipes.json"
+
+    # Build a recipe hash for each survived mutant that has a computable
+    # activation source.
+    #
+    # @param survived_mutants [Array<Mutant>]
+    # @return [Hash<String, Hash>] stableId → recipe
+    def self.compute(survived_mutants)
+      survived_mutants.each_with_object({}) do |mutant, cache|
+        source = Mutant::Activator.activation_source_for(mutant)
+        next unless source
+
+        cache[mutant.stable_id] = build_recipe(mutant, source)
+      end
+    end
+
+    # @param path [String] path to +activation-recipes.json+
+    # @return [Hash, nil] nil when the file is absent or unparseable
+    def self.load(path)
+      return nil unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      nil
+    end
+
+    # @param path    [String]
+    # @param recipes [Hash<String, Hash>]
+    def self.write(path, recipes)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(recipes))
+    end
+
+    class << self
+      private
+
+      def build_recipe(mutant, activation_source)
+        {
+          "activationSource" => activation_source,
+          "namespace" => mutant.subject.namespace,
+          "methodName" => mutant.subject.method_name,
+          "methodType" => mutant.subject.method_type.to_s,
+          "sourceFile" => mutant.subject.source_file,
+          "operator" => mutant.operator,
+          "description" => mutant.description,
+          "location" => serialize_location(mutant.location),
+          "coveredBy" => Array(mutant.covered_by).compact
+        }
+      end
+
+      def serialize_location(location)
+        {
+          "file" => location[:file],
+          "startLine" => location[:start_line],
+          "endLine" => location[:end_line],
+          "startCol" => location[:start_col],
+          "endCol" => location[:end_col]
+        }.compact
+      end
+    end
+  end
+end

data/lib/henitai/survivor_loader.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Henitai
+  # Reads a Stryker-compatible mutation report and extracts survivor data.
+  #
+  # Returns a +Report+ value object carrying:
+  #   - +survivor_ids+  — stable IDs of survived mutants
+  #   - +coverage_map+  — stableId → [test_files] from prior coveredBy data
+  #   - +git_sha+       — git HEAD at the time the report was written (may be nil)
+  #
+  # Scope validation is intentionally shallow: checks schemaVersion presence
+  # and at least one file path overlap with config.includes.
+  class SurvivorLoader
+    # Value object returned by #load.
+    Report = Struct.new(:survivor_ids, :coverage_map, :git_sha)
+
+    class FileNotFoundError < StandardError; end
+    class InvalidReportError < StandardError; end
+    class ScopeMismatchError < StandardError; end
+
+    # @param path          [String]        path to a Stryker-compatible JSON report
+    # @param include_paths [Array<String>] from config.includes; used for scope validation
+    def initialize(path, include_paths: [])
+      @path          = path
+      @include_paths = include_paths
+    end
+
+    # @return [Report]
+    def load
+      raw    = read_file
+      report = parse_json(raw)
+      validate_scope(report)
+      build_report(report)
+    end
+
+    private
+
+    def build_report(report)
+      entries = known_entries(report)
+      Report.new(
+        survivor_ids: extract_survivor_ids(entries),
+        coverage_map: extract_coverage_map(entries),
+        git_sha: report["gitSha"]
+      )
+    end
+
+    # Returns mutant entries that have a stableId, warning about those that don't.
+    def known_entries(report)
+      all_mutants(report).select do |entry|
+        if entry["stableId"]
+          true
+        else
+          warn "henitai: survivor report entry missing stableId — skipping"
+          false
+        end
+      end
+    end
+
+    def extract_survivor_ids(entries)
+      entries.filter_map { |e| e["stableId"] if e["status"] == "Survived" }
+    end
+
+    def extract_coverage_map(entries)
+      entries.each_with_object({}) do |entry, map|
+        covered = Array(entry["coveredBy"]).compact
+        map[entry["stableId"]] = covered unless covered.empty?
+      end
+    end
+
+    def read_file
+      File.read(@path)
+    rescue Errno::ENOENT
+      raise FileNotFoundError, "Survivor report not found: #{@path}"
+    end
+
+    def parse_json(raw)
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise InvalidReportError, "Invalid JSON in survivor report #{@path}: #{e.message}"
+    end
+
+    def validate_scope(report)
+      validate_schema_version!(report)
+      return if @include_paths.empty?
+
+      report_files = normalized_report_files(report)
+      include_dirs_raw = normalized_include_dirs_raw
+      include_dirs_abs = normalized_include_dirs_abs(include_dirs_raw)
+
+      return if any_report_file_overlaps?(report_files, include_dirs_raw, include_dirs_abs)
+
+      raise ScopeMismatchError,
+            "Survivor report #{@path} has no file overlap with configured includes — " \
+            "did you pass a report from a different project?"
+    end
+
+    def validate_schema_version!(report)
+      return if report.key?("schemaVersion")
+
+      raise InvalidReportError,
+            "Survivor report #{@path} is missing schemaVersion — is this a Henitai report?"
+    end
+
+    def normalized_report_files(report)
+      (report.fetch("files", {}) || {}).keys.map { |p| strip_trailing_slash(p.to_s) }
+    end
+
+    def normalized_include_dirs_raw
+      @include_paths.map { |p| strip_trailing_slash(p.to_s) }.uniq
+    end
+
+    def normalized_include_dirs_abs(dirs_raw)
+      dirs_raw.map { |p| File.expand_path(p) }.uniq
+    end
+
+    def strip_trailing_slash(path)
+      path.sub(%r{/\z}, "")
+    end
+
+    def any_report_file_overlaps?(report_files, include_dirs_raw, include_dirs_abs)
+      report_files.any? do |file|
+        include_dirs_raw.any? { |inc| path_prefix_match?(file, inc) } ||
+          include_dirs_abs.any? { |inc_abs| path_prefix_match?(File.expand_path(file), inc_abs) }
+      end
+    end
+
+    def path_prefix_match?(path, dir)
+      return false if path.empty? || dir.empty?
+
+      path == dir || path.start_with?(dir + File::SEPARATOR)
+    end
+
+    def all_mutants(report)
+      files = report.fetch("files", {}) || {}
+      files.values.compact.flat_map { |file_data| file_data.fetch("mutants", []) }
+    end
+  end
+end

data/lib/henitai/survivor_selector.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Filters a mutant list to those that match a set of prior survivor stable IDs.
+  #
+  # After calling #select, #unmatched_ids reports which survivor IDs had no
+  # corresponding mutant in the current generation. A high unmatched ratio
+  # indicates that the source has drifted and a full run is recommended.
+  class SurvivorSelector
+    DRIFT_THRESHOLD = 0.5
+    class SelectionError < StandardError; end
+
+    def initialize(survivor_ids:)
+      @survivor_ids  = survivor_ids.to_set
+      @unmatched_ids = nil
+    end
+
+    def select(mutants)
+      current_index = mutants.to_h { |m| [m.stable_id, m] }
+      matched_ids, @unmatched_ids = @survivor_ids.partition { |id| current_index.key?(id) }
+      matched_ids.filter_map { |id| current_index[id] }
+    end
+
+    def unmatched_ids
+      raise SelectionError, "Call #select before accessing #unmatched_ids" if @unmatched_ids.nil?
+
+      @unmatched_ids
+    end
+
+    def drift_warning?
+      return false if @survivor_ids.empty?
+
+      unmatched_ids.size.to_f / @survivor_ids.size > DRIFT_THRESHOLD
+    end
+  end
+end

data/lib/henitai/survivor_test_filter.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Splits a matched survivor set into stable and pending subsets by consulting
+  # a git diff against the covering tests from the prior report.
+  #
+  # A survivor is **stable** (can skip re-execution) when:
+  #   - it has covering test data in the prior report, AND
+  #   - none of those test files appear in the diff between the prior run's
+  #     git_sha and the current HEAD.
+  #
+  # A survivor is **pending** (must execute) when:
+  #   - git_sha is nil (no anchor → conservative), OR
+  #   - its coveredBy data is absent or empty, OR
+  #   - at least one covering test file changed.
+  #
+  # On any git error the filter conservatively treats all survivors as pending.
+  class SurvivorTestFilter
+    # @param coverage_map  [Hash<String, Array<String>>] stableId → [test_files]
+    # @param git_sha       [String, nil] git SHA from the prior report
+    # @param dirty_source_files [Boolean] true when the current worktree has
+    #   dirty source files and the survivor shortcut must be disabled
+    # @param worktree_changed_files [Array<String>] dirty tracked/untracked files
+    # @param diff_analyzer [GitDiffAnalyzer]
+    def initialize(
+      coverage_map:,
+      git_sha:,
+      dirty_source_files: false,
+      worktree_changed_files: [],
+      diff_analyzer: GitDiffAnalyzer.new
+    )
+      @coverage_map  = coverage_map
+      @git_sha       = git_sha
+      @dirty_source_files = dirty_source_files
+      @worktree_changed_files = Array(worktree_changed_files)
+      @diff_analyzer = diff_analyzer
+    end
+
+    # @param mutants [Array<Mutant>]
+    # @return [Hash<Symbol, Array<Mutant>>] { stable: [...], pending: [...] }
+    def apply(mutants)
+      return { stable: [], pending: mutants } if @dirty_source_files
+      return { stable: [], pending: mutants } if @git_sha.nil?
+
+      changed = changed_test_files
+      return { stable: [], pending: mutants } if changed.nil?
+
+      mutants.each_with_object({ stable: [], pending: [] }) do |mutant, result|
+        bucket = stable_survivor?(mutant, changed) ? :stable : :pending
+        result[bucket] << mutant
+      end
+    end
+
+    private
+
+    def stable_survivor?(mutant, changed)
+      covering = @coverage_map[mutant.stable_id]
+      return false if covering.nil? || covering.empty?
+
+      covering.none? { |test_file| changed.include?(test_file) }
+    end
+
+    # Returns a Set of changed test file paths, or nil on any git error
+    # (nil triggers conservative fallback in #apply — all survivors pending).
+    def changed_test_files
+      committed = @diff_analyzer.changed_files(from: @git_sha, to: "HEAD")
+      (committed + @worktree_changed_files).to_set
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/henitai/version.rb

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