evilution 0.23.0 → 0.25.0

data/lib/evilution/cli/parser.rb

@@ -1,28 +1,8 @@
 # frozen_string_literal: true
 
-require "optparse"
-require_relative "../version"
 require_relative "parsed_args"
 
 class Evilution::CLI::Parser
-  SIMPLE_COMMANDS = {
-    "version" => :version,
-    "init" => :init,
-    "mcp" => :mcp,
-    "subjects" => :subjects
-  }.freeze
-
-  SESSION_SUBCOMMANDS = {
-    "list" => :session_list,
-    "show" => :session_show,
-    "diff" => :session_diff,
-    "gc" => :session_gc
-  }.freeze
-
-  TESTS_SUBCOMMANDS = { "list" => :tests_list }.freeze
-  ENVIRONMENT_SUBCOMMANDS = { "show" => :environment_show }.freeze
-  UTIL_SUBCOMMANDS = { "mutation" => :util_mutation }.freeze
-
   def initialize(argv, stdin: $stdin)
     @argv = argv.dup
     @stdin = stdin
@@ -39,76 +19,19 @@ class Evilution::CLI::Parser
     return build_parsed_args if @command == :parse_error
 
     preprocess_flags
-    remaining = build_option_parser.parse!(@argv)
-    @files, @line_ranges = parse_file_args(remaining)
+    remaining = OptionsBuilder.build(@options).parse!(@argv)
+    @files, @line_ranges = FileArgs.parse(remaining)
     read_stdin_files if @options.delete(:stdin) && %i[run subjects].include?(@command)
     build_parsed_args
   end
 
   private
 
-  def read_stdin_files
-    if @files.any?
-      @stdin_error = "--stdin cannot be combined with positional file arguments"
-      return
-    end
-
-    lines = []
-    @stdin.each_line do |line|
-      line = line.strip
-      lines << line unless line.empty?
-    end
-    stdin_files, stdin_ranges = parse_file_args(lines)
-    @files = stdin_files
-    @line_ranges = @line_ranges.merge(stdin_ranges)
-  end
-
-  def build_parsed_args
-    Evilution::CLI::ParsedArgs.new(
-      command: @command,
-      options: @options,
-      files: @files,
-      line_ranges: @line_ranges,
-      stdin_error: @stdin_error,
-      parse_error: @parse_error
-    )
-  end
-
   def extract_command
-    first = @argv.first
-    if SIMPLE_COMMANDS.key?(first)
-      @command = SIMPLE_COMMANDS[first]
-      @argv.shift
-    elsif first == "run"
-      @argv.shift
-    elsif first == "session"
-      @argv.shift
-      extract_subcommand(SESSION_SUBCOMMANDS, "session", "list, show, diff, gc")
-    elsif first == "tests"
-      @argv.shift
-      extract_subcommand(TESTS_SUBCOMMANDS, "tests", "list")
-    elsif first == "environment"
-      @argv.shift
-      extract_subcommand(ENVIRONMENT_SUBCOMMANDS, "environment", "show")
-    elsif first == "util"
-      @argv.shift
-      extract_subcommand(UTIL_SUBCOMMANDS, "util", "mutation")
-    end
-  end
-
-  def extract_subcommand(table, family, available)
-    sub = @argv.first
-    if table.key?(sub)
-      @command = table[sub]
-      @argv.shift
-    elsif sub.nil?
-      @command = :parse_error
-      @parse_error = "Missing #{family} subcommand. Available subcommands: #{available}"
-    else
-      @command = :parse_error
-      @parse_error = "Unknown #{family} subcommand: #{sub}. Available subcommands: #{available}"
-      @argv.shift
-    end
+    result = CommandExtractor.call(@argv)
+    @command = result.command
+    @argv = result.remaining_argv
+    @parse_error = result.parse_error
   end
 
   def preprocess_flags
@@ -137,121 +60,29 @@ class Evilution::CLI::Parser
     @argv = result
   end
 
