evilution 0.16.1 → 0.18.0

data/lib/evilution/cli.rb

@@ -2,9 +2,15 @@
 
 require "json"
 require "optparse"
+require "tempfile"
 require_relative "version"
 require_relative "config"
+require_relative "hooks"
+require_relative "hooks/registry"
+require_relative "hooks/loader"
 require_relative "runner"
+require_relative "spec_resolver"
+require_relative "git/changed_files"
 
 class Evilution::CLI
   def initialize(argv, stdin: $stdin)
@@ -16,34 +22,42 @@ class Evilution::CLI
     argv = preprocess_flags(argv)
     raw_args = build_option_parser.parse!(argv)
     @files, @line_ranges = parse_file_args(raw_args)
-    read_stdin_files if @options.delete(:stdin) && @command == :run
+    read_stdin_files if @options.delete(:stdin) && %i[run subjects].include?(@command)
   end
 
-  def call
+  def call # rubocop:disable Metrics/CyclomaticComplexity
     case @command
-    when :version
-      $stdout.puts(Evilution::VERSION)
-      0
-    when :init
-      run_init
-    when :mcp
-      run_mcp
-    when :session_list
-      run_session_list
-    when :session_show
-      run_session_show
-    when :session_gc
-      run_session_gc
-    when :session_error
-      warn("Error: #{@session_error}")
-      2
-    when :run
-      run_mutations
+    when :version             then run_version
+    when :init                then run_init
+    when :mcp                 then run_mcp
+    when :session_list        then run_session_list
+    when :session_show        then run_session_show
+    when :session_diff        then run_session_diff
+    when :session_gc          then run_session_gc
+    when :session_error       then run_subcommand_error(@session_error)
+    when :subjects            then run_subjects
+    when :tests_list          then run_tests_list
+    when :tests_error         then run_subcommand_error(@tests_error)
+    when :environment_show    then run_environment_show
+    when :environment_error   then run_subcommand_error(@environment_error)
+    when :util_mutation       then run_util_mutation
+    when :util_error          then run_subcommand_error(@util_error)
+    when :run                 then run_mutations
     end
   end
 
   private
 
+  def run_version
+    $stdout.puts(Evilution::VERSION)
+    0
+  end
+
+  def run_subcommand_error(message)
+    warn("Error: #{message}")
+    2
+  end
+
   def extract_command(argv)
     case argv.first
     when "version"
@@ -58,6 +72,18 @@ class Evilution::CLI
     when "session"
       argv.shift
       extract_session_subcommand(argv)
+    when "subjects"
+      @command = :subjects
+      argv.shift
+    when "tests"
+      argv.shift
+      extract_tests_subcommand(argv)
+    when "environment"
+      argv.shift
+      extract_environment_subcommand(argv)
+    when "util"
+      argv.shift
+      extract_util_subcommand(argv)
     when "run"
       argv.shift
     end
@@ -73,15 +99,66 @@ class Evilution::CLI
     when "show"
       @command = :session_show
       argv.shift
+    when "diff"
+      @command = :session_diff
+      argv.shift
     when "gc"
       @command = :session_gc
       argv.shift
     when nil
       @command = :session_error
-      @session_error = "Missing session subcommand. Available subcommands: list, show, gc"
+      @session_error = "Missing session subcommand. Available subcommands: list, show, diff, gc"
     else
       @command = :session_error
-      @session_error = "Unknown session subcommand: #{subcommand}. Available subcommands: list, show, gc"
+      @session_error = "Unknown session subcommand: #{subcommand}. Available subcommands: list, show, diff, gc"
+      argv.shift
+    end
+  end
+
+  def extract_environment_subcommand(argv)
+    subcommand = argv.first
+    case subcommand
+    when "show"
+      @command = :environment_show
+      argv.shift
+    when nil
+      @command = :environment_error
+      @environment_error = "Missing environment subcommand. Available subcommands: show"
+    else
+      @command = :environment_error
+      @environment_error = "Unknown environment subcommand: #{subcommand}. Available subcommands: show"
+      argv.shift
+    end
+  end
+
+  def extract_tests_subcommand(argv)
+    subcommand = argv.first
+    case subcommand
+    when "list"
+      @command = :tests_list
+      argv.shift
+    when nil
+      @command = :tests_error
+      @tests_error = "Missing tests subcommand. Available subcommands: list"
+    else
+      @command = :tests_error
+      @tests_error = "Unknown tests subcommand: #{subcommand}. Available subcommands: list"
+      argv.shift
+    end
+  end
+
+  def extract_util_subcommand(argv)
+    subcommand = argv.first
+    case subcommand
+    when "mutation"
+      @command = :util_mutation
+      argv.shift
+    when nil
+      @command = :util_error
+      @util_error = "Missing util subcommand. Available subcommands: mutation"
+    else
+      @command = :util_error
+      @util_error = "Unknown util subcommand: #{subcommand}. Available subcommands: mutation"
       argv.shift
     end
   end
