henitai 0.1.10 → 0.2.1

data/lib/henitai/process_wakeup.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Wakeup pipe used to interrupt child-process wait loops when CHLD arrives.
+  class ProcessWakeup
+    def initialize(signal_name: "CHLD")
+      @signal_name = signal_name
+      @reader, @writer = IO.pipe
+    end
+
+    def install
+      @previous_handler = Signal.trap(signal_name) { signal }
+      self
+    end
+
+    def wait(timeout)
+      # rubocop:disable Lint/IncompatibleIoSelectWithFiberScheduler
+      IO.select([reader], nil, nil, timeout)
+      # rubocop:enable Lint/IncompatibleIoSelectWithFiberScheduler
+    rescue Errno::EINTR
+      nil
+    end
+
+    def drain
+      loop do
+        reader.read_nonblock(4096)
+      end
+    rescue IO::WaitReadable, EOFError
+      nil
+    end
+
+    def signal
+      writer.write_nonblock(".")
+    rescue IO::WaitWritable, IOError, Errno::EPIPE
+      nil
+    end
+
+    def close
+      Signal.trap(signal_name, previous_handler) if previous_handler
+    ensure
+      reader.close unless reader.closed?
+      writer.close unless writer.closed?
+    end
+
+    private
+
+    attr_reader :previous_handler, :reader, :signal_name, :writer
+  end
+end

data/lib/henitai/process_worker_runner.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Flat, single-threaded driver for parallel mutation runs.
+  #
+  # Owns the event loop and OS signal handling, and delegates the slot
+  # lifecycle (spawning, reaping, timeout detection and the drain/broadcast
+  # state machine) to a {SlotScheduler}. Because the scheduler is the sole
+  # caller of Process.wait*, there are no races between threads reaping the
+  # same child.
+  class ProcessWorkerRunner
+    # Default bridge to process and signal primitives used by the scheduler.
+    class Runtime
+      def clock_gettime(clock_id)
+        Process.clock_gettime(clock_id)
+      end
+
+      def wait2(pid, flags = nil)
+        Process.wait2(pid, flags)
+      end
+
+      def kill(signal, pid)
+        Process.kill(signal, pid)
+      end
+
+      def wait(pid)
+        Process.wait(pid)
+      end
+
+      def trap(signal, handler = nil, &block)
+        Kernel.trap(signal, handler || block)
+      end
+    end
+
+    # Loop primitives the {SlotScheduler} reads back from its host.
+    attr_reader :worker_count, :runtime, :wakeup
+
+    def initialize(worker_count:, runtime: Runtime.new, wakeup: nil)
+      @worker_count = worker_count
+      @runtime = runtime
+      @wakeup = wakeup
+      @shutdown_requested = false
+    end
+
+    # Number of mutants that required at least one retry during the run.
+    # Mirrors the linear path's per-mutant flaky semantics so the engine can
+    # report a single, mode-agnostic flaky statistic.
+    def flaky_retry_count
+      @scheduler ? @scheduler.flaky_retry_count : 0
+    end
+
+    # True once a graceful shutdown has been requested; read by the scheduler.
+    def shutdown_requested?
+      @shutdown_requested
+    end
+
+    # Trigger a graceful shutdown from outside the event loop.
+    # Safe to call from any thread. The loop observes the flag on its next tick.
+    def request_shutdown
+      @shutdown_requested = true
+      @wakeup&.signal
+    end
+
+    # Runs all mutants and returns an array of ScenarioExecutionResult.
+    #
+    # @param mutants [Array<Mutant>]
+    # @param integration [Integration::Base]
+    # @param config [Configuration]
+    # @param progress_reporter [#progress, nil]
+    # @param options [Hash]
+    # @return [Array<ScenarioExecutionResult>]
+    def run(mutants, integration, config, progress_reporter, options = {})
+      Integration::SchedulerDiagnostics.reset! if Integration::SchedulerDiagnostics.enabled?
+      prepare_run(mutants, integration, config, progress_reporter, options)
+
+      event_loop
+      @scheduler.results
+    ensure
+      @wakeup&.close
+      @wakeup = nil
+    end
+
+    private
+
+    def prepare_run(mutants, integration, config, progress_reporter, options)
+      @shutdown_requested = false
+      @wakeup = Henitai::ProcessWakeup.new.install if @wakeup.nil?
+      @scheduler = SlotScheduler.new(
+        integration: integration,
+        config: config,
+        progress_reporter: progress_reporter,
+        options: options,
+        host: self
+      )
+      @scheduler.enqueue(mutants)
+    end
+
+    def event_loop
+      saved_traps = install_signal_traps
+      loop do
+        break if @scheduler.done?
+
+        break if process_cycle == :shutdown
+      end
+    ensure
+      restore_signal_traps(saved_traps)
+      raise Interrupt if @shutdown_requested
+    end
+
+    def process_cycle
+      @scheduler.fill_idle_slots unless @shutdown_requested
+      @scheduler.reap_all_completed_children
+      @scheduler.check_timeouts
+      @scheduler.fill_idle_slots unless @shutdown_requested
+      return handle_shutdown if @shutdown_requested
+
+      @scheduler.drain_draining_slots if @scheduler.draining_slots?
+      @scheduler.fill_idle_slots unless @shutdown_requested
+      return :done if @scheduler.done?
+
+      wait_for_next_event
+      nil
+    end
+
+    def handle_shutdown
+      @scheduler.interrupt_active_slots
+      @scheduler.drain_draining_slots
+      :shutdown
+    end
+
+    def wait_for_next_event
+      @wakeup&.wait(@scheduler.next_event_timeout)
+      @wakeup&.drain
+    end
+
+    def install_signal_traps
+      saved = {}
+      %w[INT TERM HUP].each do |sig|
+        saved[sig] = @runtime.trap(sig) { @shutdown_requested = true }
+      end
+      saved
+    end
+
+    def restore_signal_traps(saved)
+      saved&.each { |sig, handler| @runtime.trap(sig, handler) }
+    end
+  end
+end

