evilution 0.1.0

data/lib/evilution/parallel/pool.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Parallel
+    class Pool
+      def initialize(jobs:)
+        @jobs = jobs
+      end
+
+      # Executes mutations in parallel across N worker processes.
+      #
+      # @param mutations [Array] Array of mutation objects to run
+      # @param test_command_builder [#call] Callable that receives a mutation and returns a test command callable
+      # @param timeout [Numeric] Per-mutation timeout in seconds
+      # @return [Array<Result::MutationResult>]
+      def call(mutations:, test_command_builder:, timeout:)
+        return [] if mutations.empty?
+
+        worker_count = [@jobs, mutations.size].min
+        chunks = partition(mutations, worker_count)
+
+        pipes = worker_count.times.map { IO.pipe }
+
+        pids = chunks.each_with_index.map do |chunk, index|
+          _, write_io = pipes[index]
+
+          pid = Process.fork do
+            # Close all read ends in the child; close sibling write ends too
+            pipes.each_with_index do |(r, w), i|
+              if i == index
+                r.close
+              else
+                r.close
+                w.close
+              end
+            end
+
+            results = run_chunk(chunk, test_command_builder, timeout)
+            Marshal.dump(results, write_io)
+            write_io.close
+            exit!(0)
+          end
+
+          write_io.close
+          pid
+        end
+
+        results = collect_results(pipes.map(&:first), pids)
+
+        results
+      ensure
+        # Ensure all pipes are closed even if something goes wrong
+        pipes&.each do |read_io, write_io|
+          read_io.close unless read_io.closed?
+          write_io.close unless write_io.closed?
+        end
+      end
+
+      private
+
+      attr_reader :jobs
+
+      # Distributes mutations across N chunks using round-robin.
+      # File isolation is handled by Integration::RSpec via temp directories
+      # and $LOAD_PATH, so same-file mutations can safely run in parallel.
+      def partition(mutations, n)
+        chunks = Array.new(n) { [] }
+        mutations.each_with_index { |m, i| chunks[i % n] << m }
+        chunks
+      end
+
+      # Runs a chunk of mutations sequentially inside a worker process.
+      def run_chunk(mutations, test_command_builder, timeout)
+        worker = Worker.new
+        worker.call(mutations: mutations, test_command_builder: test_command_builder, timeout: timeout)
+      end
+
+      # Reads results from all worker pipes and waits for workers to finish.
+      def collect_results(read_ios, pids)
+        results = []
+
+        read_ios.each_with_index do |read_io, _index|
+          data = read_io.read
+          read_io.close
+
+          unless data.empty?
+            chunk_results = Marshal.load(data) # rubocop:disable Security/MarshalLoad
+            results.concat(chunk_results)
+          end
+        end
+
+        pids.each { |pid| Process.wait(pid) rescue nil } # rubocop:disable Style/RescueModifier
+
+        results
+      end
+    end
+  end
+end

data/lib/evilution/parallel/worker.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Parallel
+    class Worker
+      def initialize(isolator: Isolation::Fork.new)
+        @isolator = isolator
+      end
+
+      # Runs a batch of mutations sequentially using fork isolation.
+      #
+      # @param mutations [Array<Mutation>] Mutations to execute
+      # @param test_command_builder [#call] Receives a mutation, returns a test command callable
+      # @param timeout [Numeric] Per-mutation timeout in seconds
+      # @return [Array<Result::MutationResult>]
+      def call(mutations:, test_command_builder:, timeout:)
+        mutations.map do |mutation|
+          test_command = test_command_builder.call(mutation)
+          @isolator.call(mutation: mutation, test_command: test_command, timeout: timeout)
+        end
+      end
+    end
+  end
+end