@@ -125,7 +202,8 @@ class Evilution::CLI
     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,gc}, mcp, version"
+    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
@@ -162,7 +240,14 @@ class Evilution::CLI
     opts.on("--stdin", "Read target file paths from stdin (one per line)") { @options[:stdin] = true }
     opts.on("--suggest-tests", "Generate concrete RSpec test code in suggestions") { @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("--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
@@ -188,6 +273,151 @@ class Evilution::CLI
     0
   end
 
+  def run_subjects
+    raise Evilution::ConfigError, @stdin_error if @stdin_error
+
+    config = Evilution::Config.new(target_files: @files, line_ranges: @line_ranges, **@options)
+    runner = Evilution::Runner.new(config: config)
+    subjects = runner.parse_and_filter_subjects
+
+    if subjects.empty?
+      $stdout.puts("No subjects found")
+      return 0
+    end
+
+    registry = Evilution::Mutator::Registry.default
+    filter = build_subject_filter(config)
+    total_mutations = 0
+
+    subjects.each do |subj|
+      count = registry.mutations_for(subj, filter: filter).length
+      total_mutations += count
+      label = count == 1 ? "1 mutation" : "#{count} mutations"
+      $stdout.puts("  #{subj.name}  #{subj.file_path}:#{subj.line_number}  (#{label})")
+    ensure
+      subj.release_node!
+    end
+
+    $stdout.puts("")
+    $stdout.puts("#{subjects.length} subjects, #{total_mutations} mutations")
+    0
+  rescue Evilution::Error => e
+    warn("Error: #{e.message}")
+    2
+  end
+
+  def build_subject_filter(config)
+    return nil if config.ignore_patterns.empty?
+
+    require_relative "ast/pattern/filter"
+    Evilution::AST::Pattern::Filter.new(config.ignore_patterns)
+  end
+
+  def run_tests_list
+    config = Evilution::Config.new(target_files: @files, line_ranges: @line_ranges, **@options)
+
+    if config.spec_files.any?
+      print_explicit_spec_files(config.spec_files)
+      return 0
+    end
+
+    source_files = resolve_source_files(config)
+    if source_files.empty?
+      $stdout.puts("No source files found")
+      return 0
+    end
+
+    resolver = Evilution::SpecResolver.new
+    print_resolved_specs(source_files, resolver)
+    0
+  rescue Evilution::Error => e
+    warn("Error: #{e.message}")
+    2
+  end
+
+  def resolve_source_files(config)
+    return config.target_files unless config.target_files.empty?
+
+    Evilution::Git::ChangedFiles.new.call
+  rescue Evilution::Error
+    []
+  end
+
+  def print_explicit_spec_files(spec_files)
+    spec_files.each { |f| $stdout.puts("  #{f}") }
+    label = spec_files.length == 1 ? "1 spec file" : "#{spec_files.length} spec files"
+    $stdout.puts("")
+    $stdout.puts(label)
+  end
+
+  def print_resolved_specs(source_files, resolver)
+    unique_specs = []
+    source_files.each do |source|
+      spec = resolver.call(source)
+      if spec
+        unique_specs << spec
+        $stdout.puts("  #{spec}  (#{source})")
+      else
+        $stdout.puts("  #{source}  (no spec found)")
+      end
+    end
+
+    unique_specs.uniq!
+    $stdout.puts("")
+    spec_label = unique_specs.length == 1 ? "1 spec file" : "#{unique_specs.length} spec files"
+    $stdout.puts("#{source_files.length} source files, #{spec_label}")
+  end
+
+  def run_environment_show
+    config = Evilution::Config.new(**@options)
+    $stdout.puts(format_environment(config))
+    0
+  rescue Evilution::ConfigError => e
+    warn("Error: #{e.message}")
+    2
+  end
+
+  def format_environment(config)
+    config_file = Evilution::Config::CONFIG_FILES.find { |path| File.exist?(path) }
+    lines = environment_header(config_file)
+    lines.concat(environment_settings(config))
+    lines.join("\n")
+  end
+
+  def environment_header(config_file)
+    [
+      "Evilution Environment",
+      ("=" * 30),
+      "",
+      "evilution: #{Evilution::VERSION}",
+      "ruby: #{RUBY_VERSION}",
+      "config_file: #{config_file || "(none)"}",
+      "",
+      "Settings:"
+    ]
+  end
+
+  def environment_settings(config)
+    [
+      "  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)"}",
+      "  ignore_patterns: #{config.ignore_patterns.empty? ? "(none)" : config.ignore_patterns.inspect}"
+    ]
+  end
+
   def run_mcp
     require_relative "mcp/server"
     server = Evilution::MCP::Server.build
@@ -237,6 +467,79 @@ class Evilution::CLI
     end
   end
 
+  def run_util_mutation
+    source, file_path = resolve_util_mutation_source
+    subjects = parse_source_to_subjects(source, file_path)
+    registry = Evilution::Mutator::Registry.default
+    mutations = subjects.flat_map { |s| registry.mutations_for(s) }
+
+    if mutations.empty?
+      $stdout.puts("No mutations generated")
+      return 0
+    end
+
+    if @options[:format] == :json
+      print_util_mutations_json(mutations)
+    else
+      print_util_mutations_text(mutations)
+    end
+
+    0
+  rescue Evilution::Error => e
+    warn("Error: #{e.message}")
+    2
+  ensure
+    @util_tmpfile&.close!
+  end
+
+  def resolve_util_mutation_source
+    if @options[:eval]
+      tmpfile = Tempfile.new(["evilution_eval", ".rb"])
+      tmpfile.write(@options[:eval])
+      tmpfile.flush
+      @util_tmpfile = tmpfile
+      [@options[:eval], tmpfile.path]
+    elsif @files.first
+      path = @files.first
+      raise Evilution::Error, "file not found: #{path}" unless File.exist?(path)
+
+      begin
+        [File.read(path), path]
+      rescue SystemCallError => e
+        raise Evilution::Error, e.message
+      end
+    else
+      raise Evilution::Error, "source required: use -e 'code' or provide a file path"
+    end
+  end
+
+  def parse_source_to_subjects(source, file_label)
+    result = Prism.parse(source)
+    raise Evilution::Error, "failed to parse source: #{result.errors.map(&:message).join(", ")}" if result.failure?
+
+    finder = Evilution::AST::SubjectFinder.new(source, file_label)
+    finder.visit(result.value)
+    finder.subjects
+  end
+
+  def print_util_mutations_text(mutations)
+    mutations.each_with_index do |m, i|
+      $stdout.puts("#{i + 1}. #{m.operator_name} — #{m.subject.name} (line #{m.line})")
+      m.diff.each_line { |line| $stdout.puts("   #{line}") }
+      $stdout.puts("")
+    end
+    label = mutations.length == 1 ? "1 mutation" : "#{mutations.length} mutations"
+    $stdout.puts(label)
+  end
+
+  def print_util_mutations_json(mutations)
+    data = mutations.map do |m|
+      { operator: m.operator_name, subject: m.subject.name,
+        file: m.file_path, line: m.line, diff: m.diff }
+    end
+    $stdout.puts(JSON.pretty_generate(data))
+  end
+
   def run_session_list
     require_relative "session/store"
 
@@ -309,6 +612,70 @@ class Evilution::CLI
     2
   end
 
+  def run_session_diff
+    require_relative "session/store"
+    require_relative "session/diff"
+
+    raise Evilution::ConfigError, "two session file paths required" unless @files.length == 2
+
+    store = Evilution::Session::Store.new
+    base_data = store.load(@files[0])
+    head_data = store.load(@files[1])
+
+    diff = Evilution::Session::Diff.new
+    result = diff.call(base_data, head_data)
+
+    if @options[:format] == :json
+      $stdout.puts(JSON.pretty_generate(result.to_h))
+    else
+      print_session_diff(result)
+    end
+
+    0
+  rescue Evilution::Error, SystemCallError => e
+    warn("Error: #{e.message}")
+    2
+  rescue ::JSON::ParserError => e
+    warn("Error: invalid session file: #{e.message}")
+    2
+  end
+
+  def print_session_diff(result)
+    print_diff_summary(result.summary)
+    print_diff_section("Fixed (survived \u2192 killed)", result.fixed, "\e[32m")
+    print_diff_section("New survivors (killed \u2192 survived)", result.new_survivors, "\e[31m")
+    print_diff_section("Persistent survivors", result.persistent, "\e[33m")
+
+    return unless result.fixed.empty? && result.new_survivors.empty? && result.persistent.empty?
+
+    $stdout.puts("")
+    $stdout.puts("No mutation changes between sessions")
+  end
+
+  def print_diff_summary(summary)
+    delta_str = format("%+.2f%%", summary.score_delta * 100)
+    $stdout.puts("Session Diff")
+    $stdout.puts("=" * 40)
+    $stdout.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))
+    $stdout.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))
+    $stdout.puts("Delta:       #{delta_str}")
+  end
+
+  def print_diff_section(title, mutations, color)
+    return if mutations.empty?
+
+    reset = "\e[0m"
+    $stdout.puts("")
+    $stdout.puts("#{color}#{title} (#{mutations.length}):#{reset}")
+    mutations.each do |m|
+      $stdout.puts("  #{m["operator"]} — #{m["file"]}:#{m["line"]}  #{m["subject"]}")
+    end
+  end
+
   def run_session_gc
     require_relative "session/store"
 
