evilution 0.1.0

data/lib/evilution/cli.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "version"
+require_relative "config"
+require_relative "runner"
+
+module Evilution
+  class CLI
+    def initialize(argv)
+      @options = {}
+      @command = :run
+      argv = argv.dup
+
+      case argv.first
+      when "version"
+        @command = :version
+        argv.shift
+      when "init"
+        @command = :init
+        argv.shift
+      when "run"
+        argv.shift
+      end
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: evilution [command] [options] [files...]"
+
+        opts.on("-j", "--jobs N", Integer, "Number of parallel workers") { |n| @options[:jobs] = n }
+        opts.on("-t", "--timeout N", Integer, "Per-mutation timeout in seconds") { |n| @options[:timeout] = n }
+        opts.on("-f", "--format FORMAT", "Output format: text, json") { |f| @options[:format] = f.to_sym }
+        opts.on("--diff BASE", "Only mutate code changed since BASE") { |b| @options[:diff_base] = b }
+        opts.on("--min-score FLOAT", Float, "Minimum mutation score to pass") { |s| @options[:min_score] = s }
+        opts.on("--no-coverage", "Disable coverage-based filtering of uncovered mutations") { @options[:coverage] = false }
+        opts.on("-v", "--verbose", "Verbose output") { @options[:verbose] = true }
+        opts.on("-q", "--quiet", "Suppress output") { @options[:quiet] = true }
+      end
+
+      @files = parser.parse!(argv)
+    end
+
+    def call
+      case @command
+      when :version
+        $stdout.puts(VERSION)
+        0
+      when :init
+        run_init
+      when :run
+        run_mutations
+      end
+    end
+
+    private
+
+    def run_init
+      path = ".evilution.yml"
+      if File.exist?(path)
+        warn("#{path} already exists")
+        return 1
+      end
+
+      File.write(path, Config.default_template)
+      $stdout.puts("Created #{path}")
+      0
+    end
+
+    def run_mutations
+      config = Config.new(**@options, target_files: @files)
+      runner = Runner.new(config: config)
+      summary = runner.call
+      summary.success?(min_score: config.min_score) ? 0 : 1
+    rescue Error => e
+      warn("Error: #{e.message}")
+      2
+    end
+  end
+end

data/lib/evilution/config.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Evilution
+  class Config
+    CONFIG_FILES = %w[.evilution.yml config/evilution.yml].freeze
+
+    DEFAULTS = {
+      jobs: nil,
+      timeout: 10,
+      format: :text,
+      diff_base: nil,
+      target: nil,
+      min_score: 0.0,
+      integration: :rspec,
+      coverage: true,
+      verbose: false,
+      quiet: false
+    }.freeze
+
+    attr_reader :target_files, :jobs, :timeout, :format, :diff_base,
+                :target, :min_score, :integration, :coverage, :verbose, :quiet
+
+    def initialize(**options)
+      file_options = options.delete(:skip_config_file) ? {} : load_config_file
+      merged = DEFAULTS.merge(file_options).merge(options)
+      @target_files = Array(merged[:target_files])
+      @jobs = merged[:jobs] || default_jobs
+      @timeout = merged[:timeout]
+      @format = merged[:format].to_sym
+      @diff_base = merged[:diff_base]
+      @target = merged[:target]
+      @min_score = merged[:min_score].to_f
+      @integration = merged[:integration].to_sym
+      @coverage = merged[:coverage]
+      @verbose = merged[:verbose]
+      @quiet = merged[:quiet]
+      freeze
+    end
+
+    def json?
+      format == :json
+    end
+
+    def text?
+      format == :text
+    end
+
+    def diff?
+      !diff_base.nil?
+    end
+
+    # Generates a default config file template.
+    def self.default_template
+      <<~YAML
+        # Evilution configuration
+        # See: https://github.com/marinazzio/evilution
+
+        # Number of parallel workers (default: number of CPU cores)
+        # jobs: 4
+
+        # Per-mutation timeout in seconds (default: 10)
+        # timeout: 10
+
+        # Output format: text or json (default: text)
+        # format: text
+
+        # Minimum mutation score to pass (0.0 to 1.0, default: 0.0)
+        # min_score: 0.0
+
+        # Test integration: rspec (default: rspec)
+        # integration: rspec
+
+        # Skip mutations on uncovered lines (default: true)
+        # coverage: true
+      YAML
+    end
+
+    private
+
+    def load_config_file
+      CONFIG_FILES.each do |path|
+        next unless File.exist?(path)
+
+        data = YAML.safe_load_file(path, symbolize_names: true)
+        return data.is_a?(Hash) ? data : {}
+      end
+
+      {}
+    end
+
+    def default_jobs
+      require "etc"
+      Etc.nprocessors
+    end
+  end
+end