data/lib/evilution/reporter/cli.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Reporter
+    class CLI
+      SEPARATOR = "=" * 44
+
+      def call(summary)
+        lines = []
+        lines << header
+        lines << SEPARATOR
+        lines << ""
+        lines << mutations_line(summary)
+        lines << score_line(summary)
+        lines << duration_line(summary)
+
+        if summary.survived_results.any?
+          lines << ""
+          lines << "Survived mutations:"
+          summary.survived_results.each do |result|
+            lines << format_survived(result)
+          end
+        end
+
+        lines << ""
+        lines << result_line(summary)
+
+        lines.join("\n")
+      end
+
+      private
+
+      def header
+        "Evilution v#{Evilution::VERSION} — Mutation Testing Results"
+      end
+
+      def mutations_line(summary)
+        "Mutations: #{summary.total} total, #{summary.killed} killed, " \
+          "#{summary.survived} survived, #{summary.timed_out} timed out"
+      end
+
+      def score_line(summary)
+        denominator = summary.total - summary.errors
+        score_pct = format_pct(summary.score)
+        "Score: #{score_pct} (#{summary.killed}/#{denominator})"
+      end
+
+      def duration_line(summary)
+        "Duration: #{format("%.2f", summary.duration)}s"
+      end
+
+      def format_survived(result)
+        mutation = result.mutation
+        location = "#{mutation.file_path}:#{mutation.line}"
+        diff_lines = mutation.diff.split("\n").map { |l| "    #{l}" }.join("\n")
+        "  #{mutation.operator_name}: #{location}\n#{diff_lines}"
+      end
+
+      def result_line(summary)
+        min_score = 0.8
+        pass_fail = summary.success?(min_score: min_score) ? "PASS" : "FAIL"
+        score_pct = format_pct(summary.score)
+        threshold_pct = format_pct(min_score)
+        "Result: #{pass_fail} (score #{score_pct} #{pass_fail == "PASS" ? ">=" : "<"} #{threshold_pct})"
+      end
+
+      def format_pct(value)
+        format("%.2f%%", value * 100)
+      end
+    end
+  end
+end

data/lib/evilution/reporter/json.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "suggestion"
+
+module Evilution
+  module Reporter
+    class JSON
+      def initialize
+        @suggestion = Suggestion.new
+      end
+
+      def call(summary)
+        ::JSON.generate(build_report(summary))
+      end
+
+      private
+
+      def build_report(summary)
+        {
+          version: Evilution::VERSION,
+          timestamp: Time.now.iso8601,
+          summary: build_summary(summary),
+          survived: summary.survived_results.map { |r| build_mutation_detail(r) },
+          killed: summary.killed_results.map { |r| build_mutation_detail(r) },
+          timed_out: summary.results.select(&:timeout?).map { |r| build_mutation_detail(r) },
+          errors: summary.results.select(&:error?).map { |r| build_mutation_detail(r) }
+        }
+      end
+
+      def build_summary(summary)
+        {
+          total: summary.total,
+          killed: summary.killed,
+          survived: summary.survived,
+          timed_out: summary.timed_out,
+          errors: summary.errors,
+          score: summary.score.round(4),
+          duration: summary.duration.round(4)
+        }
+      end
+
+      def build_mutation_detail(result)
+        mutation = result.mutation
+        detail = {
+          operator: mutation.operator_name,
+          file: mutation.file_path,
+          line: mutation.line,
+          status: result.status.to_s,
+          duration: result.duration.round(4),
+          diff: mutation.diff
+        }
+        detail[:suggestion] = @suggestion.suggestion_for(mutation) if result.status == :survived
+        detail
+      end
+    end
+  end
+end

data/lib/evilution/reporter/suggestion.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Reporter
+    class Suggestion
+      TEMPLATES = {
+        "comparison_replacement" => "Add a test for the boundary condition where the comparison operand equals the threshold exactly",
+        "arithmetic_replacement" => "Add a test that verifies the arithmetic result, not just truthiness of the outcome",
+        "boolean_operator_replacement" => "Add a test where only one of the boolean conditions is true to distinguish && from ||",
+        "boolean_literal_replacement" => "Add a test that exercises the false/true branch explicitly",
+        "nil_replacement" => "Add a test that asserts the return value is not nil",
+        "integer_literal" => "Add a test that checks the exact numeric value, not just > 0 or truthy",
+        "float_literal" => "Add a test that checks the exact floating-point value returned",
+        "string_literal" => "Add a test that asserts the string content, not just its presence",
+        "array_literal" => "Add a test that verifies the array contents or length",
+        "hash_literal" => "Add a test that verifies the hash keys and values",
+        "symbol_literal" => "Add a test that checks the exact symbol returned",
+        "conditional_negation" => "Add tests for both the true and false branches of this conditional",
+        "conditional_branch" => "Add a test that exercises the removed branch of this conditional",
+        "statement_deletion" => "Add a test that depends on the side effect of this statement",
+        "method_body_replacement" => "Add a test that checks the method's return value or side effects",
+        "negation_insertion" => "Add a test where the predicate result matters (not just truthiness)",
+        "return_value_removal" => "Add a test that uses the return value of this method",
+        "collection_replacement" => "Add a test that checks the return value of the collection operation, not just side effects"
+      }.freeze
+
+      DEFAULT_SUGGESTION = "Add a more specific test that detects this mutation"
+
+      # Generate suggestions for survived mutations.
+      #
+      # @param summary [Result::Summary]
+      # @return [Array<Hash>] Array of { mutation:, suggestion: }
+      def call(summary)
+        summary.survived_results.map do |result|
+          {
+            mutation: result.mutation,
+            suggestion: suggestion_for(result.mutation)
+          }
+        end
+      end
+
+      # Generate a suggestion for a single mutation.
+      #
+      # @param mutation [Mutation]
+      # @return [String]
+      def suggestion_for(mutation)
+        TEMPLATES.fetch(mutation.operator_name, DEFAULT_SUGGESTION)
+      end
+    end
+  end
+end

