henitai 0.1.0

data/lib/henitai/runner.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Orchestrates the full mutation testing pipeline.
+  #
+  # Pipeline phases (Phase-Gate model):
+  #
+  #   Gate 1 — Subject selection
+  #     Resolve source files from includes, apply --since filter (incremental),
+  #     build Subject list from AST.
+  #
+  #   Gate 2 — Mutant generation
+  #     Apply operators to each Subject's AST. Filter arid (non-productive)
+  #     nodes via ignore_patterns. Produces the initial mutant list.
+  #
+  #   Gate 3 — Static filtering
+  #     Remove ignored mutants (pattern matches), compile-time errors.
+  #     Apply per-test coverage data: mark :no_coverage for uncovered mutants.
+  #
+  #   Gate 4 — Mutant execution
+  #     Run surviving mutants in isolated child processes (fork isolation).
+  #     Each child process loads the test suite with the mutated method
+  #     injected via Module#define_method. Collect kill/survive/timeout results.
+  #
+  #   Gate 5 — Reporting
+  #     Write results to configured reporters (terminal, html, json, dashboard).
+  #
+  class Runner
+    attr_reader :config, :result
+
+    def initialize(config: Configuration.load, subjects: nil, since: nil)
+      @config   = config
+      @subjects = subjects
+      @since    = since
+    end
+
+    # Entry point — runs the full pipeline and returns a Result.
+    # @return [Result]
+    def run
+      started_at = Time.now
+      source_files = self.source_files
+      bootstrap_coverage(source_files)
+      subjects = resolve_subjects(source_files)
+      mutants = generate_mutants(subjects)
+      mutants = filter_mutants(mutants)
+      mutants = execute_mutants(mutants)
+      finished_at = Time.now
+
+      build_result(mutants, started_at, finished_at)
+    end
+
+    private
+
+    def resolve_subjects(source_files = self.source_files)
+      subjects = subject_resolver.resolve_from_files(source_files)
+      return subjects if pattern_subjects.empty?
+
+      selected_subjects = pattern_subjects.flat_map do |pattern|
+        subject_resolver.apply_pattern(subjects, pattern.expression)
+      end
+      unique_subjects(selected_subjects)
+    end
+
+    def generate_mutants(subjects)
+      mutant_generator.generate(subjects, operators, config:)
+    end
+
+    def filter_mutants(mutants)
+      static_filter.apply(mutants, config)
+    end
+
+    def execute_mutants(mutants)
+      execution_engine.run(
+        mutants,
+        integration,
+        config,
+        progress_reporter: progress_reporter
+      )
+    end
+
+    def report(result)
+      Reporter.run_all(names: config.reporters, result:, config:)
+    end
+
+    def persist_history(result, recorded_at)
+      history_store.record(
+        result,
+        version: Henitai::VERSION,
+        recorded_at:
+      )
+    end
+
+    def build_result(mutants, started_at, finished_at)
+      @result = Result.new(
+        mutants:,
+        started_at:,
+        finished_at:
+      )
+      persist_history(@result, finished_at)
+      report(@result)
+      @result
+    end
+
+    def subject_resolver
+      @subject_resolver ||= SubjectResolver.new
+    end
+
+    def git_diff_analyzer
+      @git_diff_analyzer ||= GitDiffAnalyzer.new
+    end
+
+    def mutant_generator
+      @mutant_generator ||= MutantGenerator.new
+    end
+
+    def static_filter
+      @static_filter ||= StaticFilter.new
+    end
+
+    def execution_engine
+      @execution_engine ||= ExecutionEngine.new
+    end
+
+    def coverage_bootstrapper
+      @coverage_bootstrapper ||= CoverageBootstrapper.new
+    end
+
+    def bootstrap_coverage(source_files)
+      coverage_bootstrapper.ensure!(source_files:, config:, integration:)
+    end
+
+    def integration
+      @integration ||= Integration.for(config.integration).new
+    end
+
+    def operators
+      @operators ||= Operator.for_set(config.operators)
+    end
+
+    def progress_reporter
+      return nil unless Array(config.reporters).map(&:to_s).include?("terminal")
+
+      Reporter::Terminal.new(config:)
+    end
+
+    def history_store
+      @history_store ||= MutantHistoryStore.new(
+        path: File.join(config.reports_dir, Henitai::HISTORY_STORE_FILENAME)
+      )
+    end
+
+    def source_files
+      @source_files ||= begin
+        included_files = Array(config.includes).flat_map do |include_path|
+          Dir.glob(File.join(include_path, "**", "*.rb"))
+        end.uniq
+
+        if @since
+          changed_files = git_diff_analyzer.changed_files(from: @since, to: "HEAD")
+          changed_file_set = changed_files.map { |path| normalize_path(path) }
+
+          included_files.select do |path|
+            changed_file_set.include?(normalize_path(path))
+          end
+        else
+          included_files
+        end
+      end
+    end
+
+    def pattern_subjects
+      Array(@subjects)
+    end
+
+    def unique_subjects(subjects)
+      subjects.uniq { |subject| [subject.expression, subject.source_file] }
+    end
+
+    def normalize_path(path)
+      File.expand_path(path)
+    end
+  end
+end