@@ -434,7 +801,8 @@ class Evilution::CLI
 
     file_options = Evilution::Config.file_options
     config = Evilution::Config.new(**@options, target_files: @files, line_ranges: @line_ranges)
-    runner = Evilution::Runner.new(config: config)
+    hooks = build_hooks(config)
+    runner = Evilution::Runner.new(config: config, hooks: hooks)
     summary = runner.call
     summary.success?(min_score: config.min_score) ? 0 : 1
   rescue Evilution::Error => e
@@ -446,6 +814,14 @@ class Evilution::CLI
     2
   end
 
+  def build_hooks(config)
+    return nil if config.hooks.empty?
+
+    registry = Evilution::Hooks::Registry.new
+    Evilution::Hooks::Loader.call(registry, config.hooks)
+    registry
+  end
+
   def json_format?(config, file_options)
     return config.json? if config
 

data/lib/evilution/config.rb

@@ -22,13 +22,17 @@ class Evilution::Config
     progress: true,
     save_session: false,
     line_ranges: {},
-    spec_files: []
+    spec_files: [],
+    ignore_patterns: [],
+    show_disabled: false,
+    baseline_session: nil
   }.freeze
 
   attr_reader :target_files, :timeout, :format,
               :target, :min_score, :integration, :verbose, :quiet,
               :jobs, :fail_fast, :baseline, :isolation, :incremental, :suggest_tests,