-  def build_option_parser
-    OptionParser.new do |opts|
-      opts.banner = "Usage: evilution [command] [options] [files...]"
-      opts.version = Evilution::VERSION
-      add_separators(opts)
-      add_options(opts)
-    end
-  end
-
-  def add_separators(opts)
-    opts.separator ""
-    opts.separator "Line-range targeting: lib/foo.rb:15-30, lib/foo.rb:15, lib/foo.rb:15-"
-    opts.separator ""
-    opts.separator "Commands: run (default), init, session {list,show,diff,gc}, subjects, tests {list},"
-    opts.separator "         util {mutation}, environment {show}, mcp, version"
-    opts.separator ""
-    opts.separator "Options:"
-  end
-
-  def add_options(opts)
-    add_core_options(opts)
-    add_filter_options(opts)
-    add_flag_options(opts)
-    add_session_options(opts)
-  end
-
-  def add_core_options(opts)
-    opts.on("-j", "--jobs N", Integer, "Number of parallel workers (default: 1)") { |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, html") { |f| @options[:format] = f.to_sym }
-  end
-
-  def add_filter_options(opts)
-    opts.on("--min-score FLOAT", Float, "Minimum mutation score to pass") { |s| @options[:min_score] = s }
-    opts.on("--spec FILES", Array, "Spec files to run (comma-separated)") { |f| @options[:spec_files] = f }
-    opts.on("--spec-dir DIR", "Include all specs in DIR") { |d| expand_spec_dir(d) }
-    opts.on("--target EXPR",
-            "Filter: method (Foo#bar), type (Foo#/Foo.), namespace (Foo*),",
-            "class (Foo), glob (source:**/*.rb), hierarchy (descendants:Foo)") do |m|
-      @options[:target] = m
-    end
-  end
-
-  def add_flag_options(opts)
-    opts.on("--fail-fast", "Stop after N surviving mutants " \
-                           "(default: disabled; if provided without N, uses 1; use --fail-fast=N)") { @options[:fail_fast] ||= 1 }
-    opts.on("--no-baseline", "Skip baseline test suite check") { @options[:baseline] = false }
-    opts.on("--incremental", "Cache killed/timeout results; skip re-running them on unchanged files") { @options[:incremental] = true }
-    opts.on("--integration NAME", "Test integration: rspec, minitest (default: rspec)") { |i| @options[:integration] = i }
-    opts.on("--isolation STRATEGY", "Isolation: auto, fork, in_process (default: auto)") { |s| @options[:isolation] = s }
-    opts.on("--preload FILE", "Preload FILE in the parent process before forking " \
-                              "(default: auto-detect spec/rails_helper.rb for Rails projects)") { |f| @options[:preload] = f }
-    opts.on("--no-preload", "Disable parent-process preload even for Rails projects") { @options[:preload] = false }
-    opts.on("--stdin", "Read target file paths from stdin (one per line)") { @options[:stdin] = true }
-    opts.on("--suggest-tests", "Generate concrete test code in suggestions (RSpec or Minitest)") { @options[:suggest_tests] = true }
-    opts.on("--no-progress", "Disable progress bar") { @options[:progress] = false }
-    add_extra_flag_options(opts)
-  end
-
-  def add_extra_flag_options(opts)
-    opts.on("--skip-heredoc-literals", "Skip all string literal mutations inside heredocs") { @options[:skip_heredoc_literals] = true }
-    opts.on("--related-specs-heuristic", "Append related request/integration/feature/system specs for includes() mutations") do
-      @options[:related_specs_heuristic] = true
-    end
-    opts.on("--show-disabled", "Report mutations skipped by # evilution:disable") { @options[:show_disabled] = true }
-    opts.on("--baseline-session PATH", "Compare against a baseline session in HTML report") { |p| @options[:baseline_session] = p }
-    opts.on("--save-session", "Save session results to .evilution/results/") { @options[:save_session] = true }
-    opts.on("-e", "--eval CODE", "Evaluate code snippet (for util mutation)") { |c| @options[:eval] = c }
-    opts.on("-v", "--verbose", "Verbose output") { @options[:verbose] = true }
-    opts.on("-q", "--quiet", "Suppress output") { @options[:quiet] = true }
-  end
-
-  def add_session_options(opts)
-    opts.on("--results-dir DIR", "Session results directory") { |d| @options[:results_dir] = d }
-    opts.on("--limit N", Integer, "Show only the N most recent sessions") { |n| @options[:limit] = n }
-    opts.on("--since DATE", "Show sessions since DATE (YYYY-MM-DD)") { |d| @options[:since] = d }
-    opts.on("--older-than DURATION", "Delete sessions older than DURATION (e.g., 30d, 24h, 1w)") do |d|
-      @options[:older_than] = d
-    end
-  end
-
-  def parse_file_args(raw_args)
-    files = []
-    ranges = {}
-
-    raw_args.each do |arg|
-      file, range_str = arg.split(":", 2)
-      files << file
-      next unless range_str
-
-      ranges[file] = parse_line_range(range_str)
-    end
-
-    [files, ranges]
-  end
-
-  def parse_line_range(str)
-    if str.include?("-")
-      start_str, end_str = str.split("-", 2)
-      start_line = Integer(start_str)
-      end_line = end_str.empty? ? Float::INFINITY : Integer(end_str)
-      start_line..end_line
-    else
-      line = Integer(str)
-      line..line
-    end
-  end
-
-  def expand_spec_dir(dir)
-    unless File.directory?(dir)
-      warn("Error: #{dir} is not a directory")
+  def read_stdin_files
+    result = StdinReader.call(@stdin, existing_files: @files)
+    if result.error
+      @stdin_error = result.error
       return
     end
+    @files = result.files
+    @line_ranges = @line_ranges.merge(result.ranges)
+  end
 
-    specs = Dir.glob(File.join(dir, "**/*_spec.rb"))
-    @options[:spec_files] = Array(@options[:spec_files]) + specs
+  def build_parsed_args
+    Evilution::CLI::ParsedArgs.new(
+      command: @command,
+      options: @options,
+      files: @files,
+      line_ranges: @line_ranges,
+      stdin_error: @stdin_error,
+      parse_error: @parse_error
+    )
   end
 end
+
+require_relative "parser/command_extractor"
+require_relative "parser/file_args"
+require_relative "parser/stdin_reader"
+require_relative "parser/options_builder"

data/lib/evilution/cli/printers/compare.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../printers"
+
+class Evilution::CLI::Printers::Compare
+  SCHEMA = {
+    "shared" => %w[file line operator fp],
+    "alive_only" => %w[file line operator fp other_status]
+  }.freeze
+
+  FILE_LINE_WIDTH = 40
+  OPERATOR_WIDTH  = 22
+  FP_LENGTH       = 7
+  MUTANT_OPERATOR = "(mutant)"
+  ABSENT_STATUS   = "absent"
+
+  def initialize(buckets, format: :json)
+    @buckets = buckets
+    @format  = format || :json
+  end
+
+  def render(io)
+    case @format
+    when :json then render_json(io)
+    when :text then render_text(io)
+    else raise Evilution::Error, "unknown compare format: #{@format.inspect}"
+    end
+  end
+
+  private
+
+  def render_json(io)
+    payload = {
+      "schema" => SCHEMA,
+      "summary" => summary_hash,
+      "alive_only_against" => @buckets[:alive_only_against].map { |e| alive_entry_array(e) },
+      "alive_only_current" => @buckets[:alive_only_current].map { |e| alive_entry_array(e) },
+      "shared_alive" => @buckets[:shared_alive].map { |e| shared_entry_array(e) },
+      "shared_dead" => @buckets[:shared_dead].map { |e| shared_entry_array(e) }
+    }
+    io.puts(JSON.generate(payload))
+  end
+
+  def render_text(io)
+    io.puts("Compare results")
+    io.puts("-" * 15)
+    io.puts(summary_line)
+
+    if fully_empty?
+      io.puts("No mutations to compare.")
+      return
+    end
+
+    print_alive_block(io, :alive_only_against, "current")
+    print_alive_block(io, :alive_only_current, "against")
+    print_shared_block(io, :shared_alive)
+    print_shared_block(io, :shared_dead)
+  end
+
+  def summary_hash
+    against_count = @buckets[:alive_only_against].length
+    current_count = @buckets[:alive_only_current].length
+    {
+      "alive_only_against" => against_count,
+      "alive_only_current" => current_count,
+      "shared_alive" => @buckets[:shared_alive].length,
+      "shared_dead" => @buckets[:shared_dead].length,
+      "excluded_against" => @buckets[:excluded_against],
+      "excluded_current" => @buckets[:excluded_current],
+      "delta" => current_count - against_count
+    }
+  end
+
+  def summary_line
+    s = summary_hash
+    parts = [
+      "summary:",
+      "alive_only_against=#{s["alive_only_against"]}",
+      "alive_only_current=#{s["alive_only_current"]}",
+      "shared_alive=#{s["shared_alive"]}",
+      "shared_dead=#{s["shared_dead"]}",
+      "excluded=#{s["excluded_against"]}/#{s["excluded_current"]}",
+      "delta=#{format_delta(s["delta"])}"
+    ]
+    parts.join(" ")
+  end
+
+  def format_delta(delta)
+    return "\u00B10" if delta.zero?
+
+    format("%+d", delta)
+  end
+
+  def fully_empty?
+    @buckets[:alive_only_against].empty? &&
+      @buckets[:alive_only_current].empty? &&
+      @buckets[:shared_alive].empty? &&
+      @buckets[:shared_dead].empty? &&
+      @buckets[:excluded_against].zero? &&
+      @buckets[:excluded_current].zero?
+  end
+
+  def alive_entry_array(entry)
+    r = entry[:record]
+    peer = entry[:peer_status]
+    peer_str = peer.nil? ? ABSENT_STATUS : peer.to_s
+    [r.file_path, r.line, r.operator, r.fingerprint, peer_str]
+  end
+
+  def shared_entry_array(entry)
+    r = entry[:against]
+    [r.file_path, r.line, shared_operator(entry), r.fingerprint]
+  end
+
+  # Mutant-sourced records always have operator=nil. When comparing mutant
+  # vs evilution, prefer whichever side has an operator so the shared row
+  # stays informative.
+  def shared_operator(entry)
+    entry[:against].operator || entry[:current].operator
+  end
+
+  def print_alive_block(io, bucket_key, peer_side_label)
+    entries = @buckets[bucket_key]
+    return if entries.empty?
+
+    io.puts("")
+    io.puts("#{bucket_key} (#{entries.length}):")
+    entries.each { |entry| io.puts(format_alive_row(entry, peer_side_label)) }
+  end
+
+  def print_shared_block(io, bucket_key)
+    entries = @buckets[bucket_key]
+    return if entries.empty?
+
+    io.puts("")
+    io.puts("#{bucket_key} (#{entries.length}):")
+    entries.each { |entry| io.puts(format_shared_row(entry)) }
+  end
+
+  def format_alive_row(entry, peer_side_label)
+    r = entry[:record]
+    peer = entry[:peer_status]
+    peer_str = peer.nil? ? ABSENT_STATUS : peer.to_s
+    "  #{row_prefix(r)}  (#{peer_side_label}: #{peer_str})"
+  end
+
+  def format_shared_row(entry)
+    r = entry[:against]
+    "  #{row_prefix(r, operator: shared_operator(entry))}"
+  end
+
+  def row_prefix(record, operator: record.operator)
+    file_line = "#{record.file_path}:#{record.line}"
+    op_label  = operator || MUTANT_OPERATOR
+    fp        = record.fingerprint.to_s[0, FP_LENGTH]
+    "#{file_line.ljust(FILE_LINE_WIDTH)}#{op_label.ljust(OPERATOR_WIDTH)}#{fp}"
+  end
+end

data/lib/evilution/cli.rb

@@ -16,6 +16,7 @@ require_relative "cli/commands/session_list"
 require_relative "cli/commands/session_show"
 require_relative "cli/commands/session_diff"
 require_relative "cli/commands/session_gc"
+require_relative "cli/commands/compare"
 require_relative "cli/commands/run"
 
 class Evilution::CLI

data/lib/evilution/compare/categorizer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+require_relative "record"
+
+module Evilution::Compare::Categorizer
+  ALIVE = %i[survived].freeze
+  DEAD  = %i[killed timeout error].freeze
+  # neutral, equivalent, unresolved, unparseable are non-actionable signals
+  # — excluded from alive/dead buckets, counted in summary.
+
+  module_function
+
+  # @param against [Array<Record>] prior run (baseline)
+  # @param current [Array<Record>] current run
+  # @return [Hash] bucketed comparison result with keys:
+  #   - `:alive_only_against` => `Array<{record: Record, peer_status: Symbol|nil}>`
+  #     records that survived in against but not in current (or absent in current).
+  #     `peer_status` is the current-side record's status symbol, or `nil` when
+  #     no current-side record exists for that fingerprint.
+  #   - `:alive_only_current` => `Array<{record: Record, peer_status: Symbol|nil}>`
+  #     mirror of the above from the current side.
+  #   - `:shared_alive` => `Array<{against: Record, current: Record}>`
+  #     mutations that survived in both runs.
+  #   - `:shared_dead` => `Array<{against: Record, current: Record}>`
+  #     mutations killed/timed-out/errored in both runs.
+  #   - `:excluded_against` => `Integer`
+  #     count of against records with non-actionable statuses (neutral,
+  #     equivalent, unresolved, unparseable).
+  #   - `:excluded_current` => `Integer` mirror for the current side.
+  def call(against, current)
+    # Duplicate fingerprints within one side should not happen (Normalizer
+    # invariant). If they do, last write wins — we do not dedupe proactively.
+    against_by_fp = index_by_fingerprint(against)
+    current_by_fp = index_by_fingerprint(current)
+
+    buckets = {
+      alive_only_against: [],
+      alive_only_current: [],
+      shared_alive: [],
+      shared_dead: [],
+      excluded_against: 0,
+      excluded_current: 0
+    }
+
+    (against_by_fp.keys | current_by_fp.keys).each do |fp|
+      classify(against_by_fp[fp], current_by_fp[fp], buckets)
+    end
+
+    sort_buckets!(buckets)
+    buckets
+  end
+
+  # Dispatches one fingerprint pair into buckets.
+  # Either record may be nil (fingerprint present on only one side).
+  def classify(against_record, current_record, buckets)
+    count_excluded(against_record, current_record, buckets)
+    a_kind = kind_of(against_record)
+    c_kind = kind_of(current_record)
+
+    if a_kind == :alive && c_kind == :alive
+      buckets[:shared_alive] << { against: against_record, current: current_record }
+    elsif a_kind == :dead && c_kind == :dead
+      buckets[:shared_dead] << { against: against_record, current: current_record }
+    else
+      bucket_single_sided(against_record, current_record, a_kind, c_kind, buckets)
+    end
+    # A dead-only fingerprint (dead on one side, absent on the other) is
+    # intentionally not bucketed and not counted as excluded.
+  end
+
+  def count_excluded(against_record, current_record, buckets)
+    buckets[:excluded_against] += 1 if against_record && kind_of(against_record) == :excluded
+    buckets[:excluded_current] += 1 if current_record && kind_of(current_record) == :excluded
+  end
+
+  def bucket_single_sided(against_record, current_record, a_kind, c_kind, buckets)
+    # peer_status is the peer record's status symbol, or nil if peer absent.
+    # When the peer is excluded, its status symbol (e.g. :neutral) flows through.
+    a_peer = current_record && current_record.status
+    c_peer = against_record && against_record.status
+    buckets[:alive_only_against] << { record: against_record, peer_status: a_peer } if a_kind == :alive
+    buckets[:alive_only_current] << { record: current_record, peer_status: c_peer } if c_kind == :alive
+  end
+
+  # Returns :alive, :dead, :excluded, or nil (for nil records).
+  def kind_of(record)
+    return nil if record.nil?
+    return :alive if ALIVE.include?(record.status)
+    return :dead  if DEAD.include?(record.status)
+
+    :excluded
+  end
+
+  def sort_buckets!(buckets)
+    buckets[:alive_only_against].sort_by! { |e| sort_key(e[:record]) }
+    buckets[:alive_only_current].sort_by! { |e| sort_key(e[:record]) }
+    buckets[:shared_alive].sort_by!       { |e| sort_key(e[:against]) }
+    buckets[:shared_dead].sort_by!        { |e| sort_key(e[:against]) }
+  end
+
+  def sort_key(record)
+    [record.file_path, record.line, record.fingerprint]
+  end
+
+  def index_by_fingerprint(records)
+    records.to_h { |r| [r.fingerprint, r] }
+  end
+end

data/lib/evilution/compare/detector.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+require_relative "normalizer"
+
+module Evilution::Compare::Detector
+  module_function
+
+  def call(json)
+    raise Evilution::Compare::InvalidInput, "expected Hash, got #{json.class}" unless json.is_a?(Hash)
+
+    mutant = json.key?("subject_results")
+    evilution = json.key?("summary") && Evilution::Compare::Normalizer::EVILUTION_BUCKETS.any? { |k| json.key?(k) }
+
+    raise Evilution::Compare::InvalidInput, "ambiguous JSON shape - both mutant and evilution markers present" if mutant && evilution
+    return :mutant if mutant
+    return :evilution if evilution
+
+    raise Evilution::Compare::InvalidInput, "cannot detect tool from JSON shape"
+  end
+end

data/lib/evilution/compare/fingerprint.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../compare"
+
+module Evilution::Compare::Fingerprint
+  module_function
+
+  def extract_from_evilution_diff(diff)
+    minus = []
+    plus = []
+    diff.to_s.each_line do |line|
+      line = line.chomp
+      if line.start_with?("- ")
+        minus << line[2..]
+      elsif line.start_with?("+ ")
+        plus << line[2..]
+      end
+    end
+    { minus: minus, plus: plus }
+  end
+
+  def extract_from_mutant_diff(diff)
+    minus = []
+    plus = []
+    diff.to_s.each_line do |line|
+      line = line.chomp
+      next if line.start_with?("---", "+++", "@@")
+
+      if line.start_with?("-")
+        minus << line[1..]
+      elsif line.start_with?("+")
+        plus << line[1..]
+      end
+    end
+    { minus: minus, plus: plus }
+  end
+
+  # v1 limitation: only " and ' literals are preserved. Regex literals (/.../),
+  # heredocs, %w[], %q{} forms are treated as ordinary code — whitespace runs
+  # inside them collapse. A mutation touching whitespace inside a regex may
+  # false-match across tools.
+  # rubocop:disable Metrics/PerceivedComplexity, Style/MultipleComparison
+  def normalize_line(line)
+    out = +""
+    i = 0
+    in_literal = nil
+    last_was_space = false
+    chars = line.chars
+    while i < chars.length
+      ch = chars[i]
+      if in_literal
+        out << ch
+        if ch == "\\" && i + 1 < chars.length
+          out << chars[i + 1]
+          i += 2
+          next
+        end
+        in_literal = nil if ch == in_literal
+      elsif ch == '"' || ch == "'"
+        in_literal = ch
+        out << ch
+        last_was_space = false
+      elsif ch == " " || ch == "\t"
+        out << " " unless last_was_space || out.empty?
+        last_was_space = true
+      else
+        out << ch
+        last_was_space = false
+      end
+      i += 1
+    end
+    out.rstrip
+  end
+  # rubocop:enable Metrics/PerceivedComplexity, Style/MultipleComparison
+
+  def compute(file_path:, line:, body:)
+    minus = body[:minus].map { |l| normalize_line(l) }
+    plus  = body[:plus].map  { |l| normalize_line(l) }
+    payload = [file_path, line.to_s, minus.join("\n"), plus.join("\n")].join("\x00")
+    Digest::SHA256.hexdigest(payload)
+  end
+end