data/lib/henitai/sampling_strategy.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Samples mutants in a strategy-aware, deterministic way.
+  class SamplingStrategy
+    def sample(mutants, ratio:, strategy: :stratified)
+      strategy = strategy.to_sym if strategy.respond_to?(:to_sym)
+
+      case strategy
+      when :stratified
+        stratified_sample(Array(mutants), ratio:)
+      else
+        raise ArgumentError, "Unsupported sampling strategy: #{strategy}"
+      end
+    end
+
+    private
+
+    def stratified_sample(mutants, ratio:)
+      return [] if ratio.to_f <= 0.0
+
+      mutants.group_by { |mutant| mutant.subject.expression }.flat_map do |_subject, group|
+        group.take(sample_count(group.size, ratio))
+      end
+    end
+
+    def sample_count(size, ratio)
+      count = (size * ratio).ceil
+      count = 1 if count < 1
+      [count, size].min
+    end
+  end
+end

data/lib/henitai/scenario_execution_result.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Captures the result of one baseline or mutant test run.
+  class ScenarioExecutionResult
+    attr_reader :status, :stdout, :stderr, :exit_status, :log_path
+
+    def initialize(status:, stdout:, stderr:, log_path:, exit_status: nil)
+      @status = status
+      @stdout = stdout.to_s
+      @stderr = stderr.to_s
+      @log_path = log_path
+      @exit_status = exit_status
+    end
+
+    def survived?
+      status == :survived
+    end
+
+    def killed?
+      status == :killed
+    end
+
+    def timeout?
+      status == :timeout
+    end
+
+    def ==(other)
+      return status == other.status if other.respond_to?(:status)
+      return status == other if other.is_a?(Symbol)
+
+      super
+    end
+
+    def log_text
+      @log_text ||= if File.exist?(log_path)
+                      File.read(log_path)
+                    else
+                      combined_output
+                    end
+    end
+
+    def combined_output
+      [
+        (stdout.empty? ? nil : stream_section("stdout", stdout)),
+        (stderr.empty? ? nil : stream_section("stderr", stderr))
+      ].compact.join("\n")
+    end
+
+    def tail(lines = 12)
+      log_text.lines.last(lines).join
+    end
+
+    def should_show_logs?(all_logs: false)
+      all_logs || timeout?
+    end
+
+    def failure_tail(all_logs: false, lines: 12)
+      return combined_output if all_logs
+      return "" unless should_show_logs?(all_logs:)
+
+      tail(lines)
+    end
+
+    private
+
+    def stream_section(name, content)
+      "#{name}:\n#{content}"
+    end
+  end
+end

data/lib/henitai/source_parser.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "parser/source/buffer"
+require "prism"
+
+module Henitai
+  # Parses Ruby source into parser-compatible AST nodes using Prism.
+  #
+  # The parser translation layer keeps the `Parser::AST::Node` shape that the
+  # mutation pipeline and Unparser already expect, while delegating syntax
+  # support to Prism.
+  class SourceParser
+    DEFAULT_PATH = "(string)"
+
+    def self.parse(source, path: DEFAULT_PATH)
+      new.parse(source, path:)
+    end
+
+    def self.parse_file(path)
+      new.parse_file(path)
+    end
+
+    def parse(source, path: DEFAULT_PATH)
+      Prism::Translation::ParserCurrent.new.parse(source_buffer(source, path))
+    end
+
+    def parse_file(path)
+      # Ruby's file encoding rules apply here. Projects that use explicit source
+      # encoding comments can be handled by a future encoding-aware option.
+      parse(File.read(path), path:)
+    end
+
+    private
+
+    def source_buffer(source, path)
+      Parser::Source::Buffer.new(path).tap do |buffer|
+        buffer.source = source
+      end
+    end
+  end
+end