data/lib/henitai/reporter.rb

@@ -22,9 +22,12 @@ module Henitai
     # @param names  [Array<String>] reporter names from configuration
     # @param result [Result]
     # @param config [Configuration]
-    def self.run_all(names:, result:, config:)
+    # @param history_store [MutantHistoryStore, nil] persistence store the JSON
+    #   reporter reads trend data from; supplied by the composition root so the
+    #   reporter does not build infrastructure itself.
+    def self.run_all(names:, result:, config:, history_store: nil)
       names.each do |name|
-        reporter_class(name).new(config:).report(result)
+        reporter_class(name).new(config:, history_store:).report(result)
       end
     end
 
@@ -36,8 +39,12 @@ module Henitai
 
     # Base class for all reporters.
     class Base
-      def initialize(config:)
+      # @param history_store [MutantHistoryStore, nil] accepted by every
+      #   reporter for a uniform factory signature; only the JSON reporter uses
+      #   it. Ignored elsewhere.
+      def initialize(config:, history_store: nil)
         @config = config
+        @history_store = history_store
       end
 
       # @param result [Result]
@@ -47,7 +54,7 @@ module Henitai
 
       private
 
-      attr_reader :config
+      attr_reader :config, :history_store
     end
 
     # Terminal reporter.
@@ -90,6 +97,14 @@ module Henitai
       end
 
       def summary_lines(result)
+        if result.respond_to?(:partial_rerun?) && result.partial_rerun?
+          partial_summary_lines(result)
+        else
+          full_summary_lines(result)
+        end
+      end
+
+      def full_summary_lines(result)
         [
           "Mutation testing summary",
           score_line(result),
@@ -101,6 +116,28 @@ module Henitai
         ]
       end
 
+      def partial_summary_lines(result)
+        lines = [
+          "Partial survivor rerun",
+          format_row("Survived", count_status(result, :survived)),
+          format_row("Duration", format_duration(result.duration))
+        ]
+        append_survivor_stats(lines, result)
+        lines
+      end
+
+      def append_survivor_stats(lines, result)
+        return unless result.respond_to?(:survivor_stats)
+
+        stats = result.survivor_stats # : Hash[Symbol, untyped]?
+        return unless stats
+
+        lines << format_row("Matched", stats.fetch(:matched))
+        lines << format_row("Skipped", stats.fetch(:skipped_count, 0))
+        lines << format_row("Unmatched", stats.fetch(:unmatched_count))
+        lines << format_row("Drift warning", stats.fetch(:drift_warning) ? "yes" : "no")
+      end
+
       def survived_detail_lines(result)
         survivors = result.mutants.select(&:survived?)
         return [] if survivors.empty?
@@ -212,24 +249,72 @@ module Henitai
     # JSON reporter.
     class Json < Base
       def report(result)
-        FileUtils.mkdir_p(File.dirname(report_path))
-        File.write(report_path, JSON.pretty_generate(result.to_stryker_schema))
+        schema = result.to_stryker_schema
+        write_canonical(schema)
+        write_session_snapshot(schema)
+        write_activation_recipes(result)
         write_history_report
       end
 
       private
 
-      def report_path
+      def write_canonical(schema)
+        FileUtils.mkdir_p(File.dirname(canonical_path))
+        File.write(canonical_path, JSON.pretty_generate(schema))
+      end
+
+      def write_session_snapshot(schema)
+        session_id = schema[:sessionId]
+        return unless session_id
+
+        path = session_snapshot_path(session_id)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(schema))
+      end
+
+      def write_activation_recipes(result)
+        session_id = result.session_id if result.respond_to?(:session_id)
+        return unless session_id
+
+        survived = survived_mutants_for(result)
+        return if survived.empty?
+
+        recipes = SurvivorActivationCache.compute(survived)
+        return if recipes.empty?
+
+        SurvivorActivationCache.write(session_recipe_path(session_id), recipes)
+      end
+
+      def survived_mutants_for(result)
+        return [] unless result.respond_to?(:mutants)
+
+        result.mutants.select(&:survived?)
+      end
+
+      def session_snapshot_path(session_id)
+        File.join(config.reports_dir, "sessions", session_id, "mutation-report.json")
+      end
+
+      def session_recipe_path(session_id)
+        File.join(config.reports_dir, "sessions", session_id, SurvivorActivationCache::FILENAME)
+      end
+
+      def canonical_path
         File.join(config.reports_dir, "mutation-report.json")
       end
 
       def write_history_report
