henitai 0.1.0

data/lib/henitai/configuration_validator.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Henitai
+  # rubocop:disable Metrics/ModuleLength
+  # Internal validator for configuration data loaded from YAML and CLI overrides.
+  module ConfigurationValidator
+    VALID_TOP_LEVEL_KEYS = %i[
+      integration
+      includes
+      mutation
+      coverage_criteria
+      thresholds
+      reporters
+      reports_dir
+      all_logs
+      dashboard
+      jobs
+    ].freeze
+    VALID_MUTATION_KEYS = %i[operators timeout ignore_patterns max_mutants_per_line max_flaky_retries sampling].freeze
+    VALID_SAMPLING_KEYS = %i[ratio strategy].freeze
+    VALID_COVERAGE_CRITERIA_KEYS = %i[test_result timeout process_abort].freeze
+    VALID_THRESHOLDS_KEYS = %i[high low].freeze
+    VALID_DASHBOARD_KEYS = %i[project base_url].freeze
+    VALID_INTEGRATION_KEYS = %i[name].freeze
+    VALID_OPERATORS = %i[light full].freeze
+    VALIDATION_STEPS = %i[
+      validate_top_level_keys
+      validate_integration
+      validate_includes
+      validate_jobs
+      validate_reporters
+      validate_reports_dir
+      validate_all_logs
+      validate_dashboard
+      validate_mutation
+      validate_coverage_criteria
+      validate_thresholds
+    ].freeze
+
+    def self.validate!(raw)
+      ensure_hash!(raw, "configuration")
+      VALIDATION_STEPS.each { |step| 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_mutants_per_line(value[:max_mutants_per_line])
+        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_mutants_per_line(value)
+        return if value.nil?
+        return if value.is_a?(Integer) && value >= 1
+
+        configuration_error(
+          "Invalid configuration value for mutation.max_mutants_per_line: expected Integer >= 1, got #{value.inspect}"
+        )
+      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
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/henitai/coverage_bootstrapper.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Ensures coverage data exists before the mutation pipeline starts.
+  class CoverageBootstrapper
+    def initialize(static_filter: StaticFilter.new)
+      @static_filter = static_filter
+    end
+
+    def ensure!(source_files:, config:, integration:)
+      return if source_files.empty?
+      return if coverage_available?(source_files, config)
+
+      bootstrap_coverage(integration, config)
+      return if coverage_available?(source_files, config)
+
+      raise CoverageError,
+            "Coverage data is unavailable for the configured source files"
+    end
+
+    private
+
+    attr_reader :static_filter
+
+    def coverage_available?(source_files, config)
+      coverage_lines = static_filter.coverage_lines_for(config)
+
+      source_file_paths(source_files).any? do |path|
+        Array(coverage_lines[path]).any?
+      end
+    end
+
+    def source_file_paths(source_files)
+      Array(source_files).map { |path| File.expand_path(path) }
+    end
+
+    def bootstrap_coverage(integration, config)
+      with_coverage_dir(config) do
+        result = integration.run_suite(integration.test_files)
+        return if result == :survived
+
+        raise CoverageError, build_bootstrap_error(result)
+      end
+    end
+
+    def build_bootstrap_error(result)
+      return "Configured test suite failed while generating coverage" unless result.respond_to?(:log_path)
+
+      tail = result.tail(12).strip
+      message = +"Configured test suite failed while generating coverage"
+      message << " (see #{result.log_path})"
+      message << "\n#{tail}" unless tail.empty?
+      message
+    end
+
+    def with_coverage_dir(config)
+      original_coverage_dir = ENV.fetch("HENITAI_COVERAGE_DIR", nil)
+      ENV["HENITAI_COVERAGE_DIR"] = 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 coverage_dir(config)
+      reports_dir = config.respond_to?(:reports_dir) ? config.reports_dir : nil
+      return "coverage" if reports_dir.nil? || reports_dir.empty?
+
+      File.join(reports_dir, "coverage")
+    end
+  end
+end

data/lib/henitai/coverage_formatter.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "coverage"
+require "fileutils"
+require "json"
+
+module Henitai
+  # Collects per-test coverage data for static filtering heuristics.
+  class CoverageFormatter
+    REPORT_DIR_ENV = "HENITAI_REPORTS_DIR"
+    REPORT_FILE_NAME = "henitai_per_test.json"
+
+    RSpec::Core::Formatters.register self, :example_finished, :dump_summary
+
+    def initialize(_output)
+      @coverage_by_test = Hash.new do |hash, test_file|
+        hash[test_file] = Hash.new { |nested, source_file| nested[source_file] = [] }
+      end
+      @previous_snapshot = {}
+      @warned_missing_coverage = false
+    end
+
+    def example_finished(notification)
+      snapshot = current_snapshot
+      return warn_missing_coverage unless snapshot
+
+      test_file = notification.example.metadata[:file_path]
+      new_lines(snapshot).each do |source_file, lines|
+        @coverage_by_test[test_file][source_file].concat(lines)
+        @coverage_by_test[test_file][source_file].uniq!
+        @coverage_by_test[test_file][source_file].sort!
+      end
+      @previous_snapshot = snapshot
+    end
+
+    def dump_summary(_summary)
+      return if @coverage_by_test.empty?
+
+      FileUtils.mkdir_p(File.dirname(report_path))
+      File.write(report_path, JSON.pretty_generate(serializable_report))
+    end
+
+    private
+
+    def report_path
+      File.join(reports_dir, REPORT_FILE_NAME)
+    end
+
+    def reports_dir
+      ENV.fetch(REPORT_DIR_ENV, "coverage")
+    end
+
+    def current_snapshot
+      Coverage.peek_result
+    rescue StandardError
+      nil
+    end
+
+    def warn_missing_coverage
+      return if @warned_missing_coverage
+
+      warn "Per-test coverage unavailable; skipping coverage formatter output"
+      @warned_missing_coverage = true
+    end
+
+    def new_lines(snapshot)
+      snapshot.each_with_object({}) do |(source_file, file_coverage), result|
+        next unless source_file?(source_file)
+
+        lines = new_line_numbers(
+          file_coverage,
+          previous_line_counts(source_file)
+        )
+        result[source_file] = lines unless lines.empty?
+      end
+    end
+
+    def new_line_numbers(file_coverage, previous_counts)
+      line_counts_for(file_coverage).each_with_index.filter_map do |count, index|
+        next unless count.to_i.positive?
+        next if previous_counts.fetch(index, 0).to_i.positive?
+
+        index + 1
+      end
+    end
+
+    def previous_line_counts(source_file)
+      line_counts_for(@previous_snapshot.fetch(source_file, []))
+    end
+
+    def line_counts_for(file_coverage)
+      case file_coverage
+      when Hash
+        Array(file_coverage["lines"])
+      else
+        Array(file_coverage)
+      end
+    end
+
+    def source_file?(path)
+      expanded = File.expand_path(path)
+      expanded.start_with?(Dir.pwd) &&
+        !expanded.include?("#{File::SEPARATOR}spec#{File::SEPARATOR}")
+    end
+
+    def serializable_report
+      @coverage_by_test.transform_values do |source_map|
+        source_map.transform_values { |lines| lines.uniq.sort }
+      end
+    end
+  end
+end

data/lib/henitai/equivalence_detector.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "parser_current"
+
+module Henitai
+  # Detects obvious equivalent mutants before execution.
+  #
+  # The detector is intentionally conservative: it only marks mutations as
+  # equivalent when the AST shape and the operand literals make the equivalence
+  # obvious enough to be useful.
+  class EquivalenceDetector
+    def analyze(mutant)
+      return mutant unless equivalent_arithmetic_mutation?(mutant)
+
+      mutant.status = :equivalent
+      mutant
+    end
+
+    private
+
+    def equivalent_arithmetic_mutation?(mutant)
+      original = mutant.original_node
+      mutated = mutant.mutated_node
+      return false unless binary_send?(original) && binary_send?(mutated)
+      return false unless same_receiver?(original, mutated)
+
+      additive_equivalent?(original, mutated) ||
+        multiplicative_equivalent?(original, mutated)
+    end
+
+    def binary_send?(node)
+      node.is_a?(Parser::AST::Node) && node.type == :send && node.children.size >= 3
+    end
+
+    def same_receiver?(original, mutated)
+      same_node?(original.children[0], mutated.children[0])
+    end
+
+    def additive_equivalent?(original, mutated)
+      additive_operator?(original.children[1]) &&
+        additive_operator?(mutated.children[1]) &&
+        zero_operand?(original) &&
+        zero_operand?(mutated)
+    end
+
+    def multiplicative_equivalent?(original, mutated)
+      multiplicative_operator?(original.children[1]) &&
+        multiplicative_operator?(mutated.children[1]) &&
+        one_operand?(original) &&
+        one_operand?(mutated)
+    end
+
+    def additive_operator?(operator)
+      %i[+ -].include?(operator)
+    end
+
+    def multiplicative_operator?(operator)
+      %i[* / **].include?(operator)
+    end
+
+    def zero_operand?(node)
+      numeric_operand?(node, 0)
+    end
+
+    def one_operand?(node)
+      numeric_operand?(node, 1)
+    end
+
+    def numeric_operand?(node, value)
+      operand = node.children[2]
+      return false unless operand.is_a?(Parser::AST::Node)
+
+      case operand.type
+      when :int, :float
+        operand.children.first == value || operand.children.first == value.to_i
+      else
+        false
+      end
+    end
+
+    def same_node?(left, right)
+      left == right
+    end
+  end
+end