data/lib/henitai/static_filter.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Henitai
+  # Applies static, pre-execution filtering to generated mutants.
+  class StaticFilter
+    DEFAULT_COVERAGE_REPORT_PATH = "coverage/.resultset.json"
+    DEFAULT_PER_TEST_COVERAGE_REPORT_PATH = "coverage/henitai_per_test.json"
+
+    # This method is the gate-level filter orchestrator.
+    def apply(mutants, config)
+      coverage_lines = coverage_lines_for(config)
+      coverage_report_present = coverage_report_present?(config)
+
+      Array(mutants).each do |mutant|
+        next if ignored_mutant?(mutant, config)
+
+        mark_equivalent_mutant(mutant)
+        mark_no_coverage_mutant(
+          mutant,
+          coverage_report_present:,
+          coverage_lines:
+        )
+      end
+
+      mutants
+    end
+
+    def coverage_lines_for(config)
+      coverage_report_path = coverage_report_path(config)
+      per_test_coverage_report_path = per_test_coverage_report_path(config)
+
+      coverage_lines = coverage_lines_by_file(coverage_report_path)
+      return coverage_lines unless coverage_lines.empty?
+
+      coverage_lines_from_test_lines(
+        test_lines_by_file(per_test_coverage_report_path)
+      )
+    end
+
+    def coverage_lines_by_file(path = DEFAULT_COVERAGE_REPORT_PATH)
+      return {} unless File.exist?(path)
+
+      coverage = Hash.new { |hash, key| hash[key] = [] }
+      JSON.parse(File.read(path)).each_value do |result|
+        result.fetch("coverage", {}).each do |file, file_coverage|
+          coverage[normalize_path(file)].concat(covered_lines(file_coverage))
+        end
+      end
+
+      coverage.transform_values(&:uniq).transform_values(&:sort)
+    end
+
+    def test_lines_by_file(path = DEFAULT_PER_TEST_COVERAGE_REPORT_PATH)
+      return {} unless File.exist?(path)
+
+      parsed = JSON.parse(File.read(path))
+      return {} unless parsed.is_a?(Hash)
+
+      parsed.transform_values do |coverage|
+        normalize_test_coverage(coverage)
+      end
+    end
+
+    private
+
+    def ignored?(mutant, config)
+      source = source_for(mutant)
+      return false unless source
+
+      compiled_ignore_patterns(config).any? do |pattern|
+        pattern.match?(source)
+      end
+    end
+
+    def ignored_mutant?(mutant, config)
+      return false unless ignored?(mutant, config)
+
+      mutant.status = :ignored
+      true
+    end
+
+    def mark_equivalent_mutant(mutant)
+      return unless mutant.pending?
+
+      equivalence_detector.analyze(mutant)
+    end
+
+    def mark_no_coverage_mutant(mutant, coverage_report_present:, coverage_lines:)
+      return unless coverage_report_present
+      return unless mutant.pending?
+      return if covered?(mutant, coverage_lines)
+
+      mutant.status = :no_coverage
+    end
+
+    def covered?(mutant, coverage_lines)
+      file = normalize_path(mutant.location[:file])
+      start_line = mutant.location[:start_line]
+
+      Array(coverage_lines[file]).include?(start_line)
+    end
+
+    def source_for(mutant)
+      original_node = mutant.original_node
+      location = original_node&.location
+      expression = location&.expression
+      expression&.source
+    end
+
+    def compiled_ignore_patterns(config)
+      patterns = Array(config&.ignore_patterns).dup.freeze
+      @compiled_ignore_patterns ||= {}
+      @compiled_ignore_patterns[patterns] ||= patterns.map { |pattern| Regexp.new(pattern) }
+    end
+
+    def covered_lines(file_coverage)
+      Array(file_coverage["lines"]).each_with_index.filter_map do |count, index|
+        index + 1 if count.to_i.positive?
+      end
+    end
+
+    def normalize_test_coverage(coverage)
+      case coverage
+      when Hash
+        coverage.transform_values do |lines|
+          Array(lines).grep(Integer).uniq.sort
+        end
+      else
+        Array(coverage).grep(Integer).uniq.sort
+      end
+    end
+
+    def coverage_lines_from_test_lines(test_lines)
+      coverage = Hash.new { |hash, key| hash[key] = [] }
+
+      test_lines.each_value do |source_coverage|
+        next unless source_coverage.is_a?(Hash)
+
+        source_coverage.each do |source_file, lines|
+          coverage[normalize_path(source_file)].concat(Array(lines).grep(Integer))
+        end
+      end
+
+      coverage.transform_values(&:uniq).transform_values(&:sort)
+    end
+
+    def normalize_path(path)
+      File.expand_path(path)
+    end
+
+    def equivalence_detector
+      @equivalence_detector ||= EquivalenceDetector.new
+    end
+
+    def coverage_report_path(config)
+      File.join(coverage_dir_for(config), ".resultset.json")
+    end
+
+    def coverage_report_present?(config)
+      coverage_report_path = coverage_report_path(config)
+      per_test_coverage_report_path = per_test_coverage_report_path(config)
+
+      File.exist?(coverage_report_path) || File.exist?(per_test_coverage_report_path)
+    end
+
+    def per_test_coverage_report_path(config)
+      reports_dir = reports_dir_for(config)
+      File.join(reports_dir, File.basename(DEFAULT_PER_TEST_COVERAGE_REPORT_PATH))
+    end
+
+    def coverage_dir_for(config)
+      return "coverage" unless config.respond_to?(:reports_dir)
+      return "coverage" if config.reports_dir.nil? || config.reports_dir.empty?
+
+      File.join(config.reports_dir, "coverage")
+    end
+
+    def reports_dir_for(config)
+      return "coverage" unless config.respond_to?(:reports_dir)
+
+      config.reports_dir || "coverage"
+    end
+  end
+end