-        path = File.join(config.reports_dir, Henitai::HISTORY_STORE_FILENAME)
-        history_store = MutantHistoryStore.new(path:)
-        return unless File.exist?(path)
+        store = history_store || default_history_store
+        return unless File.exist?(store.path)
 
         FileUtils.mkdir_p(File.dirname(history_report_path))
-        File.write(history_report_path, JSON.pretty_generate(history_store.trend_report))
+        File.write(history_report_path, JSON.pretty_generate(store.trend_report))
+      end
+
+      def default_history_store
+        MutantHistoryStore.new(
+          path: File.join(config.reports_dir, Henitai::HISTORY_STORE_FILENAME)
+        )
       end
 
       def history_report_path

data/lib/henitai/result.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "securerandom"
 require_relative "unparse_helper"
 
 module Henitai
@@ -13,14 +14,32 @@ module Henitai
     SCHEMA_VERSION = "1.0"
     DEFAULT_THRESHOLDS = { high: 80, low: 60 }.freeze
 
-    attr_reader :mutants, :started_at, :finished_at, :thresholds
-
-    def initialize(mutants:, started_at:, finished_at:, thresholds: nil)
-      @mutants     = mutants
-      @started_at  = started_at
-      @finished_at = finished_at
-      @thresholds  = DEFAULT_THRESHOLDS.merge(thresholds || {})
-    end
+    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.
+    # 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) { "" })
+      @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
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def partial_rerun? = @partial_rerun
 
     # @return [Integer] number of killed mutants
     def killed   = mutants.count(&:killed?)
@@ -88,25 +107,38 @@ module Henitai
     # Serialise to Stryker mutation-testing-report-schema JSON (schema 1.0).
     # @return [Hash]
     def to_stryker_schema
-      {
+      schema = base_schema
+      sha = @git_sha
+      schema[:gitSha] = sha if sha
+      return schema unless partial_rerun?
+
+      schema[:partialRerun] = true
+      schema[:unmatchedSurvivorIds] = unmatched_survivor_ids
+      schema
+    end
+
+    private
+
+    def base_schema
+      { # : Hash[Symbol, untyped]
         schemaVersion: SCHEMA_VERSION,
+        sessionId: @session_id,
         thresholds: thresholds,
         files: build_files_section
       }
     end
 
-    private
+    def unmatched_survivor_ids
+      return survivor_stats.fetch(:unmatched_ids) if survivor_stats
+
+      [] # : Array[String]
+    end
 
     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
@@ -115,6 +147,7 @@ module Henitai
     def mutant_to_schema(mutant)
       {
         id: mutant.id,
+        stableId: mutant.stable_id,
         mutatorName: mutant.operator,
         replacement: replacement_for(mutant),
         location: location_for(mutant),

data/lib/henitai/runner.rb

@@ -28,25 +28,35 @@ module Henitai
   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 = 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
 
       build_result(mutants, started_at, Time.now)
     end
@@ -75,8 +85,10 @@ module Henitai
       bootstrap_thread = bootstrap_mutants(source_files)
       mutants = generate_mutants(subjects)
       bootstrap_thread.value
+      filtered = filter_mutants(mutants)
+      return filtered unless survivor_rerun?
 
-      filter_mutants(mutants)
+      survivor_strategy.apply_selection(filtered)
     end
 
     def bootstrap_mutants(source_files)
@@ -93,7 +105,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)
@@ -109,13 +121,39 @@ module Henitai
         mutants:,
         started_at:,
         finished_at:,
-        thresholds: result_thresholds
+        thresholds: result_thresholds,
+        partial_rerun: survivor_rerun?,
+        survivor_stats: survivor_strategy.survivor_stats,
+        git_sha: safe_head_sha,
+        source_provider: source_provider
       )
       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
+      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
@@ -165,22 +203,38 @@ module Henitai
     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
+      @source_files ||= filter_changed(reject_excluded(included_source_files))
+    end
+
+    def included_source_files
+      Array(config.includes).flat_map do |include_path|
+        Dir.glob(File.join(include_path, "**", "*.rb"))
+      end.uniq
+    end
+
+    # 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?
+
+      files.reject { |path| excluded.include?(normalize_path(path)) }
+    end
+
+    def excluded_source_files
+      Array(config.excludes)
+        .flat_map { |pattern| Dir.glob(pattern) }
+        .map { |path| normalize_path(path) }
+    end
+
+    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) }
+      files.select { |path| changed_file_set.include?(normalize_path(path)) }
     end
 
     def pattern_subjects
@@ -200,5 +254,17 @@ module Henitai
 
       config.thresholds
     end
+
+    def survivor_rerun?
+      !@survivors_from.nil?
+    end
+
+    def survivor_strategy
+      @survivor_strategy ||= SurvivorRerunStrategy.new(
+        survivors_from: @survivors_from,
+        config:,
+        git_diff_analyzer:
+      )
+    end
   end
 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)