henitai 0.2.0 → 0.2.1

data/lib/henitai/configuration_validator/scalars.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Henitai
+  module ConfigurationValidator
+    # Leaf validators for individual configuration values.
+    #
+    # Each method returns silently for an acceptable value or raises
+    # +Henitai::ConfigurationError+ via {Rules.configuration_error}.
+    module Scalars
+      module_function
+
+      def validate_operator(value)
+        return if value.nil?
+
+        operator = value.respond_to?(:to_sym) ? value.to_sym : nil
+        return if VALID_OPERATORS.include?(operator)
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.operators: expected one of " \
+          "#{VALID_OPERATORS.join(', ')}, got #{value.inspect}"
+        )
+      end
+
+      def validate_timeout(value)
+        return if value.nil?
+        return if value.is_a?(Numeric)
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.timeout: expected Numeric, got #{value.class}"
+        )
+      end
+
+      def validate_threshold(value, path)
+        return if value.is_a?(Integer) && value.between?(0, 100)
+
+        Rules.configuration_error(
+          "Invalid configuration value for #{path}: expected Integer between 0 and 100, " \
+          "got #{value.inspect}"
+        )
+      end
+
+      def validate_boolean(value, path)
+        return if [true, false].include?(value)
+
+        Rules.configuration_error(
+          "Invalid configuration value for #{path}: expected true or false, got #{value.inspect}"
+        )
+      end
+
+      def validate_optional_string(value, path)
+        return if value.nil?
+        return if value.is_a?(String)
+
+        Rules.configuration_error("Invalid configuration value for #{path}: expected String, got #{value.class}")
+      end
+
+      def validate_string_array(value, path)
+        return if value.nil?
+        return if value.is_a?(Array) && value.all?(String)
+
+        Rules.configuration_error(
+          "Invalid configuration value for #{path}: expected Array<String>, got #{describe_array_type(value)}"
+        )
+      end
+
+      def validate_ignore_patterns(value)
+        Array(value).each do |pattern|
+          Regexp.new(pattern)
+        rescue RegexpError => e
+          Rules.configuration_error(
+            "Invalid configuration value for mutation.ignore_patterns: " \
+            "invalid regular expression #{pattern.inspect}: #{e.message}"
+          )
+        end
+      end
+
+      def validate_max_flaky_retries(value)
+        return if value.nil?
+        return if value.is_a?(Integer) && value >= 0
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.max_flaky_retries: expected Integer >= 0, got #{value.inspect}"
+        )
+      end
+
+      def validate_sampling_ratio(value)
+        return if value.nil?
+        return if value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.sampling.ratio: " \
+          "expected Numeric between 0 and 1, got #{value.inspect}"
+        )
+      end
+
+      def validate_sampling_strategy(value)
+        return if value.nil?
+
+        strategy = value.respond_to?(:to_sym) ? value.to_sym : nil
+        return if strategy == :stratified
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.sampling.strategy: expected stratified, got #{value.inspect}"
+        )
+      end
+
+      def validate_sampling_completeness(value)
+        return if value.key?(:ratio) && value.key?(:strategy)
+
+        Rules.configuration_error(
+          "Invalid configuration value for mutation.sampling: expected both ratio and strategy"
+        )
+      end
+
+      def describe_array_type(value)
+        return value.class.name unless value.is_a?(Array)
+
+        element_types = value.map { |item| item.class.name }.uniq.join(", ")
+        "Array<#{element_types}>"
+      end
+    end
+  end
+end

data/lib/henitai/configuration_validator.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
+require_relative "configuration_validator/rules"
+
 module Henitai
-  # rubocop:disable Metrics/ModuleLength
   # Internal validator for configuration data loaded from YAML and CLI overrides.