data/lib/evilution/coverage/collector.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "coverage"
+require "stringio"
+
+module Evilution
+  module Coverage
+    class Collector
+      def call(test_files:)
+        read_io, write_io = IO.pipe
+
+        pid = ::Process.fork do
+          read_io.close
+          result = collect_coverage(test_files)
+          Marshal.dump(result, write_io)
+          write_io.close
+          exit!(0)
+        end
+
+        write_io.close
+        data = read_io.read
+        read_io.close
+        ::Process.wait(pid)
+
+        Marshal.load(data) # rubocop:disable Security/MarshalLoad
+      ensure
+        read_io&.close
+        write_io&.close
+      end
+
+      private
+
+      def collect_coverage(test_files)
+        ::Coverage.start
+        return ::Coverage.result if test_files.empty?
+
+        require "rspec/core"
+        ::RSpec.reset
+        ::RSpec::Core::Runner.run(
+          ["--format", "progress", "--no-color", "--order", "defined", *test_files],
+          StringIO.new, StringIO.new
+        )
+        ::Coverage.result
+      end
+    end
+  end
+end

data/lib/evilution/coverage/test_map.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Coverage
+    class TestMap
+      def initialize(coverage_data)
+        @coverage_data = coverage_data
+      end
+
+      # Returns true if the given source line was executed during tests.
+      # file_path should be an absolute path matching coverage data keys.
+      # line is 1-based (editor line numbers).
+      def covered?(file_path, line)
+        line_data = @coverage_data[file_path]
+        return false unless line_data
+
+        index = line - 1
+        return false if index.negative? || index >= line_data.length
+
+        count = line_data[index]
+        !count.nil? && count.positive?
+      end
+    end
+  end
+end

data/lib/evilution/diff/file_filter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Diff
+    class FileFilter
+      # Filters subjects to only those whose methods overlap with changed lines.
+      #
+      # @param subjects [Array<Subject>] All extracted subjects
+      # @param changed_ranges [Array<Hash>] Output from Diff::Parser#parse
+      # @return [Array<Subject>] Subjects overlapping with changes
+      def filter(subjects, changed_ranges)
+        lookup = build_lookup(changed_ranges)
+
+        subjects.select do |subject|
+          ranges = lookup[subject.file_path]
+          next false unless ranges
+
+          ranges.any? { |range| range.cover?(subject.line_number) }
+        end
+      end
+
+      private
+
+      def build_lookup(changed_ranges)
+        changed_ranges.to_h { [_1[:file], _1[:lines]] }
+      end
+    end
+  end
+end