data/lib/evilution/result/mutation_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Result
+    class MutationResult
+      STATUSES = %i[killed survived timeout error].freeze
+
+      attr_reader :mutation, :status, :duration, :killing_test
+
+      def initialize(mutation:, status:, duration: 0.0, killing_test: nil)
+        raise ArgumentError, "invalid status: #{status}" unless STATUSES.include?(status)
+
+        @mutation = mutation
+        @status = status
+        @duration = duration
+        @killing_test = killing_test
+        freeze
+      end
+
+      def killed?
+        status == :killed
+      end
+
+      def survived?
+        status == :survived
+      end
+
+      def timeout?
+        status == :timeout
+      end
+
+      def error?
+        status == :error
+      end
+    end
+  end
+end

data/lib/evilution/result/summary.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Result
+    class Summary
+      attr_reader :results, :duration
+
+      def initialize(results:, duration: 0.0)
+        @results = results
+        @duration = duration
+        freeze
+      end
+
+      def total
+        results.length
+      end
+
+      def killed
+        results.count(&:killed?)
+      end
+
+      def survived
+        results.count(&:survived?)
+      end
+
+      def timed_out
+        results.count(&:timeout?)
+      end
+
+      def errors
+        results.count(&:error?)
+      end
+
+      def score
+        denominator = total - errors
+        return 0.0 if denominator.zero?
+
+        killed.to_f / denominator
+      end
+
+      def success?(min_score: 1.0)
+        score >= min_score
+      end
+
+      def survived_results
+        results.select(&:survived?)
+      end
+
+      def killed_results
+        results.select(&:killed?)
+      end
+    end
+  end
+end

data/lib/evilution/runner.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "ast/parser"
+require_relative "mutator/registry"
+require_relative "isolation/fork"
+require_relative "parallel/pool"
+require_relative "integration/rspec"
+require_relative "reporter/json"
+require_relative "reporter/cli"
+require_relative "reporter/suggestion"
+require_relative "coverage/collector"
+require_relative "coverage/test_map"
+require_relative "diff/parser"
+require_relative "diff/file_filter"
+require_relative "result/mutation_result"
+require_relative "result/summary"
+
+module Evilution
+  class Runner
+    attr_reader :config
+
+    def initialize(config: Config.new)
+      @config = config
+      @parser = AST::Parser.new
+      @registry = Mutator::Registry.default
+      @isolator = Isolation::Fork.new
+    end
+
+    def call
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      subjects = parse_subjects
+      subjects = filter_by_diff(subjects) if config.diff?
+      mutations = generate_mutations(subjects)
+      test_map = collect_coverage if config.coverage && config.integration == :rspec
+      mutations, skipped = filter_by_coverage(mutations, test_map) if test_map
+      results = run_mutations(mutations)
+      results.concat(skipped) if skipped
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+      summary = Result::Summary.new(results: results, duration: duration)
+      output_report(summary)
+
+      summary
+    end
+
+    private
+
+    attr_reader :parser, :registry, :isolator
+
+    def parse_subjects
+      config.target_files.flat_map { |file| parser.call(file) }
+    end
+
+    def filter_by_diff(subjects)
+      diff_parser = Diff::Parser.new
+      changed_ranges = diff_parser.parse(config.diff_base)
+      Diff::FileFilter.new.filter(subjects, changed_ranges)
+    end
+
+    def generate_mutations(subjects)
+      subjects.flat_map { |subject| registry.mutations_for(subject) }
+    end
+
+    def collect_coverage
+      test_files = Dir.glob("spec/**/*_spec.rb")
+      return nil if test_files.empty?
+
+      data = Coverage::Collector.new.call(test_files: test_files)
+      Coverage::TestMap.new(data)
+    end
+
+    def filter_by_coverage(mutations, test_map)
+      covered, uncovered = mutations.partition do |m|
+        test_map.covered?(File.expand_path(m.file_path), m.line)
+      end
+
+      skipped = uncovered.map do |m|
+        Result::MutationResult.new(mutation: m, status: :survived, duration: 0.0)
+      end
+
+      [covered, skipped]
+    end
+
+    def run_mutations(mutations)
+      integration = build_integration
+
+      if config.jobs > 1 && mutations.size > 1
+        run_parallel(mutations, integration)
+      else
+        run_sequential(mutations, integration)
+      end
+    end
+
+    def run_sequential(mutations, integration)
+      mutations.map do |mutation|
+        test_command = ->(m) { integration.call(m) }
+        isolator.call(
+          mutation: mutation,
+          test_command: test_command,
+          timeout: config.timeout
+        )
+      end
+    end
+
+    def run_parallel(mutations, integration)
+      pool = Parallel::Pool.new(jobs: config.jobs)
+      test_command_builder = ->(_mutation) { ->(m) { integration.call(m) } }
+      pool.call(mutations: mutations, test_command_builder: test_command_builder, timeout: config.timeout)
+    end
+
+    def build_integration
+      case config.integration
+      when :rspec
+        Integration::RSpec.new
+      else
+        raise Error, "unknown integration: #{config.integration}"
+      end
+    end
+
+    def output_report(summary)
+      reporter = build_reporter
+      return unless reporter
+
+      output = reporter.call(summary)
+      $stdout.puts(output) unless config.quiet
+    end
+
+    def build_reporter
+      case config.format
+      when :json
+        Reporter::JSON.new
+      when :text
+        Reporter::CLI.new
+      end
+    end
+  end
+end