+  #
+  # The public entry point is {.validate!}; the individual rules live in
+  # {Rules}. Unknown-key warnings are emitted via {.warn} so that callers (and
+  # specs) can observe them on this module.
   module ConfigurationValidator
     VALID_TOP_LEVEL_KEYS = %i[
       integration
       includes
+      excludes
       mutation
       coverage_criteria
       thresholds
@@ -27,6 +33,7 @@ module Henitai
       validate_top_level_keys
       validate_integration
       validate_includes
+      validate_excludes
       validate_jobs
       validate_reporters
       validate_reports_dir
@@ -38,246 +45,12 @@ module Henitai
     ].freeze
 
     def self.validate!(raw)
-      ensure_hash!(raw, "configuration")
-      VALIDATION_STEPS.each { |step| send(step, raw) }
+      Rules.ensure_hash!(raw, "configuration")
+      VALIDATION_STEPS.each { |step| Rules.public_send(step, raw) }
     end
 
-    class << self
-      private
-
-      def validate_top_level_keys(raw)
-        warn_unknown_keys(raw, VALID_TOP_LEVEL_KEYS)
-      end
-
-      def validate_integration(raw)
-        value = raw[:integration]
-        return if value.nil?
-        return if value.is_a?(String)
-
-        ensure_hash!(value, "integration")
-        warn_unknown_keys(value, VALID_INTEGRATION_KEYS, "integration")
-        validate_optional_string(value[:name], "integration.name")
-      end
-
-      def validate_includes(raw)
-        validate_string_array(raw[:includes], "includes")
-      end
-
-      def validate_jobs(raw)
-        value = raw[:jobs]
-        return if value.nil?
-        return if value.is_a?(Integer)
-
-        configuration_error("Invalid configuration value for jobs: expected Integer, got #{value.class}")
-      end
-
-      def validate_reporters(raw)
-        validate_string_array(raw[:reporters], "reporters")
-      end
-
-      def validate_reports_dir(raw)
-        validate_optional_string(raw[:reports_dir], "reports_dir")
-      end
-
-      def validate_all_logs(raw)
-        value = raw[:all_logs]
-        return if value.nil?
-
-        validate_boolean(value, "all_logs")
-      end
-
-      def validate_dashboard(raw)
-        value = raw[:dashboard]
-        return if value.nil?
-
-        ensure_hash!(value, "dashboard")
-        warn_unknown_keys(value, VALID_DASHBOARD_KEYS, "dashboard")
-        validate_optional_string(value[:project], "dashboard.project")
-        validate_optional_string(value[:base_url], "dashboard.base_url")
-      end
-
-      def validate_mutation(raw)
-        value = raw[:mutation]
-        return if value.nil?
-
-        ensure_hash!(value, "mutation")
-        warn_unknown_keys(value, VALID_MUTATION_KEYS, "mutation")
-        validate_operator(value[:operators])
-        validate_mutation_limits(value)
-        validate_mutation_filters(value)
-        validate_sampling(value[:sampling])
-      end
-
-      def validate_mutation_limits(value)
-        validate_timeout(value[:timeout])
-        validate_max_flaky_retries(value[:max_flaky_retries])
-      end
-
-      def validate_mutation_filters(value)
-        validate_string_array(value[:ignore_patterns], "mutation.ignore_patterns")
-        validate_ignore_patterns(value[:ignore_patterns])
-      end
-
-      def validate_coverage_criteria(raw)
-        value = raw[:coverage_criteria]
-        return if value.nil?
-
-        ensure_hash!(value, "coverage_criteria")
-        warn_unknown_keys(value, VALID_COVERAGE_CRITERIA_KEYS, "coverage_criteria")
-        value.each do |key, flag|
-          validate_boolean(flag, "coverage_criteria.#{key}")
-        end
-      end
-
-      def validate_thresholds(raw)
-        value = raw[:thresholds]
-        return if value.nil?
-
-        ensure_hash!(value, "thresholds")
-        warn_unknown_keys(value, VALID_THRESHOLDS_KEYS, "thresholds")
-        value.each do |key, threshold|
-          validate_threshold(threshold, "thresholds.#{key}")
-        end
-      end
-
-      def validate_operator(value)
-        return if value.nil?
-
-        operator = value.respond_to?(:to_sym) ? value.to_sym : nil
-        return if VALID_OPERATORS.include?(operator)
-
-        configuration_error(
-          "Invalid configuration value for mutation.operators: expected one of " \
-          "#{VALID_OPERATORS.join(', ')}, got #{value.inspect}"
-        )
-      end
-
-      def validate_timeout(value)
-        return if value.nil?
-        return if value.is_a?(Numeric)
-
-        configuration_error("Invalid configuration value for mutation.timeout: expected Numeric, got #{value.class}")
-      end
-
-      def validate_threshold(value, path)
-        return if value.is_a?(Integer) && value.between?(0, 100)
-
-        configuration_error(
-          "Invalid configuration value for #{path}: expected Integer between 0 and 100, " \
-          "got #{value.inspect}"
-        )
-      end
-
-      def validate_boolean(value, path)
-        return if [true, false].include?(value)
-
-        configuration_error("Invalid configuration value for #{path}: expected true or false, got #{value.inspect}")
-      end
-
-      def validate_optional_string(value, path)
-        return if value.nil?
-        return if value.is_a?(String)
-
-        configuration_error("Invalid configuration value for #{path}: expected String, got #{value.class}")
-      end
-
-      def validate_string_array(value, path)
-        return if value.nil?
-        return if value.is_a?(Array) && value.all?(String)
-
-        configuration_error(
-          "Invalid configuration value for #{path}: expected Array<String>, got #{describe_array_type(value)}"
-        )
-      end
-
-      def validate_ignore_patterns(value)
-        Array(value).each do |pattern|
-          Regexp.new(pattern)
-        rescue RegexpError => e
-          configuration_error(
-            "Invalid configuration value for mutation.ignore_patterns: " \
-            "invalid regular expression #{pattern.inspect}: #{e.message}"
-          )
-        end
-      end
-
-      def validate_max_flaky_retries(value)
-        return if value.nil?
-        return if value.is_a?(Integer) && value >= 0
-
-        configuration_error(
-          "Invalid configuration value for mutation.max_flaky_retries: expected Integer >= 0, got #{value.inspect}"
-        )
-      end
-
-      def validate_sampling(value)
-        return if value.nil?
-
-        ensure_hash!(value, "mutation.sampling")
-        warn_unknown_keys(value, VALID_SAMPLING_KEYS, "mutation.sampling")
-        validate_sampling_completeness(value)
-        validate_sampling_ratio(value[:ratio])
-        validate_sampling_strategy(value[:strategy])
-      end
-
-      def validate_sampling_ratio(value)
-        return if value.nil?
-        return if value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
-
-        configuration_error(
-          "Invalid configuration value for mutation.sampling.ratio: " \
-          "expected Numeric between 0 and 1, got #{value.inspect}"
-        )
-      end
-
-      def validate_sampling_strategy(value)
-        return if value.nil?
-
-        strategy = value.respond_to?(:to_sym) ? value.to_sym : nil
-        return if strategy == :stratified
-
-        configuration_error(
-          "Invalid configuration value for mutation.sampling.strategy: expected stratified, got #{value.inspect}"
-        )
-      end
-
-      def validate_sampling_completeness(value)
-        return if value.key?(:ratio) && value.key?(:strategy)
-
-        configuration_error(
-          "Invalid configuration value for mutation.sampling: expected both ratio and strategy"
-        )
-      end
-
-      def warn_unknown_keys(raw, allowed_keys, path = nil)
-        raw.each_key do |key|
-          next if allowed_keys.include?(key)
-
-          warn "Unknown configuration key: #{key_path(path, key)}"
-        end
-      end
-
-      def key_path(path, key)
-        path ? "#{path}.#{key}" : key.to_s
-      end
-
-      def ensure_hash!(value, path)
-        return if value.is_a?(Hash)
-
-        configuration_error("Invalid configuration value for #{path}: expected Hash, got #{value.class}")
-      end
-
-      def describe_array_type(value)
-        return value.class.name unless value.is_a?(Array)
-
-        element_types = value.map { |item| item.class.name }.uniq.join(", ")
-        "Array<#{element_types}>"
-      end
-
-      def configuration_error(message)
-        raise Henitai::ConfigurationError, message
-      end
+    def self.warn(message)
+      Kernel.warn(message)
     end
   end