data/lib/henitai/stillborn_filter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "unparser"
+
+module Henitai
+  # Suppresses mutants that do not produce syntactically valid Ruby.
+  class StillbornFilter
+    def suppressed?(mutant)
+      source = render(mutant)
+      return true unless source
+
+      RubyVM::InstructionSequence.compile(wrapped_source(source))
+      false
+    rescue SyntaxError
+      true
+    end
+
+    private
+
+    def render(mutant)
+      Unparser.unparse(mutant.mutated_node)
+    rescue StandardError
+      nil
+    end
+
+    def wrapped_source(source)
+      <<~RUBY
+        def __henitai_stillborn__
+          #{source}
+        end
+      RUBY
+    end
+  end
+end

data/lib/henitai/subject.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Represents an addressable unit of source code to be mutated.
+  #
+  # Subjects are expressed using a compact syntax:
+  #   Foo::Bar#instance_method    — specific instance method
+  #   Foo::Bar.class_method       — specific class method
+  #   Foo::Bar*                   — all methods on Foo::Bar
+  #   Foo*                        — all methods in the Foo namespace
+  #
+  # The Subject is resolved from the AST before mutation begins.
+  # Test selection uses longest-prefix matching against example group
+  # descriptions in the test suite.
+  class Subject
+    attr_reader :namespace, :method_name, :method_type, :source_file,
+                :source_range, :ast_node
+
+    # @param expression [String] subject expression, e.g. "Foo::Bar#method"
+    def self.parse(expression)
+      new(expression:)
+    end
+
+    # @param namespace   [String]  fully-qualified module/class name
+    # @param method_name [String]  method name (nil for wildcard subjects)
+    # @param method_type [Symbol]  :instance or :class
+    # @param source_location [Hash] file/range metadata for the subject source
+    # The explicit keyword API matches the public call sites and keeps the
+    # metadata fields discoverable without a single options hash.
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(expression: nil, namespace: nil, method_name: nil,
+                   method_type: :instance, source_location: nil, ast_node: nil)
+      if expression
+        parse_expression(expression)
+      else
+        @namespace   = namespace
+        @method_name = method_name
+        @method_type = method_type
+      end
+      @source_file  = source_location&.fetch(:file, nil)
+      @source_range = source_location&.fetch(:range, nil)
+      @ast_node = ast_node
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Full addressable expression, e.g. "Foo::Bar#method"
+    def expression
+      sep = @method_type == :class ? "." : "#"
+      @method_name ? "#{@namespace}#{sep}#{@method_name}" : "#{@namespace}*"
+    end
+
+    def wildcard?
+      @method_name.nil?
+    end
+
+    private
+
+    def parse_expression(expr)
+      if (m = expr.match(/\A(.+?)([#.])(\w+)\z/))
+        @namespace   = m[1]
+        @method_type = m[2] == "." ? :class : :instance
+        @method_name = m[3]
+      else
+        # Wildcard: "Foo*" or "Foo::Bar*"
+        @namespace   = expr.delete_suffix("*")
+        @method_name = nil
+        @method_type = :instance
+      end
+    end
+  end
+end