henitai 0.1.0

data/lib/henitai/execution_engine.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Henitai
+  # Runs pending mutants through the selected integration.
+  class ExecutionEngine
+    def run(mutants, integration, config, progress_reporter: nil)
+      with_reports_dir(config) do
+        with_coverage_dir(config) do
+          @flaky_retry_count = 0
+          pending_mutants = Array(mutants).select(&:pending?)
+          mutex = Mutex.new
+          if parallel_execution?(config, pending_mutants)
+            run_parallel(pending_mutants, integration, config, progress_reporter, mutex)
+          else
+            run_linear(pending_mutants, integration, config, progress_reporter, mutex)
+          end
+
+          warn_flaky_mutants(pending_mutants.size)
+          mutants
+        end
+      end
+    end
+
+    private
+
+    def parallel_execution?(config, mutants)
+      worker_count(config) > 1 && mutants.size > 1
+    end
+
+    def worker_count(config)
+      configured_jobs = config.respond_to?(:jobs) ? config.jobs : nil
+      configured_jobs || Etc.nprocessors
+    end
+
+    def run_linear(mutants, integration, config, progress_reporter, mutex)
+      mutants.each do |mutant|
+        process_mutant(mutant, integration, config, progress_reporter, mutex)
+      end
+    end
+
+    def run_parallel(mutants, integration, config, progress_reporter, mutex)
+      queue = Queue.new
+      mutants.each { |mutant| queue << mutant }
+
+      Array.new(worker_count(config)) do
+        Thread.new do
+          loop do
+            mutant = queue.pop(true)
+            process_mutant(mutant, integration, config, progress_reporter, mutex)
+          rescue ThreadError
+            break
+          end
+        end
+      end.each(&:join)
+    end
+
+    def process_mutant(mutant, integration, config, progress_reporter, mutex)
+      test_files = prioritized_tests_for(mutant, integration, config)
+      scenario_result = run_with_flaky_retry(mutant, integration, config, test_files, mutex)
+      mutant.status = scenario_status(scenario_result)
+
+      if mutex
+        mutex.synchronize { progress_reporter&.progress(mutant, scenario_result:) }
+      else
+        progress_reporter&.progress(mutant, scenario_result:)
+      end
+    end
+
+    def prioritized_tests_for(mutant, integration, config)
+      test_prioritizer.sort(
+        integration.select_tests(mutant.subject),
+        mutant,
+        test_history(config)
+      )
+    end
+
+    def test_prioritizer
+      @test_prioritizer ||= TestPrioritizer.new
+    end
+
+    def test_history(config)
+      return {} unless config.respond_to?(:history)
+
+      config.history || {}
+    end
+
+    # Retry logic is kept in one place to preserve the status transition flow.
+    # The retry budget is configurable because repeated survivors can multiply
+    # runtime on real CI workloads.
+    # rubocop:disable Metrics/MethodLength
+    def run_with_flaky_retry(mutant, integration, config, test_files, mutex)
+      scenario_result = integration.run_mutant(
+        mutant:,
+        test_files:,
+        timeout: config.timeout
+      )
+      return scenario_result unless scenario_status(scenario_result) == :survived
+
+      retries = 0
+      max_flaky_retries(config).times do
+        retries += 1
+        scenario_result = integration.run_mutant(
+          mutant:,
+          test_files:,
+          timeout: config.timeout
+        )
+        break unless scenario_status(scenario_result) == :survived
+      end
+
+      mutex.synchronize { @flaky_retry_count += 1 } if retries.positive?
+      scenario_result
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def scenario_status(result)
+      return result if result.is_a?(Symbol)
+
+      result.status
+    end
+
+    def warn_flaky_mutants(total_mutants)
+      return if total_mutants.zero?
+
+      flaky_ratio = @flaky_retry_count.to_f / total_mutants
+      return unless flaky_ratio > 0.05
+
+      warn format(
+        "Flaky-test mitigation: %<flaky>d/%<total>d mutants required retries (%<ratio>.2f%%)",
+        flaky: @flaky_retry_count,
+        total: total_mutants,
+        ratio: flaky_ratio * 100.0
+      )
+    end
+
+    def with_reports_dir(config)
+      original_reports_dir = ENV.fetch("HENITAI_REPORTS_DIR", nil)
+      ENV["HENITAI_REPORTS_DIR"] = config.reports_dir
+      yield
+    ensure
+      if original_reports_dir.nil?
+        ENV.delete("HENITAI_REPORTS_DIR")
+      else
+        ENV["HENITAI_REPORTS_DIR"] = original_reports_dir
+      end
+    end
+
+    def with_coverage_dir(config)
+      original_coverage_dir = ENV.fetch("HENITAI_COVERAGE_DIR", nil)
+      ENV["HENITAI_COVERAGE_DIR"] = mutation_coverage_dir(config)
+      yield
+    ensure
+      if original_coverage_dir.nil?
+        ENV.delete("HENITAI_COVERAGE_DIR")
+      else
+        ENV["HENITAI_COVERAGE_DIR"] = original_coverage_dir
+      end
+    end
+
+    def mutation_coverage_dir(config)
+      base_dir = config.respond_to?(:reports_dir) ? config.reports_dir : nil
+      base_dir = "reports" if base_dir.nil? || base_dir.empty?
+
+      File.join(base_dir, "mutation-coverage")
+    end
+
+    def max_flaky_retries(config)
+      return 3 unless config.respond_to?(:max_flaky_retries)
+
+      config.max_flaky_retries || 3
+    end
+  end
+end