-  # rubocop:enable Metrics/ModuleLength
 end

data/lib/henitai/eager_load.rb

@@ -2,10 +2,41 @@
 
 require "henitai"
 
-# Force all autoloaded constants to load so mutation testing tools
-# (e.g. mutant) can discover subjects via ObjectSpace.
-SIDE_EFFECT_FILES = %w[minitest_simplecov.rb minitest_coverage_hook.rb rspec_coverage_formatter.rb].freeze
+# Standalone entry point that forces every Henitai constant to load so external
+# mutation tooling (e.g. mutant) can discover subjects via ObjectSpace.
+#
+# Usage:
+#   ruby -r henitai/eager_load -e ""
+#
+# A bare `Dir[].each { require }` glob loads files in filesystem order, which
+# does not respect dependency order: a child file that reopens an autoloaded
+# constant (e.g. `class CLI` or `class Rspec < Base`) triggers the parent
+# autoload before the child's own constants exist, raising NameError. To avoid
+# that, first touch every constant in the autoload table so each entry-point
+# file loads with its `require_relative` children in the correct order; only
+# then glob the remaining files, by which point every base class and namespace
+# is already defined and load order no longer matters.
 
-Dir[File.join(__dir__, "**/*.rb")].each do |f|
-  require f unless SIDE_EFFECT_FILES.any? { |name| f.end_with?(name) }
+# Files that run as side effects on load (test hooks and coverage formatters)
+# and must therefore be skipped by the eager loader.
+SIDE_EFFECT_FILES = %w[
+  minitest_simplecov.rb
+  minitest_coverage_hook.rb
+  rspec_coverage_formatter.rb
+].freeze
+
+# Recursively force every autoloaded constant under a module to load, so nested
+# namespaces (Operators::*, Mutant::*, CLI::*, Integration::*) load their bases
+# before the glob below touches their files.
+force_autoloads = lambda do |mod|
+  mod.constants(false).each do |constant|
+    value = mod.const_get(constant)
+    force_autoloads.call(value) if value.is_a?(Module) && value.name&.start_with?("Henitai")
+  end
+end
+
+force_autoloads.call(Henitai)
+
+Dir[File.join(__dir__, "**/*.rb")].each do |file|
+  require file unless SIDE_EFFECT_FILES.any? { |name| file.end_with?(name) }
 end