-              :progress, :save_session, :line_ranges, :spec_files
+              :progress, :save_session, :line_ranges, :spec_files, :hooks,
+              :ignore_patterns, :show_disabled, :baseline_session
 
   def initialize(**options)
     file_options = options.delete(:skip_config_file) ? {} : load_config_file
@@ -81,6 +85,10 @@ class Evilution::Config
     save_session
   end
 
+  def show_disabled?
+    show_disabled
+  end
+
   def self.file_options
     CONFIG_FILES.each do |path|
       next unless File.exist?(path)
@@ -122,6 +130,17 @@ class Evilution::Config
 
       # Generate concrete RSpec test code in suggestions (default: false)
       # suggest_tests: false
+
+      # Hooks: Ruby files returning a Proc, keyed by lifecycle event
+      # hooks:
+      #   worker_process_start: config/evilution_hooks/worker_start.rb
+      #   mutation_insert_pre: config/evilution_hooks/mutation_pre.rb
+
+      # AST patterns to skip during mutation generation (default: [])
+      # See docs/ast_pattern_syntax.md for pattern syntax
+      # ignore_patterns:
+      #   - "call{name=info, receiver=call{name=logger}}"
+      #   - "call{name=debug|warn}"
     YAML
   end
 
@@ -157,6 +176,10 @@ class Evilution::Config
     @save_session = merged[:save_session]
     @line_ranges = merged[:line_ranges] || {}
     @spec_files = Array(merged[:spec_files])