data/lib/evilution/diff/parser.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Diff
+    class Parser
+      # Parses git diff output to extract changed file paths and line ranges.
+      #
+      # @param diff_base [String] Git ref to diff against (e.g., "HEAD~1", "main")
+      # @return [Array<Hash>] Array of { file: String, lines: Array<Range> }
+      def parse(diff_base)
+        output = run_git_diff(diff_base)
+        parse_diff_output(output)
+      end
+
+      private
+
+      def run_git_diff(diff_base)
+        `git diff --unified=0 #{diff_base}..HEAD -- '*.rb' 2>/dev/null`
+      end
+
+      def parse_diff_output(output)
+        result = {}
+        current_file = nil
+
+        output.each_line do |line|
+          case line
+          when %r{^diff --git a/.+ b/(.+)$}
+            current_file = Regexp.last_match(1)
+          when /^@@\s+-\d+(?:,\d+)?\s+\+(\d+)(?:,(\d+))?\s+@@/
+            next unless current_file
+
+            start_line = Regexp.last_match(1).to_i
+            count = (Regexp.last_match(2) || "1").to_i
+
+            next if count.zero? # Pure deletion, no new lines
+
+            end_line = start_line + count - 1
+            result[current_file] ||= []
+            result[current_file] << (start_line..end_line)
+          end
+        end
+
+        result.map { |file, lines| { file: file, lines: lines } }
+      end
+    end
+  end
+end

data/lib/evilution/integration/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Integration
+    class Base
+      def call(mutation)
+        raise NotImplementedError, "#{self.class}#call must be implemented"
+      end
+    end
+  end
+end

