henitai 0.1.10 → 0.2.1

data/lib/henitai/slot_scheduler/draining.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Drain/timeout state machine for in-flight slots.
+    #
+    # A slot enters the draining state either when it exceeds its timeout
+    # ({#check_timeouts}) or when a shutdown is requested
+    # ({#interrupt_active_slots}). {#drain_draining_slots} then performs the
+    # two-phase SIGTERM/SIGKILL broadcast and the final blocking reap.
+    #
+    # Mixed into {SlotScheduler}; relies on its slot table, +integration+,
+    # +progress_reporter+, +wakeup+ and the {ProcessControl} primitives.
+    module Draining
+      # Per-slot timeout check. Must be called after reap_all_completed_children
+      # so that naturally-exited processes are already removed from slots.
+      def check_timeouts
+        now = monotonic_time
+        slots.each_value do |slot|
+          next if slot.draining
+          next unless now >= slot.started_at_monotonic + slot.timeout
+
+          # Final targeted reap: if the child already exited, classify it normally.
+          pid, status = wnohang_reap(slot.pid)
+          if pid
+            complete_slot(pid, status)
+          else
+            slot.forced_outcome = :timeout
+            slot.draining = true
+          end
+        end
+      end
+
+      def draining_slots?
+        slots.any? { |_, slot| slot.draining }
+      end
+
+      # Two-phase broadcast cleanup for all slots that are in draining state.
+      #
+      # Precision rule: before signalling, do one final WNOHANG pass to catch
+      # processes that exited naturally in the window between check_timeouts and
+      # now. If SIGTERM gets ESRCH, the process is already gone — we must not
+      # force-label those as :timeout.
+      def drain_draining_slots
+        draining = draining_slots
+        return if draining.empty?
+
+        prune_raced_draining_slots(draining)
+
+        return if draining.empty?
+
+        broadcast_term(draining)
+        wait_for_drain_window
+        signal_draining_slots(draining)
+        reap_and_remove_draining(draining)
+      end
+
+      def interrupt_active_slots
+        slots.each_value do |slot|
+          next if slot.draining
+
+          slot.forced_outcome = :interrupted
+          slot.draining = true
+        end
+      end
+
+      private
+
+      def draining_slots
+        slots.select { |_, slot| slot.draining }
+      end
+
+      def prune_raced_draining_slots(draining)
+        draining.reject! do |_, slot|
+          pid, status = wnohang_reap(slot.pid)
+          next false unless pid
+
+          complete_slot(pid, status)
+          true
+        end
+      end
+
+      def wait_for_drain_window
+        wakeup&.wait(PROCESS_DRAIN_WINDOW)
+        wakeup&.drain
+      end
+
+      def signal_draining_slots(draining)
+        draining.each_value { |slot| signal_process_group(slot.pid, :SIGKILL) }
+      end
+
+      def broadcast_term(draining)
+        now = monotonic_time
+        draining.each_value do |slot|
+          slot.term_sent_at_monotonic = now
+          signal_process_group(slot.pid, :SIGTERM)
+        end
+      end
+
+      # After SIGKILL window: blocking reap each slot, then build its result.
+      #
+      # Interrupted slots are cleaned up but produce no result — the scheduler
+      # is shutting down and does not emit verdicts for in-flight mutants.
+      #
+      # For timeout slots: a real exit status only wins if observed before any
+      # 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
+
+          pid_to_slot.delete(slot.pid)
+          slots.delete(slot.slot_id)
+          Integration::SchedulerDiagnostics.child_ended(slot.pid)
+
+          next if slot.forced_outcome == :interrupted
+
+          result = build_drain_result(slot, final_status)
+          slot.mutant.status = result.status
+          results << result
+          progress_reporter&.progress(slot.mutant, scenario_result: result)
+        end
+      end
+
+      # Choose result: use real exit status only if observed before any parent
+      # signal was sent. After SIGTERM, the forced outcome is authoritative.
+      def build_drain_result(slot, final_status)
+        if final_status&.exited? && slot.term_sent_at_monotonic.nil?
+          integration.build_result(final_status, slot.log_paths)
+        else
+          integration.build_result(slot.forced_outcome || :timeout, slot.log_paths)
+        end
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler/process_control.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Henitai
+  class SlotScheduler
+    # Low-level bridge to the OS process and signal primitives.
+    #
+    # Every Process.wait*/kill call routes through +runtime+ so that the
+    # scheduler remains the single caller of the process table. Mixed into
+    # {SlotScheduler}; relies on its +runtime+ reader.
+    module ProcessControl
+      private
+
+      def monotonic_time
+        runtime.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def wnohang_reap(pid)
+        runtime.wait2(pid, Process::WNOHANG)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+
+      def signal_process_group(pid, signal)
+        runtime.kill(signal, -pid)
+      rescue Errno::ESRCH
+        nil
+      rescue Errno::EPERM
+        # Process group not yet established; fall back to signalling the pid.
+        begin
+          runtime.kill(signal, pid)
+        rescue Errno::ESRCH
+          nil
+        end
+      end
+
+      def reap_pid(pid)
+        runtime.wait(pid)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/henitai/slot_scheduler.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative "slot_scheduler/process_control"
+require_relative "slot_scheduler/draining"
+
+module Henitai
+  # Owns the process-slot table for a single parallel mutation run.
+  #
+  # {ProcessWorkerRunner} drives the event loop and OS signal handling and
+  # delegates every slot operation here: filling idle slots, reaping completed
+  # children, retrying flaky survivors, detecting timeouts and running the
+  # drain/broadcast state machine. Keeping the table behind one collaborator
+  # means Process.wait* has a single caller, so there are no races between
+  # threads reaping the same child.
+  #
+  # The drain/timeout state machine lives in {Draining}; the low-level process
+  # and signal primitives live in {ProcessControl}. +host+ is the owning
+  # {ProcessWorkerRunner}, which supplies +runtime+, +wakeup+, +worker_count+
+  # and the shutdown flag.
+  class SlotScheduler
+    include ProcessControl
+    include Draining
+
+    PROCESS_DRAIN_WINDOW = 0.2
+
+    # 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
+    )
+
+    # @return [Integer] mutants that required at least one retry during the run.
+    # @return [Array<ScenarioExecutionResult>] verdicts accumulated so far.
+    attr_reader :flaky_retry_count, :results
+
+    def initialize(integration:, config:, progress_reporter:, options:, host:)
+      @integration = integration
+      @config = config
+      @progress_reporter = progress_reporter
+      @options = options
+      @host = host
+      @pending = []
+      @slots = {}
+      @pid_to_slot = {}
+      @results = []
+      @flaky_retry_count = 0
+      @next_slot_id = 0
+    end
+
+    # Queues the mutants to be scheduled into worker slots.
+    def enqueue(mutants)
+      @pending = mutants.dup
+    end
+
+    def done?
+      pending.empty? && slots.empty?
+    end
+
+    def fill_idle_slots
+      while slots.size < worker_count && !pending.empty?
+        mutant = pending.shift
+        spawn_into_slot(mutant)
+      end
+    end
+
+    def reap_all_completed_children
+      loop do
+        pid, status = runtime.wait2(-1, Process::WNOHANG)
+        break unless pid
+
+        complete_slot(pid, status)
+      end
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def next_event_timeout
+      now = monotonic_time
+      slot_timeouts = slots.each_value.filter_map do |slot|
+        remaining_slot_timeout(slot, now)
+      end
+
+      slot_timeouts.min
+    end
+
+    private
+
+    attr_reader :pending, :slots, :pid_to_slot, :integration, :config,
+                :progress_reporter, :options, :host
+
+    def worker_count = host.worker_count
+    def runtime = host.runtime
+    def wakeup = host.wakeup
+    def shutdown? = host.shutdown_requested?
+
+    def spawn_into_slot(mutant)
+      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)
+    rescue StandardError => e
+      record_spawn_failure(mutant, e)
+    end
+
+    def register_slot(handle, mutant)
+      slot_id = next_slot_id!
+      slot = build_slot(slot_id, mutant, handle)
+      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)
+      Slot.new(
+        slot_id, mutant, handle.pid,
+        monotonic_time,
+        config.timeout, handle.log_paths, 0, false, nil, nil
+      )
+    end
+
+    def complete_slot(pid, wait_result)
+      slot_id = pid_to_slot.delete(pid)
+      return unless slot_id
+
+      slot = slots[slot_id]
+      return unless slot
+
+      Integration::SchedulerDiagnostics.child_ended(pid)
+      result = integration.build_result(wait_result, slot.log_paths)
+      dispatch_slot_result(slot, result)
+    end
+
+    def dispatch_slot_result(slot, result)
+      if should_retry?(slot, result)
+        retry_slot(slot)
+      else
+        slots.delete(slot.slot_id)
+        slot.mutant.status = result.status
+        results << result
+        progress_reporter&.progress(slot.mutant, scenario_result: result)
+      end
+    end
+
+    def should_retry?(slot, result)
+      !shutdown? && result.survived? && slot.retry_count < config.max_flaky_retries.to_i
+    end
+
+    def retry_slot(slot) # rubocop:disable Metrics/AbcSize
+      @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)
+      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)
+      result = ScenarioExecutionResult.new(
+        status: :compile_error,
+        stdout: "",
+        stderr: "spawn failed: #{error.message}",
+        log_path: "/dev/null",
+        exit_status: nil
+      )
+      mutant.status = result.status
+      results << result
+      progress_reporter&.progress(mutant, scenario_result: result)
+    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
+      # whose SIGTERM has not been sent. Guard term_sent_at_monotonic defensively
+      # against a future ordering change: an unsignalled draining slot is due now.
+      return 0.0 if slot.draining && slot.term_sent_at_monotonic.nil?
+
+      deadline =
+        if slot.draining
+          slot.term_sent_at_monotonic + PROCESS_DRAIN_WINDOW
+        else
+          slot.started_at_monotonic + slot.timeout
+        end
+      remaining = deadline - now
+      remaining.positive? ? remaining : 0.0
+    end
+
+    def resolve_test_files(mutant)
+      if @options.key?(:test_file_resolver)
+        @options[:test_file_resolver].call(mutant)
+      elsif @options.key?(:test_files)
+        @options[:test_files]
+      else
+        integration.select_tests(mutant.subject)
+      end
+    end
+
+    def next_slot_id!
+      id = @next_slot_id
+      @next_slot_id += 1
+      id
+    end
+  end
+end

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