+    @ignore_patterns = validate_ignore_patterns(merged[:ignore_patterns])
+    @show_disabled = merged[:show_disabled]
+    @baseline_session = merged[:baseline_session]
+    @hooks = validate_hooks(merged[:hooks])
   end
 
   def validate_isolation(value)
@@ -180,6 +203,24 @@ class Evilution::Config
     raise Evilution::ConfigError, "jobs must be a positive integer, got #{value.inspect}"
   end
 
+  def validate_ignore_patterns(value)
+    patterns = Array(value)
+    patterns.each do |pattern|
+      unless pattern.is_a?(String)
+        raise Evilution::ConfigError,
+              "ignore_patterns must be an array of strings, got #{pattern.class} (#{pattern.inspect})"
+      end
+    end
+    patterns
+  end
+
+  def validate_hooks(value)
+    return {} if value.nil?
+    raise Evilution::ConfigError, "hooks must be a mapping of event names to file paths, got #{value.class}" unless value.is_a?(Hash)
+
+    value
+  end
+
   def load_config_file
     self.class.file_options
   end

data/lib/evilution/disable_comment.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "prism"
+
+class Evilution::DisableComment
+  DISABLE_MARKER = /\A#\s*evilution:disable\s*\z/
+  ENABLE_MARKER = /\A#\s*evilution:enable\s*\z/
+
+  def call(source)
+    return [] if source.empty?
+
+    result = Prism.parse(source)
+    return [] if result.failure?
+
+    method_ranges = collect_def_ranges(result.value)
+    comments = classify_comments(result, source)
+    scan_comments(comments, method_ranges, source.lines.length)
+  end
+
+  private
+
+  def classify_comments(parse_result, source)
+    parse_result.comments.filter_map do |comment|
+      loc = comment.location
+      text = source[loc.start_offset...loc.end_offset]
+
+      if text.match?(DISABLE_MARKER)
+        line = source.lines[loc.start_line - 1]
+        standalone = line.strip == text.strip
+        { type: :disable, line: loc.start_line, standalone: standalone }
+      elsif text.match?(ENABLE_MARKER)
+        { type: :enable, line: loc.start_line }
+      end
+    end
+  end
+
+  def scan_comments(comments, method_ranges, total_lines)
+    disabled = []
+    range_start = nil
+
+    comments.each do |comment|
+      if comment[:type] == :enable && range_start
+        disabled << (range_start..comment[:line])
+        range_start = nil
+      elsif comment[:type] == :disable && range_start.nil?
+        range_start = process_disable(comment, method_ranges, disabled)
+      end
+    end
+
+    disabled << (range_start..total_lines) if range_start
+
+    disabled
+  end
+
+  def process_disable(comment, method_ranges, disabled)
+    unless comment[:standalone]
+      disabled << (comment[:line]..comment[:line])
+      return nil
+    end
+
+    method_range = find_method_range(method_ranges, comment[:line] + 1)
+    if method_range
+      disabled << (comment[:line]..method_range.last)
+      nil
+    else
+      comment[:line]
+    end
+  end
+
+  def collect_def_ranges(node)
+    ranges = []
+    walk_def_nodes(node, ranges)
+    ranges
+  end
+
+  def walk_def_nodes(node, ranges)
+    if node.is_a?(Prism::DefNode)
+      loc = node.location
+      ranges << (loc.start_line..loc.end_line)
+    end
+
+    node.child_nodes.each do |child|
+      walk_def_nodes(child, ranges) if child
+    end
+  end
+
+  def find_method_range(method_ranges, def_line)
+    method_ranges.find { |range| range.first == def_line }
+  end
+end