data/lib/henitai/execution_engine.rb

@@ -47,15 +47,16 @@ module Henitai
     end
 
     def run_parallel(mutants, integration, config, progress_reporter)
-      ProcessWorkerRunner.new(
-        worker_count: worker_count(config)
-      ).run(
+      runner = ProcessWorkerRunner.new(worker_count: worker_count(config))
+      results = runner.run(
         mutants,
         integration,
         config,
         progress_reporter,
         test_file_resolver: ->(mutant) { prioritized_tests_for(mutant, integration, config) }
       )
+      @flaky_retry_count = runner.flaky_retry_count
+      results
     end
 
     def process_mutant(mutant, integration, config, progress_reporter, mutex)

data/lib/henitai/integration/base.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../process_wakeup"
+require_relative "child_debug_support"
+require_relative "child_runtime_control"
+require_relative "scenario_log_support"
+
+module Henitai
+  module Integration
+    # Base class for all integrations. Provides the framework-agnostic child
+    # process lifecycle (wait, timeout handling, cleanup) and subprocess
+    # environment helpers. Concrete adapters mix in MutantRunSupport and
+    # implement #run_tests plus test selection.
+    class Base
+      include ChildDebugSupport
+      include ChildRuntimeControl
+
+      # @param subject [Subject]
+      # @return [Array<String>] paths to test files that cover this subject
+      def select_tests(subject)
+        raise NotImplementedError
+      end
+
+      # @return [Array<String>] all test files for the configured framework
+      def test_files
+        raise NotImplementedError
+      end
+
+      # Run test files in a child process with the mutant active.
+      #
+      # @param mutant [Mutant]
+      # @param test_files [Array<String>]
+      # @param timeout [Float] seconds
+      # @return [ScenarioExecutionResult]
+      def run_mutant(mutant:, test_files:, timeout:)
+        raise NotImplementedError
+      end
+
+      # Fork a child process for the mutant without waiting for it to finish.
+      # Returns a ChildHandle carrying the OS pid and log file paths.
+      # The caller is responsible for waiting and cleanup.
+      #
+      # @param mutant [Mutant]
+      # @param test_files [Array<String>]
+      # @return [RspecProcessRunner::ChildHandle]
+      def spawn_mutant(mutant:, test_files:)
+        raise NotImplementedError
+      end
+
+      def per_test_coverage_supported?
+        false
+      end
+
+      def wait_with_timeout(pid, timeout)
+        wakeup = Henitai.const_get(:ProcessWakeup).new.install
+        return Process.last_status if wait_nonblocking(pid)
+
+        wakeup.wait(timeout)
+        wakeup.drain
+        return Process.last_status if wait_nonblocking(pid)
+        return Process.last_status if wait_nonblocking(pid)
+
+        handle_timeout(pid)
+      ensure
+        wakeup&.close
+      end
+
+      def reap_child(pid)
+        Process.wait(pid)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+
+      def cleanup_process_group(pid)
+        grace_period = 2.0
+        wakeup = Henitai.const_get(:ProcessWakeup).new.install
+        Process.kill(:SIGTERM, -pid)
+        return if wait_nonblocking(pid)
+
+        wakeup.wait(grace_period)
+        wakeup.drain
+        return if wait_nonblocking(pid)
+
+        Process.kill(:SIGKILL, -pid)
+      rescue Errno::EPERM
+        cleanup_child_process(pid)
+      rescue Errno::ESRCH
+        nil
+      ensure
+        wakeup&.close
+      end
+
+      private
+
+      def pause(seconds)
+        sleep(seconds)
+      end
+
+      def handle_timeout(pid)
+        begin
+          debug_child_timeout_dump(pid)
+          cleanup_process_group(pid)
+        ensure
+          reap_child(pid)
+        end
+        :timeout
+      end
+
+      def cleanup_child_process(pid)
+        grace_period = 2.0
+        wakeup = Henitai.const_get(:ProcessWakeup).new.install
+        Process.kill(:SIGTERM, pid)
+        return if wait_nonblocking(pid)
+
+        wakeup.wait(grace_period)
+        wakeup.drain
+        return if wait_nonblocking(pid)
+
+        Process.kill(:SIGKILL, pid)
+      rescue Errno::EPERM, Errno::ESRCH
+        nil
+      ensure
+        wakeup&.close
+      end
+
+      def subprocess_env
+        { "PARALLEL_WORKERS" => "1" }
+      end
+
+      def wait_nonblocking(pid)
+        Process.wait(pid, Process::WNOHANG)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+
+      def scenario_log_support
+        @scenario_log_support ||= ScenarioLogSupport.new
+      end
+
+      def with_subprocess_env
+        original_env = {} # : Hash[String, String?]
+        subprocess_env.each do |key, value|
+          original_env[key] = ENV.fetch(key, nil)
+          ENV[key] = value
+        end
+        yield
+      ensure
+        restore_subprocess_env(original_env)
+      end
+
+      def restore_subprocess_env(original_env)
+        original_env.each do |key, value|
+          if value.nil?
+            ENV.delete(key)
+          else
+            ENV[key] = value
+          end
+        end
+      end
+
+      def with_non_interactive_stdin
+        original_stdin = $stdin
+        $stdin = StringIO.new
+        yield
+      ensure
+        $stdin = original_stdin
+      end
+    end
+  end
+end