henitai 0.2.0 → 0.3.0

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

data/lib/henitai/integration/child_debug_support.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Shared debug helpers for child-run diagnostics.
+    # Debug helpers are intentionally grouped here so the child-run diagnostics
+    # stay isolated from the main integration flow.
+    module ChildDebugSupport
+      private
+
+      def debug_child? = ENV["HENITAI_DEBUG_CHILD"] == "1"
+
+      # Gated here (not only at call sites) so no unguarded caller can leak
+      # debug lines into every child log by default.
+      def debug_child_puts(message)
+        return unless debug_child?
+
+        $stdout.puts(message)
+        $stdout.flush
+      end
+
+      def debug_child_rspec_trace(test_files:, rspec_options:, rspec_argv:)
+        return unless debug_child?
+
+        files_exist = test_files.map { |f| [f, File.exist?(f)] }.inspect
+        loaded_features = loaded_feature_map(test_files).inspect # steep:ignore Ruby::NoMethod
+
+        debug_child_puts(
+          "[henitai-debug-child] cwd=#{Dir.pwd}\n" \
+          "[henitai-debug-child] files_exist=#{files_exist}\n" \
+          "[henitai-debug-child] loaded_features_check=#{loaded_features}\n" \
+          "[henitai-debug-child] test_files=#{test_files.inspect}\n" \
+          "[henitai-debug-child] rspec_options=#{rspec_options.inspect}\n" \
+          "[henitai-debug-child] rspec_argv=#{rspec_argv.inspect}"
+        )
+      end
+
+      def debug_child_rspec_exit(status)
+        return unless debug_child?
+
+        debug_child_puts("[henitai-debug-child] RSpec result=#{status.inspect}")
+      end
+
+      def debug_child_example_count(stage) # steep:ignore Ruby::UndeclaredMethodDefinition
+        return unless debug_child?
+
+        count = rspec_world_example_count
+        debug_child_puts(
+          "[henitai-debug-child] rspec_world_example_count_#{stage}=#{count.inspect}"
+        )
+      end
+
+      def debug_child_activation_start(mutant_id)
+        return unless debug_child?
+
+        debug_child_puts("[henitai-debug-child] activate_start mutant=#{mutant_id}")
+      end
+
+      def debug_child_activation_end(activation_result, test_files:)
+        return unless debug_child?
+
+        debug_child_puts(
+          "[henitai-debug-child] activate_end result=#{activation_result.inspect}\n" \
+          "[henitai-debug-child] run_tests_start test_files=#{test_files.inspect}"
+        )
+      end
+
+      def debug_child_mutant_meta(mutant)
+        stable_id = mutant.respond_to?(:stable_id) ? mutant.stable_id : nil
+        operator = mutant.respond_to?(:operator) ? mutant.operator : nil
+        has_subject_expression =
+          mutant.respond_to?(:subject) && mutant.subject.respond_to?(:expression)
+        subject_expression = has_subject_expression ? mutant.subject.expression : nil
+        location = mutant.respond_to?(:location) ? mutant.location.inspect : nil
+
+        debug_child_puts(
+          "[henitai-debug-child] mutant_meta stableId=#{stable_id}\n" \
+          "[henitai-debug-child] mutant_meta operator=#{operator}\n" \
+          "[henitai-debug-child] mutant_meta subject=#{subject_expression}\n" \
+          "[henitai-debug-child] mutant_meta location=#{location}\n"
+        )
+      end
+
+      def debug_child_activation_check
+        location = begin
+          Henitai::Runner.instance_method(:resolve_subjects).source_location&.join(":") # henitai:disable
+        rescue StandardError
+          nil
+        end
+
+        debug_child_puts(
+          "[henitai-debug-child] activation_check resolve_subjects_location=#{location}\n"
+        )
+      end
+
+      def loaded_feature_map(test_files) = test_files.map { |file| [file, loaded_feature?(file)] } # steep:ignore Ruby::UndeclaredMethodDefinition
+
+      def loaded_feature?(file) # steep:ignore Ruby::UndeclaredMethodDefinition
+        expanded = File.expand_path(file)
+        candidates = [expanded, "#{expanded}.rb", file, "#{file}.rb"].uniq
+        $LOADED_FEATURES.any? do |feature|
+          normalized = begin
+            File.expand_path(feature)
+          rescue StandardError
+            feature
+          end
+          candidates.include?(feature) || candidates.include?(normalized)
+        end
+      end
+
+      def rspec_world_example_count # steep:ignore Ruby::UndeclaredMethodDefinition
+        world = ::RSpec.world
+        world.example_count
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/henitai/integration/child_runtime_control.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "coverage_suppression"
+
+module Henitai
+  module Integration
+    # Runtime controls applied inside the mutant child process: coverage
+    # suppression and the diagnostic timeout/thread-dump signal handling.
+    module ChildRuntimeControl
+      private
+
+      def suppress_simplecov!
+        CoverageRuntimeSuppressors.suppress_simplecov!
+      end
+
+      def suppress_coverage!
+        CoverageRuntimeSuppressors.suppress_coverage!
+      end
+
+      def debug_child_timeout_dump(pid)
+        return unless debug_child?
+
+        debug_child_puts("[henitai-debug-child] timeout_signal_sent pid=#{pid}")
+        Process.kill(:USR1, pid)
+        pause(0.2)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def install_debug_timeout_trap
+        Signal.trap("USR1") { debug_child_thread_dump("timeout") }
+      end
+
+      def debug_child_thread_dump(reason)
+        return unless debug_child?
+
+        debug_child_puts("[henitai-debug-child] thread_dump reason=#{reason}")
+        Thread.list.each_with_index do |thread, index|
+          debug_child_puts(
+            "[henitai-debug-child] thread index=#{index} id=#{thread.object_id} " \
+            "status=#{thread.status.inspect}"
+          )
+          Array(thread.backtrace).each do |line|
+            debug_child_puts("[henitai-debug-child]   #{line}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/henitai/integration/coverage_suppression.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Prepended onto SimpleCov's singleton class to turn start into a no-op
+    # during mutant child runs. Using prepend avoids "method redefined" warnings.
+    module SimpleCovStartSuppressor
+      def start(*_args) = nil
+    end
+
+    # Prepended onto the coverage gem's Coverage singleton to turn start
+    # into a no-op during mutant child runs.
+    module CoverageStartSuppressor
+      def start(*_args) = nil
+    end
+
+    # Suppresses expensive and irrelevant coverage startup/teardown during
+    # mutant child runs. Coverage artifacts are only required during the
+    # dedicated bootstrap phase.
+    module CoverageRuntimeSuppressors
+      # True once coverage startup has been suppressed in this process —
+      # consumers (e.g. PerTestCoverageCollector) can then treat missing
+      # coverage as expected instead of warning about it.
+      def self.active? = @active ? true : false
+
+      def self.activate! = @active = true
+
+      def self.suppress_simplecov!
+        activate!
+        require "simplecov"
+        sc = Object.const_get(:SimpleCov) # steep:ignore Ruby::UnknownConstant
+        sc.external_at_exit = true if sc.respond_to?(:external_at_exit=)
+        return if sc.singleton_class.ancestors.include?(SimpleCovStartSuppressor)
+
+        sc.singleton_class.prepend(SimpleCovStartSuppressor)
+      rescue LoadError, NameError
+        nil
+      end
+
+      def self.suppress_coverage!
+        activate!
+        require "coverage"
+        cov = Object.const_get(:Coverage) # steep:ignore Ruby::UnknownConstant
+        return if cov.singleton_class.ancestors.include?(CoverageStartSuppressor)
+
+        cov.singleton_class.prepend(CoverageStartSuppressor)
+      rescue LoadError, NameError
+        nil
+      end
+    end
+  end
+end

data/lib/henitai/integration/minitest.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "fileutils"
+# Guarded to avoid a circular require: integration.rb requires this file at its
+# tail, by which point Base is already defined, so the require is skipped.
+require_relative "../integration" unless defined?(Henitai::Integration::Base)
+require_relative "minitest_load_path"
+require_relative "minitest_suite_command"
+require_relative "minitest_test_runner"
+require_relative "rails_environment_preloader"
+
+module Henitai
+  module Integration
+    # Minitest integration adapter.
+    #
+    # A sibling of Rspec behind Base: it shares the framework-agnostic mutant-run
+    # orchestration (MutantRunSupport) and test selection (RspecTestSelection)
+    # but implements its own Minitest-specific test invocation and suite command.
+    # Per-test coverage collection is not yet wired into this path.
+    class Minitest < Base
+      include MutantRunSupport
+      include RspecTestSelection
+
+      DEFAULT_SUITE_TIMEOUT = 300.0
+
+      def test_files = spec_files
+
+      def per_test_coverage_supported?
+        true
+      end
+
+      def run_mutant(mutant:, test_files:, timeout:)
+        MinitestLoadPath.ensure!
+        super
+      end
+
+      def spawn_mutant(mutant:, test_files:)
+        MinitestLoadPath.ensure!
+        super
+      end
+
+      def run_in_child(mutant:, test_files:, log_paths:)
+        ENV["RAILS_ENV"] = "test" unless ENV["RAILS_ENV"] == "test"
+        RailsEnvironmentPreloader.new.call
+        super
+      end
+
+      def run_suite(test_files, timeout: DEFAULT_SUITE_TIMEOUT)
+        log_paths = scenario_log_paths("baseline")
+        pid = spawn_suite_process(test_files, log_paths)
+        wait_result = wait_with_timeout(pid, timeout)
+        build_result(wait_result, log_paths)
+      ensure
+        cleanup_suite_process(pid, wait_result)
+      end
+
+      def suite_command(test_files)
+        MinitestSuiteCommand.new.build(test_files)
+      end
+
+      private
+
+      def run_tests(test_files)
+        MinitestTestRunner.new.call(test_files)
+      end
+
+      def subprocess_env
+        env = super
+        env["RAILS_ENV"] = "test" unless ENV["RAILS_ENV"] == "test"
+        env["PARALLEL_WORKERS"] = "1"
+        env
+      end
+
+      def spawn_suite_process(test_files, log_paths)
+        FileUtils.mkdir_p(File.dirname(log_paths[:stdout_path]))
+        File.open(log_paths[:stdout_path], "w") do |stdout_file|
+          File.open(log_paths[:stderr_path], "w") do |stderr_file|
+            Process.spawn(
+              subprocess_env,
+              *suite_command(test_files),
+              out: stdout_file,
+              err: stderr_file
+            )
+          end
+        end
+      end
+
+      def cleanup_suite_process(pid, wait_result)
+        return unless pid
+
+        cleanup_child_process(pid)
+        reap_child(pid) if wait_result.nil?
+      end
+
+      def spec_files
+        (Dir.glob("test/**/*_test.rb") + Dir.glob("test/**/*_spec.rb"))
+          .reject { |f| f.start_with?("test/system/") }
+      end
+    end
+  end
+end

data/lib/henitai/integration/minitest_load_path.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Ensures the current project's test/ directory is on $LOAD_PATH, for
+    # Minitest#run_mutant/#spawn_mutant. Idempotent: safe to call repeatedly.
+    module MinitestLoadPath
+      def self.ensure!
+        test_dir = File.expand_path("test")
+        $LOAD_PATH.unshift(test_dir) unless $LOAD_PATH.include?(test_dir)
+      end
+    end
+  end
+end

data/lib/henitai/integration/minitest_suite_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Builds the argv used to run Minitest test files in an external Ruby
+    # process, for Minitest#spawn_suite_process's baseline coverage bootstrap.
+    class MinitestSuiteCommand
+      def build(test_files)
+        ["bundle", "exec", "ruby", "-I", "test",
+         "-r", "henitai/minitest_simplecov",
+         "-r", "henitai/minitest_coverage_hook",
+         "-e", "ARGV.each { |f| require File.expand_path(f) }",
+         *test_files]
+      end
+    end
+  end
+end

data/lib/henitai/integration/minitest_test_runner.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "coverage_suppression"
+
+module Henitai
+  module Integration
+    # Runs Minitest test files in-process and normalizes the result to an
+    # exit code, for Minitest#run_tests during a single mutant activation.
+    class MinitestTestRunner
+      def call(test_files)
+        CoverageRuntimeSuppressors.suppress_simplecov!
+        suppress_autorun!
+        test_files.each { |file| require File.expand_path(file) }
+        # @type var empty_args: Array[String]
+        empty_args = []
+        status = ::Minitest.run(empty_args)
+        return status if status.is_a?(Integer)
+
+        status == true ? 0 : 1
+      end
+
+      private
+
+      def suppress_autorun!
+        require "minitest"
+        singleton_class = ::Minitest.singleton_class
+        suppressor = @autorun_suppressor ||= Module.new.tap do |mod|
+          mod.define_method(:autorun) { nil }
+        end
+        return if singleton_class.ancestors.include?(suppressor)
+
+        singleton_class.prepend(suppressor)
+        nil
+      rescue LoadError, NameError
+        nil
+      end
+    end
+  end
+end

data/lib/henitai/integration/mutant_run_support.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Henitai
+  module Integration
+    # Framework-agnostic orchestration for running a single mutant in a child
+    # process and turning the captured child output into a ScenarioExecutionResult.
+    #
+    # The framework-specific test invocation is delegated to #run_tests, which
+    # including classes must implement.
+    module MutantRunSupport
+      def spawn_mutant(mutant:, test_files:)
+        log_paths = scenario_log_paths(mutant_log_name(mutant))
+        RspecProcessRunner.new.spawn_mutant(self, mutant:, test_files:, log_paths:)
+      end
+
+      def run_mutant(mutant:, test_files:, timeout:)
+        RspecProcessRunner.new.run_mutant(self, mutant:, test_files:, timeout:)
+      end
+
+      def scenario_log_paths(name)
+        reports_dir = ENV.fetch("HENITAI_REPORTS_DIR", "reports")
+        log_dir = File.join(reports_dir, "mutation-logs")
+        {
+          stdout_path: File.join(log_dir, "#{name}.stdout.log"),
+          stderr_path: File.join(log_dir, "#{name}.stderr.log"),
+          log_path: File.join(log_dir, "#{name}.log")
+        }
+      end
+
+      def build_result(wait_result, log_paths)
+        stdout = scenario_log_support.read_log_file(log_paths[:stdout_path])
+        stderr = scenario_log_support.read_log_file(log_paths[:stderr_path])
+        scenario_log_support.write_combined_log(log_paths[:log_path], stdout, stderr)
+
+        ScenarioExecutionResult.build(
+          wait_result:,
+          stdout:,
+          stderr:,
+          log_path: log_paths[:log_path]
+        )
+      end
+
+      def run_in_child(mutant:, test_files:, log_paths:)
+        Thread.report_on_exception = false
+        with_subprocess_env do
+          suppress_simplecov!
+          suppress_coverage!
+          install_debug_timeout_trap if debug_child?
+          with_non_interactive_stdin do
+            run_child_activation_and_tests(mutant:, test_files:, log_paths:)
+          end
+        end
+      end
+
+      def mutant_log_name(mutant)
+        "mutant-#{mutant.id}"
+      end
+
+      private
+
+      def run_child_activation_and_tests(mutant:, test_files:, log_paths:)
+        scenario_log_support.with_coverage_dir(mutant.id) do
+          scenario_log_support.capture_child_output(log_paths) do
+            debug_child_mutant_meta(mutant) if debug_child?
+            debug_child_activation_start(mutant.id)
+            activation_result = Mutant::Activator.activate!(mutant)
+            debug_child_activation_check if debug_child?
+            debug_child_activation_end(activation_result, test_files:)
+            activation_result == :compile_error ? 2 : run_tests(test_files)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/henitai/integration/rails_environment_preloader.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Henitai
+  module Integration
+    # Loads a Rails app's config/environment.rb if present, for
+    # Minitest#run_in_child. A no-op outside a Rails project.
+    class RailsEnvironmentPreloader
+      def call
+        env_file = File.expand_path("config/environment.rb")
+        require env_file if File.exist?(env_file)
+      end
+    end
+  end
+end