data/lib/evilution/integration/rspec.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "stringio"
+require "tmpdir"
+require_relative "base"
+
+module Evilution
+  module Integration
+    class RSpec < Base
+      def initialize(test_files: nil)
+        @test_files = test_files
+        @rspec_loaded = false
+        super()
+      end
+
+      def call(mutation)
+        @original_content = nil
+        @temp_dir = nil
+        @lock_file = nil
+        ensure_rspec_loaded
+        apply_mutation(mutation)
+        run_rspec(mutation)
+      ensure
+        restore_original(mutation)
+      end
+
+      private
+
+      attr_reader :test_files
+
+      def ensure_rspec_loaded
+        return if @rspec_loaded
+
+        require "rspec/core"
+        @rspec_loaded = true
+      rescue LoadError => e
+        raise Evilution::Error, "rspec-core is required but not available: #{e.message}"
+      end
+
+      def apply_mutation(mutation)
+        subpath = resolve_require_subpath(mutation.file_path)
+
+        if subpath
+          @temp_dir = Dir.mktmpdir("evilution")
+          dest = File.join(@temp_dir, subpath)
+          FileUtils.mkdir_p(File.dirname(dest))
+          File.write(dest, mutation.mutated_source)
+          $LOAD_PATH.unshift(@temp_dir)
+        else
+          # Fallback: direct write when file isn't under any $LOAD_PATH entry.
+          # Acquire an exclusive lock to prevent concurrent workers from corrupting the file.
+          lock_path = File.join(Dir.tmpdir, "evilution-#{File.expand_path(mutation.file_path).hash.abs}.lock")
+          @lock_file = File.open(lock_path, File::CREAT | File::RDWR) # rubocop:disable Style/FileOpen
+          @lock_file.flock(File::LOCK_EX)
+          @original_content = File.read(mutation.file_path)
+          File.write(mutation.file_path, mutation.mutated_source)
+        end
+      end
+
+      def restore_original(mutation)
+        if @temp_dir
+          $LOAD_PATH.delete(@temp_dir)
+          $LOADED_FEATURES.reject! { |f| f.start_with?(@temp_dir) }
+          FileUtils.rm_rf(@temp_dir)
+          @temp_dir = nil
+        elsif @original_content
+          File.write(mutation.file_path, @original_content)
+          @lock_file&.flock(File::LOCK_UN)
+          @lock_file&.close
+          @lock_file = nil
+        end
+      end
+
+      def resolve_require_subpath(file_path)
+        absolute = File.expand_path(file_path)
+
+        $LOAD_PATH.each do |entry|
+          dir = File.expand_path(entry)
+          prefix = dir.end_with?("/") ? dir : "#{dir}/"
+          next unless absolute.start_with?(prefix)
+
+          return absolute.delete_prefix(prefix)
+        end
+
+        nil
+      end
+
+      def run_rspec(mutation)
+        # When used via the Runner with Isolation::Fork, each mutation is executed
+        # in its own forked child process, so RSpec state (loaded example groups,
+        # world, configuration) cannot accumulate across mutation runs — the child
+        # process exits after each run.
+        #
+        # This integration can also be invoked directly (e.g. in specs or alternative
+        # runners) without fork isolation. RSpec.reset is called here as
+        # defense-in-depth to clear RSpec state between mutation runs in those cases.
+        ::RSpec.reset
+
+        out = StringIO.new
+        err = StringIO.new
+        args = build_args(mutation)
+
+        status = ::RSpec::Core::Runner.run(args, out, err)
+
+        { passed: status.zero? }
+      rescue StandardError => e
+        { passed: false, error: e.message }
+      end
+
+      def build_args(mutation)
+        files = test_files || detect_test_files(mutation)
+        ["--format", "progress", "--no-color", "--order", "defined", *files]
+      end
+
+      def detect_test_files(mutation)
+        # Convention: lib/foo/bar.rb -> spec/foo/bar_spec.rb
+        candidates = spec_file_candidates(mutation.file_path)
+        found = candidates.select { |f| File.exist?(f) }
+        return found unless found.empty?
+
+        # Fallback: find spec/ directory relative to the mutation's project root
+        fallback = fallback_spec_dir(mutation.file_path)
+        return [fallback] if fallback
+
+        []
+      end
+
+      def fallback_spec_dir(source_path)
+        expanded = File.expand_path(source_path)
+
+        # Derive spec/ from mutation's project, not CWD
+        if expanded.include?("/lib/")
+          project_root = expanded.split(%r{/lib/}, 2).first
+          spec_dir = File.join(project_root, "spec")
+          return spec_dir if Dir.exist?(spec_dir)
+        end
+
+        # Walk up from the file's directory looking for spec/
+        dir = File.dirname(expanded)
+        loop do
+          spec_dir = File.join(dir, "spec")
+          return spec_dir if Dir.exist?(spec_dir)
+
+          parent = File.dirname(dir)
+          break if parent == dir
+
+          dir = parent
+        end
+
+        nil
+      end
+
+      def spec_file_candidates(source_path)
+        candidates = []
+
+        if source_path.start_with?("lib/")
+          # lib/foo/bar.rb -> spec/foo/bar_spec.rb
+          relative = source_path.sub(%r{^lib/}, "")
+          spec_name = relative.sub(/\.rb$/, "_spec.rb")
+          candidates << File.join("spec", spec_name)
+          candidates << File.join("spec", "unit", spec_name)
+        elsif source_path.include?("/lib/")
+          # /absolute/path/lib/foo/bar.rb -> /absolute/path/spec/foo/bar_spec.rb
+          prefix, relative = source_path.split(%r{/lib/}, 2)
+          spec_name = relative.sub(/\.rb$/, "_spec.rb")
+          candidates << File.join(prefix, "spec", spec_name)
+          candidates << File.join(prefix, "spec", "unit", spec_name)
+        end
+
+        # Same directory: foo/bar.rb -> foo/bar_spec.rb
+        sibling_spec = source_path.sub(/\.rb$/, "_spec.rb")
+        candidates << sibling_spec
+
+        # Subdirectory spec/ variant: foo/bar.rb -> foo/spec/bar_spec.rb
+        dir = File.dirname(source_path)
+        base = File.basename(source_path, ".rb")
+        candidates << File.join(dir, "spec", "#{base}_spec.rb")
+
+        candidates.uniq
+      end
+    end
+  end
+end