data/lib/henitai/git_diff_analyzer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "subject_resolver"
+
+module Henitai
+  class GitDiffError < StandardError; end
+
+  # Shells out to git to discover changed files between two refs.
+  #
+  # By default the analyzer runs in the current working directory. Callers can
+  # pass dir: to point it at another repository root without changing cwd.
+  class GitDiffAnalyzer
+    def changed_files(from:, to:, dir: Dir.pwd)
+      stdout, stderr, status = git_diff(dir, "--name-only", from, to)
+
+      raise GitDiffError, stderr.strip unless status.success?
+
+      stdout.split("\n").reject(&:empty?)
+    end
+
+    def changed_methods(from:, to:, dir: Dir.pwd)
+      changed_files(from:, to:, dir:).flat_map do |path|
+        changed_methods_in_file(path, from:, to:, dir:)
+      end
+    end
+
+    private
+
+    def changed_methods_in_file(path, from:, to:, dir:)
+      subjects = SubjectResolver.new.resolve_from_files([File.expand_path(path, dir)])
+      changed_ranges = changed_line_ranges(path, from:, to:, dir:)
+
+      subjects.select do |subject|
+        subject.source_range &&
+          changed_ranges.any? do |range|
+            ranges_overlap?(subject.source_range, range)
+          end
+      end
+    end
+
+    def changed_line_ranges(path, from:, to:, dir:)
+      stdout, stderr, status = git_diff(dir, "--unified=0", from, to, "--", path)
+
+      raise GitDiffError, stderr.strip unless status.success?
+
+      stdout.each_line.filter_map { |line| changed_range_from_hunk(line) }
+    end
+
+    def changed_range_from_hunk(line)
+      match = line.match(/\A@@ -\d+(?:,\d+)? \+(?<start>\d+)(?:,(?<count>\d+))? @@/)
+      return unless match
+
+      start_line = match[:start].to_i
+      line_count = hunk_line_count(match)
+
+      start_line..(start_line + line_count - 1)
+    end
+
+    def hunk_line_count(match)
+      line_count = match[:count].nil? ? 1 : match[:count].to_i
+      # Git uses `+start` for a one-line hunk and `+start,0` for a pure
+      # deletion. We still anchor both at the reported start line so the
+      # current subject range can absorb the change point.
+      line_count = 1 if line_count.zero?
+      line_count
+    end
+
+    def ranges_overlap?(left, right)
+      left.begin <= right.end && right.begin <= left.end
+    end
+
+    def git_diff(dir, *git_args)
+      command = ["git"]
+      command += ["-C", dir] if dir
+      command << "diff"
+      command.concat(git_args)
+
+      Open3.capture3(*command)
+    end
+  end
+end