data/lib/evilution/subject.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Evilution
+  class Subject
+    attr_reader :name, :file_path, :line_number, :source, :node
+
+    def initialize(name:, file_path:, line_number:, source:, node:)
+      @name = name
+      @file_path = file_path
+      @line_number = line_number
+      @source = source
+      @node = node
+      freeze
+    end
+
+    def to_s
+      "#{name} (#{file_path}:#{line_number})"
+    end
+  end
+end

data/lib/evilution/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Evilution
+  VERSION = "0.1.0"
+end

data/lib/evilution.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "evilution/version"
+require_relative "evilution/config"
+require_relative "evilution/subject"
+require_relative "evilution/mutation"
+require_relative "evilution/ast/source_surgeon"
+require_relative "evilution/ast/parser"
+require_relative "evilution/mutator/base"
+require_relative "evilution/mutator/operator/comparison_replacement"
+require_relative "evilution/mutator/operator/boolean_literal_replacement"
+require_relative "evilution/mutator/operator/integer_literal"
+require_relative "evilution/mutator/operator/float_literal"
+require_relative "evilution/mutator/operator/nil_replacement"
+require_relative "evilution/mutator/operator/boolean_operator_replacement"
+require_relative "evilution/mutator/operator/arithmetic_replacement"
+require_relative "evilution/mutator/operator/string_literal"
+require_relative "evilution/mutator/operator/array_literal"
+require_relative "evilution/mutator/operator/hash_literal"
+require_relative "evilution/mutator/operator/conditional_branch"
+require_relative "evilution/mutator/operator/symbol_literal"
+require_relative "evilution/mutator/operator/conditional_negation"
+require_relative "evilution/mutator/operator/negation_insertion"
+require_relative "evilution/mutator/operator/statement_deletion"
+require_relative "evilution/mutator/operator/method_body_replacement"
+require_relative "evilution/mutator/operator/return_value_removal"
+require_relative "evilution/mutator/operator/collection_replacement"
+require_relative "evilution/mutator/registry"
+require_relative "evilution/isolation/fork"
+require_relative "evilution/parallel/worker"
+require_relative "evilution/parallel/pool"
+require_relative "evilution/diff/parser"
+require_relative "evilution/diff/file_filter"
+require_relative "evilution/integration/base"
+require_relative "evilution/integration/rspec"
+require_relative "evilution/result/mutation_result"
+require_relative "evilution/result/summary"
+require_relative "evilution/reporter/json"
+require_relative "evilution/reporter/cli"
+require_relative "evilution/reporter/suggestion"
+require_relative "evilution/coverage/collector"
+require_relative "evilution/coverage/test_map"
+require_relative "evilution/cli"
+require_relative "evilution/runner"
+
+module Evilution
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class ParseError < Error; end
+  class IsolationError < Error; end
+end

data/sig/evilution.rbs

@@ -0,0 +1,4 @@
+module Evilution
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end