evilution 0.22.7 → 0.23.0

data/lib/evilution/cli/parser.rb

@@ -0,0 +1,257 @@
+# 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
+    @options = {}
+    @files = []
+    @line_ranges = {}
+    @command = :run
+    @parse_error = nil
+    @stdin_error = nil
+  end
+
+  def parse
+    extract_command
+    return build_parsed_args if @command == :parse_error
+
+    preprocess_flags
+    remaining = build_option_parser.parse!(@argv)
+    @files, @line_ranges = parse_file_args(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
+  end
+
+  def preprocess_flags
+    result = []
+    i = 0
+    while i < @argv.length
+      arg = @argv[i]
+      if arg == "--fail-fast"
+        next_arg = @argv[i + 1]
+
+        if next_arg && next_arg.match?(/\A-?\d+\z/)
+          @options[:fail_fast] = next_arg
+          i += 2
+        else
+          result << arg
+          i += 1
+        end
+      elsif arg.start_with?("--fail-fast=")
+        @options[:fail_fast] = arg.delete_prefix("--fail-fast=")
+        i += 1
+      else
+        result << arg
+        i += 1
+      end
+    end
+    @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")
+      return
+    end
+
+    specs = Dir.glob(File.join(dir, "**/*_spec.rb"))
+    @options[:spec_files] = Array(@options[:spec_files]) + specs
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../printers"
+
+class Evilution::CLI::Printers::Environment
+  def initialize(config, config_file:)
+    @config = config
+    @config_file = config_file
+  end
+
+  def render(io)
+    lines = header_lines
+    lines.concat(settings_lines)
+    io.puts(lines.join("\n"))
+  end
+
+  private
+
+  def header_lines
+    [
+      "Evilution Environment",
+      ("=" * 30),
+      "",
+      "evilution: #{Evilution::VERSION}",
+      "ruby: #{RUBY_VERSION}",
+      "config_file: #{@config_file || "(none)"}",
+      "",
+      "Settings:"
+    ]
+  end
+
+  def settings_lines
+    [
+      "  timeout: #{@config.timeout}",
+      "  format: #{@config.format}",
+      "  integration: #{@config.integration}",
+      "  jobs: #{@config.jobs}",
+      "  isolation: #{@config.isolation}",
+      "  baseline: #{@config.baseline}",
+      "  incremental: #{@config.incremental}",
+      "  verbose: #{@config.verbose}",
+      "  quiet: #{@config.quiet}",
+      "  progress: #{@config.progress}",
+      "  fail_fast: #{@config.fail_fast || "(disabled)"}",
+      "  min_score: #{@config.min_score}",
+      "  suggest_tests: #{@config.suggest_tests}",
+      "  save_session: #{@config.save_session}",
+      "  target: #{@config.target || "(all files)"}",
+      "  skip_heredoc_literals: #{@config.skip_heredoc_literals}",
+      "  ignore_patterns: #{@config.ignore_patterns.empty? ? "(none)" : @config.ignore_patterns.inspect}"
+    ]
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../printers"
+
+class Evilution::CLI::Printers::SessionDetail
+  def initialize(data, format:)
+    @data = data
+    @format = format
+  end
+
+  def render(io)
+    @format == :json ? render_json(io) : render_text(io)
+  end
+
+  private
+
+  def render_json(io)
+    io.puts(JSON.pretty_generate(@data))
+  end
+
+  def render_text(io)
+    print_header(io, @data)
+    print_summary(io, @data["summary"])
+    print_survived(io, @data["survived"] || [])
+  end
+
+  def print_header(io, data)
+    io.puts("Session: #{data["timestamp"]}")
+    io.puts("Version: #{data["version"]}")
+    print_git_context(io, data["git"])
+  end
+
+  def print_git_context(io, git)
+    return unless git.is_a?(Hash)
+
+    branch = git["branch"]
+    sha = git["sha"]
+    return if branch.to_s.empty? && sha.to_s.empty?
+
+    io.puts("Git:     #{branch} (#{sha})")
+  end
+
+  def print_summary(io, summary)
+    io.puts("")
+    io.puts(
+      format(
+        "Score: %<score>.2f%%  Total: %<total>d  Killed: %<killed>d  Survived: %<surv>d  " \
+        "Timed out: %<to>d  Errors: %<err>d  Duration: %<dur>.1fs",
+        score: summary["score"] * 100, total: summary["total"], killed: summary["killed"],
+        surv: summary["survived"], to: summary["timed_out"], err: summary["errors"],
+        dur: summary["duration"]
+      )
+    )
+  end
+
+  def print_survived(io, survived)
+    io.puts("")
+    if survived.empty?
+      io.puts("No survived mutations")
+    else
+      io.puts("Survived mutations (#{survived.length}):")
+      survived.each_with_index { |m, i| print_mutation_detail(io, m, i + 1) }
+    end
+  end
+
+  def print_mutation_detail(io, mutation, index)
+    io.puts("")
+    io.puts("  #{index}. #{mutation["operator"]} — #{mutation["file"]}:#{mutation["line"]}")
+    io.puts("     Subject: #{mutation["subject"]}")
+    return unless mutation["diff"]
+
+    io.puts("     Diff:")
+    mutation["diff"].each_line { |line| io.puts("       #{line.chomp}") }
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../printers"
+
+class Evilution::CLI::Printers::SessionDiff
+  def initialize(result, format:)
+    @result = result
+    @format = format
+  end
+
+  def render(io)
+    @format == :json ? render_json(io) : render_text(io)
+  end
+
+  private
+
+  def render_json(io)
+    io.puts(JSON.pretty_generate(@result.to_h))
+  end
+
+  def render_text(io)
+    print_summary(io, @result.summary)
+    print_section(io, "Fixed (survived \u2192 killed)", @result.fixed, "\e[32m")
+    print_section(io, "New survivors (killed \u2192 survived)", @result.new_survivors, "\e[31m")
+    print_section(io, "Persistent survivors", @result.persistent, "\e[33m")
+
+    return unless @result.fixed.empty? && @result.new_survivors.empty? && @result.persistent.empty?
+
+    io.puts("")
+    io.puts("No mutation changes between sessions")
+  end
+
+  def print_summary(io, summary)
+    delta_str = format("%+.2f%%", summary.score_delta * 100)
+    io.puts("Session Diff")
+    io.puts("=" * 40)
+    io.puts(format("Base score:  %<score>6.2f%%  (%<killed>d/%<total>d killed)",
+                   score: summary.base_score * 100, killed: summary.base_killed,
+                   total: summary.base_total))
+    io.puts(format("Head score:  %<score>6.2f%%  (%<killed>d/%<total>d killed)",
+                   score: summary.head_score * 100, killed: summary.head_killed,
+                   total: summary.head_total))
+    io.puts("Delta:       #{delta_str}")
+  end
+
+  def print_section(io, title, mutations, color)
+    return if mutations.empty?
+
+    reset = "\e[0m"
+    io.puts("")
+    io.puts("#{color}#{title} (#{mutations.length}):#{reset}")
+    mutations.each do |m|
+      io.puts("  #{m["operator"]} \u2014 #{m["file"]}:#{m["line"]}  #{m["subject"]}")
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../printers"
+
+class Evilution::CLI::Printers::SessionList
+  def initialize(sessions, format:)
+    @sessions = sessions
+    @format = format
+  end
+
+  def render(io)
+    @format == :json ? render_json(io) : render_text(io)
+  end
+
+  private
+
+  def render_json(io)
+    io.puts(JSON.pretty_generate(@sessions.map { |s| session_to_hash(s) }))
+  end
+
+  def render_text(io)
+    header = "Timestamp                       Total Killed  Surv.    Score Duration"
+    io.puts(header)
+    io.puts("-" * header.length)
+    @sessions.each { |s| io.puts(format_row(s)) }
+  end
+
+  def format_row(session)
+    format(
+      "%-30<ts>s %6<total>d %6<killed>d %6<surv>d %7.2<score>f%% %7.1<dur>fs",
+      ts: session[:timestamp], total: session[:total], killed: session[:killed],
+      surv: session[:survived], score: session[:score] * 100, dur: session[:duration]
+    )
+  end
+
+  def session_to_hash(session)
+    {
+      "timestamp" => session[:timestamp],
+      "total" => session[:total],
+      "killed" => session[:killed],
+      "survived" => session[:survived],
+      "score" => session[:score],
+      "duration" => session[:duration],
+      "file" => session[:file]
+    }
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../printers"
+
+class Evilution::CLI::Printers::Subjects
+  def initialize(entries, total_mutations:)
+    @entries = entries
+    @total_mutations = total_mutations
+  end
+
+  def render(io)
+    @entries.each { |entry| io.puts(format_entry(entry)) }
+    io.puts("")
+    io.puts(summary_line)
+  end
+
+  private
+
+  def format_entry(entry)
+    "  #{entry[:name]}  #{entry[:file_path]}:#{entry[:line_number]}  (#{mutation_label(entry[:mutation_count])})"
+  end
+
+  def mutation_label(count)
+    pluralize(count, "mutation", "mutations")
+  end
+
+  def summary_line
+    "#{pluralize(@entries.length, "subject", "subjects")}, " \
+      "#{pluralize(@total_mutations, "mutation", "mutations")}"
+  end
+
+  def pluralize(count, singular, plural)
+    "#{count} #{count == 1 ? singular : plural}"
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../printers"
+
+class Evilution::CLI::Printers::TestsList
+  def initialize(mode:, specs: nil, entries: nil)
+    @mode = mode
+    @specs = specs
+    @entries = entries
+  end
+
+  def render(io)
+    case @mode
+    when :explicit then render_explicit(io)
+    when :resolved then render_resolved(io)
+    end
+  end
+
+  private
+
+  def render_explicit(io)
+    @specs.each { |f| io.puts("  #{f}") }
+    io.puts("")
+    io.puts(@specs.length == 1 ? "1 spec file" : "#{@specs.length} spec files")
+  end
+
+  def render_resolved(io)
+    unique_specs = []
+    @entries.each do |entry|
+      source = entry[:source]
+      spec = entry[:spec]
+      if spec
+        unique_specs << spec
+        io.puts("  #{spec}  (#{source})")
+      else
+        io.puts("  #{source}  (no spec found)")
+      end
+    end
+
+    unique_specs.uniq!
+    io.puts("")
+    spec_label = unique_specs.length == 1 ? "1 spec file" : "#{unique_specs.length} spec files"
+    io.puts("#{@entries.length} source files, #{spec_label}")
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../printers"
+
+class Evilution::CLI::Printers::UtilMutation
+  def initialize(mutations, format:)
+    @mutations = mutations
+    @format = format
+  end
+
+  def render(io)
+    @format == :json ? render_json(io) : render_text(io)
+  end
+
+  private
+
+  def render_text(io)
+    @mutations.each_with_index do |m, i|
+      io.puts("#{i + 1}. #{m.operator_name} — #{m.subject.name} (line #{m.line})")
+      m.diff.each_line { |line| io.puts("   #{line.chomp}") }
+      io.puts("")
+    end
+    label = @mutations.length == 1 ? "1 mutation" : "#{@mutations.length} mutations"
+    io.puts(label)
+  end
+
+  def render_json(io)
+    data = @mutations.map do |m|
+      { operator: m.operator_name, subject: m.subject.name,
+        file: m.file_path, line: m.line, diff: m.diff }
+    end
+    io.puts(JSON.pretty_generate(data))
+  end
+end

data/lib/evilution/cli/printers.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+module Evilution::CLI::Printers
+end

data/lib/evilution/cli/result.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Evilution::CLI
+  Result = Struct.new(:exit_code, :error, :error_rendered, keyword_init: true) do
+    def initialize(exit_code:, error: nil, error_rendered: false)
+      super
+    end
+  end
+end