data/lib/henitai/integration.rb

@@ -0,0 +1,417 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "minitest"
+require "rspec/core"
+
+module Henitai
+  # Namespace for test-framework integrations.
+  #
+  # An Integration is responsible for:
+  #   1. Discovering test files relevant to a Subject (test selection)
+  #   2. Running the selected tests in a child process with a mutant injected
+  #   3. Reporting pass/fail/timeout to the runner
+  #
+  # Test selection uses longest-prefix matching:
+  #   Subject expression "Foo::Bar#method" matches example groups whose
+  #   description contains "Foo::Bar" or "Foo::Bar#method".
+  #
+  # Built-in integrations:
+  #   rspec  — RSpec 3.x
+  module Integration
+    # Shared helpers for capturing stdout/stderr from child test processes.
+    class ScenarioLogSupport
+      def capture_child_output(log_paths)
+        output_files = open_child_output(log_paths)
+        yield
+      ensure
+        close_child_output(output_files)
+      end
+
+      def with_coverage_dir(mutant_id)
+        original_coverage_dir = ENV.fetch("HENITAI_COVERAGE_DIR", nil)
+        ENV["HENITAI_COVERAGE_DIR"] = mutation_coverage_dir(mutant_id)
+        yield
+      ensure
+        if original_coverage_dir.nil?
+          ENV.delete("HENITAI_COVERAGE_DIR")
+        else
+          ENV["HENITAI_COVERAGE_DIR"] = original_coverage_dir
+        end
+      end
+
+      def open_child_output(log_paths)
+        FileUtils.mkdir_p(File.dirname(log_paths[:log_path]))
+        output_files = build_child_output_files(log_paths)
+        sync_child_output_files(output_files)
+        redirect_child_output(output_files)
+        output_files
+      end
+
+      def close_child_output(output_files)
+        return unless output_files
+
+        restore_child_output(output_files)
+        close_child_output_files(output_files)
+      end
+
+      def build_child_output_files(log_paths)
+        {
+          original_stdout: $stdout.dup,
+          original_stderr: $stderr.dup,
+          stdout_file: File.new(log_paths[:stdout_path], "w"),
+          stderr_file: File.new(log_paths[:stderr_path], "w")
+        }
+      end
+
+      def sync_child_output_files(output_files)
+        output_files[:stdout_file].sync = true
+        output_files[:stderr_file].sync = true
+      end
+
+      def redirect_child_output(output_files)
+        $stdout.reopen(output_files[:stdout_file])
+        $stderr.reopen(output_files[:stderr_file])
+      end
+
+      def restore_child_output(output_files)
+        reopen_child_output_stream($stdout, output_files[:original_stdout])
+        reopen_child_output_stream($stderr, output_files[:original_stderr])
+      end
+
+      def reopen_child_output_stream(stream, original_stream)
+        stream.reopen(original_stream) if original_stream
+      end
+
+      def close_child_output_files(output_files)
+        %i[stdout_file stderr_file original_stdout original_stderr].each do |key|
+          output_files[key]&.close
+        end
+      end
+
+      private
+
+      def mutation_coverage_dir(mutant_id)
+        reports_dir = ENV.fetch("HENITAI_REPORTS_DIR", "reports")
+        File.join(reports_dir, "mutation-coverage", mutant_id.to_s)
+      end
+    end
+
+    # Integration adapter for RSpec.
+    #
+    # This class exists as the stable public entry point for the RSpec
+    # integration, even though the concrete behavior is not implemented yet.
+    # @param name [String] integration name, e.g. "rspec"
+    # @return [Class] integration class
+    def self.for(name)
+      const_get(name.capitalize)
+    rescue NameError
+      raise ArgumentError, "Unknown integration: #{name}. Available: rspec"
+    end
+
+    # Base class for all integrations.
+    class Base
+      # @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
+    end
+
+    # RSpec integration adapter.
+    class Rspec < Base
+      DEFAULT_SUITE_TIMEOUT = 300.0
+      REQUIRE_DIRECTIVE_PATTERN = /
+        \A\s*
+        (require|require_relative)
+        \s*
+        (?:\(\s*)?
+        ["']([^"']+)["']
+        \s*\)?
+      /x
+
+      def select_tests(subject)
+        matches = spec_files.select do |path|
+          content = File.read(path)
+          selection_patterns(subject).any? { |pattern| content.include?(pattern) }
+        rescue StandardError
+          false
+        end
+
+        return matches unless matches.empty?
+
+        fallback_spec_files(subject)
+      end
+
+      def test_files
+        spec_files
+      end
+
+      def run_mutant(mutant:, test_files:, timeout:)
+        log_paths = scenario_log_paths("mutant-#{mutant.id}")
+        pid = Process.fork do
+          ENV["HENITAI_MUTANT_ID"] = mutant.id
+          Process.exit(run_in_child(mutant:, test_files:, log_paths:))
+        end
+
+        build_result(wait_with_timeout(pid, timeout), log_paths)
+      end
+
+      def run_suite(test_files, timeout: DEFAULT_SUITE_TIMEOUT)
+        log_paths = scenario_log_paths("baseline")
+        FileUtils.mkdir_p(File.dirname(log_paths[:stdout_path]))
+        pid = File.open(log_paths[:stdout_path], "w") do |stdout_file|
+          File.open(log_paths[:stderr_path], "w") do |stderr_file|
+            Process.spawn(*suite_command(test_files), out: stdout_file, err: stderr_file)
+          end
+        end
+        build_result(wait_with_timeout(pid, timeout), log_paths)
+      end
+
+      private
+
+      def run_in_child(mutant:, test_files:, log_paths:)
+        scenario_log_support.with_coverage_dir(mutant.id) do
+          scenario_log_support.capture_child_output(log_paths) do
+            return 2 if Mutant::Activator.activate!(mutant) == :compile_error
+
+            run_tests(test_files)
+          end
+        end
+      end
+
+      def suite_command(test_files)
+        ["bundle", "exec", "rspec", *test_files]
+      end
+
+      def wait_with_timeout(pid, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+        loop do
+          return Process.last_status if Process.wait(pid, Process::WNOHANG)
+          return handle_timeout(pid) if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          pause(0.01)
+        end
+      end
+
+      def handle_timeout(pid)
+        begin
+          Process.kill(:SIGTERM, pid)
+          pause(2.0)
+          Process.kill(:SIGKILL, pid)
+        rescue Errno::ESRCH
+          # The child may exit after SIGTERM but before SIGKILL.
+        ensure
+          reap_child(pid)
+        end
+        :timeout
+      end
+
+      def run_tests(test_files)
+        status = RSpec::Core::Runner.run(test_files + rspec_options)
+        return status if status.is_a?(Integer)
+
+        status == true ? 0 : 1
+      end
+
+      def rspec_options
+        ["--require", "henitai/coverage_formatter"]
+      end
+
+      def pause(seconds)
+        sleep(seconds)
+      end
+
+      def scenario_log_support
+        @scenario_log_support ||= ScenarioLogSupport.new
+      end
+
+      def read_log_file(path)
+        return "" unless File.exist?(path)
+
+        File.read(path)
+      end
+
+      def write_combined_log(path, stdout, stderr)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, combined_log(stdout, stderr))
+      end
+
+      def combined_log(stdout, stderr)
+        [
+          (stdout.empty? ? nil : "stdout:\n#{stdout}"),
+          (stderr.empty? ? nil : "stderr:\n#{stderr}")
+        ].compact.join("\n")
+      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)
+        status = scenario_status(wait_result)
+        stdout = read_log_file(log_paths[:stdout_path])
+        stderr = read_log_file(log_paths[:stderr_path])
+        write_combined_log(log_paths[:log_path], stdout, stderr)
+
+        ScenarioExecutionResult.new(
+          status:,
+          stdout:,
+          stderr:,
+          log_path: log_paths[:log_path],
+          exit_status: exit_status_for(wait_result)
+        )
+      end
+
+      def scenario_status(wait_result)
+        return :timeout if wait_result == :timeout
+        return :compile_error if exit_status_for(wait_result) == 2
+        return :survived if wait_result.respond_to?(:success?) && wait_result.success?
+
+        :killed
+      end
+
+      def exit_status_for(wait_result)
+        return nil if wait_result == :timeout
+        return nil unless wait_result.respond_to?(:exitstatus)
+
+        wait_result.exitstatus
+      end
+
+      def spec_files
+        Dir.glob("spec/**/*_spec.rb")
+      end
+
+      def fallback_spec_files(subject)
+        return [] unless subject.source_file
+
+        matches = spec_files.select do |path|
+          requires_source_file_transitively?(path, subject.source_file)
+        rescue StandardError
+          false
+        end
+
+        matches.empty? ? spec_files : matches
+      end
+
+      def selection_patterns(subject)
+        [
+          subject.expression,
+          subject.namespace
+        ].compact.uniq.sort_by(&:length).reverse
+      end
+
+      def requires_source_file?(spec_file, source_file)
+        content = File.read(spec_file)
+        basename = File.basename(source_file, ".rb")
+        content.include?(basename) || content.include?(source_file)
+      end
+
+      def requires_source_file_transitively?(spec_file, source_file, visited = [])
+        normalized_spec_file = File.expand_path(spec_file)
+        return false if visited.include?(normalized_spec_file)
+
+        visited << normalized_spec_file
+        return true if requires_source_file?(spec_file, source_file)
+
+        required_files(spec_file).any? do |required_file|
+          requires_source_file_transitively?(required_file, source_file, visited)
+        end
+      end
+
+      def required_files(spec_file)
+        File.read(spec_file).lines.filter_map do |line|
+          match = line.match(REQUIRE_DIRECTIVE_PATTERN)
+          next unless match
+
+          resolve_required_file(spec_file, match[1].to_s, match[2].to_s)
+        end
+      end
+
+      def resolve_required_file(spec_file, method_name, required_path)
+        candidates =
+          if method_name == "require_relative"
+            relative_candidates(spec_file, required_path)
+          else
+            require_candidates(spec_file, required_path)
+          end
+
+        candidates.find { |candidate| File.file?(candidate) }
+      end
+
+      def relative_candidates(spec_file, required_path)
+        expand_candidates(File.dirname(spec_file), required_path)
+      end
+
+      def require_candidates(spec_file, required_path)
+        ([File.dirname(spec_file), Dir.pwd] + $LOAD_PATH).flat_map do |base_path|
+          expand_candidates(base_path, required_path)
+        end
+      end
+
+      def expand_candidates(base_path, required_path)
+        [
+          File.expand_path(required_path, base_path),
+          File.expand_path("#{required_path}.rb", base_path)
+        ].uniq
+      end
+
+      def reap_child(pid)
+        Process.wait(pid)
+      rescue Errno::ECHILD, Errno::ESRCH
+        nil
+      end
+    end
+
+    # Minitest integration adapter.
+    #
+    # Coverage formatter injection remains implemented in the RSpec child
+    # runner. Minitest shares selection and execution semantics, but per-test
+    # coverage collection is not yet wired into this path.
+    class Minitest < Rspec
+      private
+
+      def suite_command(test_files)
+        ["bundle", "exec", "ruby", "-I", "test",
+         "-e", "ARGV.each { |f| require File.expand_path(f) }",
+         *test_files]
+      end
+
+      def run_tests(test_files)
+        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
+
+      def spec_files
+        Dir.glob("test/**/*_test.rb") + Dir.glob("test/**/*_spec.rb")
+      end
+    end
+  end
+end