data/lib/evilution/isolation/fork.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Evilution
+  module Isolation
+    class Fork
+      def call(mutation:, test_command:, timeout:)
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        read_io, write_io = IO.pipe
+
+        pid = ::Process.fork do
+          read_io.close
+          result = execute_in_child(mutation, test_command)
+          Marshal.dump(result, write_io)
+          write_io.close
+          exit!(result[:passed] ? 0 : 1)
+        end
+
+        write_io.close
+        result = wait_for_result(pid, read_io, timeout)
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+        build_mutation_result(mutation, result, duration)
+      ensure
+        read_io&.close
+        write_io&.close
+      end
+
+      private
+
+      def execute_in_child(mutation, test_command)
+        test_command.call(mutation)
+      rescue StandardError => e
+        { passed: false, error: e.message }
+      end
+
+      def wait_for_result(pid, read_io, timeout)
+        if read_io.wait_readable(timeout)
+          data = read_io.read
+          ::Process.wait(pid)
+          return { timeout: false }.merge(Marshal.load(data)) unless data.empty? # rubocop:disable Security/MarshalLoad
+
+          ::Process.wait(pid) rescue nil # rubocop:disable Style/RescueModifier
+          { timeout: false, passed: false, error: "empty result from child" }
+        else
+          ::Process.kill("KILL", pid) rescue nil # rubocop:disable Style/RescueModifier
+          ::Process.wait(pid) rescue nil # rubocop:disable Style/RescueModifier
+          { timeout: true }
+        end
+      end
+
+      def build_mutation_result(mutation, result, duration)
+        status = if result[:timeout]
+                   :timeout
+                 elsif result[:error]
+                   :error
+                 elsif result[:passed]
+                   :survived
+                 else
+                   :killed
+                 end
+
+        Result::MutationResult.new(
+          mutation: mutation,
+          status: status,
+          duration: duration
+        )
+      end
+    end
+  end
+end

data/lib/evilution/mutation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "diff/lcs"
+require "diff/lcs/hunk"
+
+module Evilution
+  class Mutation
+    attr_reader :subject, :operator_name, :original_source,
+                :mutated_source, :file_path, :line, :column
+
+    def initialize(subject:, operator_name:, original_source:, mutated_source:, file_path:, line:, column: 0)
+      @subject = subject
+      @operator_name = operator_name
+      @original_source = original_source
+      @mutated_source = mutated_source
+      @file_path = file_path
+      @line = line
+      @column = column
+      freeze
+    end
+
+    def diff
+      original_lines = original_source.lines
+      mutated_lines = mutated_source.lines
+      diffs = ::Diff::LCS.diff(original_lines, mutated_lines)
+
+      return "" if diffs.empty?
+
+      result = []
+      diffs.flatten(1).each do |change|
+        case change.action
+        when "-"
+          result << "- #{change.element.chomp}"
+        when "+"
+          result << "+ #{change.element.chomp}"
+        end
+      end
+      result.join("\n")
+    end
+
+    def to_s
+      "#{operator_name}: #{file_path}:#{line}"
+    end
+  end
+end

data/lib/evilution/mutator/base.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Evilution
+  module Mutator
+    class Base < Prism::Visitor
+      attr_reader :mutations
+
+      def initialize
+        @mutations = []
+        @subject = nil
+        @file_source = nil
+      end
+
+      def call(subject)
+        @subject = subject
+        @file_source = File.read(subject.file_path)
+        @mutations = []
+        visit(subject.node)
+        @mutations
+      end
+
+      private
+
+      def add_mutation(offset:, length:, replacement:, node:)
+        mutated_source = AST::SourceSurgeon.apply(
+          @file_source,
+          offset: offset,
+          length: length,
+          replacement: replacement
+        )
+
+        @mutations << Mutation.new(
+          subject: @subject,
+          operator_name: self.class.operator_name,
+          original_source: @file_source,
+          mutated_source: mutated_source,
+          file_path: @subject.file_path,
+          line: node.location.start_line,
+          column: node.location.start_column
+        )
+      end
+
+      def self.operator_name
+        class_name = name || "anonymous"
+        class_name.split("::").last
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                  .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                  .downcase
+      end
+    end
+  end
+end