evilution 0.22.7 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 953b824799c03617e8e41a67f759c5edbd122b63046f8916e19d215021de5871
-  data.tar.gz: 38e3498c7cc763e44a5cded169c035b1a48d02c14c95b9ff4ae0800dd63389cd
+  metadata.gz: 7fe91007e7b5113b2e790e726991bcc872abe8fe8e3c321b1e1f5896f9ccec8d
+  data.tar.gz: 809753233bdd01ec72a9014e31dcc0f821f9e569b915bc58aee4ac69ce0168df
 SHA512:
-  metadata.gz: cceb0046285ad1efdd63914af840da66354006d97f1f9da0642dcf649e3628a342c6ed5f3c6776f3b76dee7eb41af833033a4c9c18992eaa6773bf1c5da8ca75
-  data.tar.gz: 6928979ecd999f213b87c3460179f4a09008894866e31d5e822f214ab521235e8463a389768e40bff065512fc1e55355d0ca249e739cb571210ccd429d94db82
+  metadata.gz: 5e1a965330f8d02db82e5bee493682a70a3492f67985e2e0729a66354de51c9e8d3e0b2323617d82dc3209eb7791e5cfc0af2e735c5351081fe48f44d6e26f22
+  data.tar.gz: 43bbd5cf785fe4370ef351642f697a205cd2af2490dbc15a187aae640a35df0d7a472f2d133ad45ac274fd0c5841401f1a6f8a42b395a97cb92b125b51ec84fb

data/.beads/interactions.jsonl

@@ -17,3 +17,6 @@
 {"id":"int-d3431bcd","kind":"field_change","created_at":"2026-04-12T02:57:43.902279367Z","actor":"Denis Kiselev","issue_id":"EV-86l6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
 {"id":"int-f409d79d","kind":"field_change","created_at":"2026-04-12T02:57:44.180309214Z","actor":"Denis Kiselev","issue_id":"EV-o28o","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
 {"id":"int-ba5d5d3e","kind":"field_change","created_at":"2026-04-12T03:42:58.408103757Z","actor":"Denis Kiselev","issue_id":"EV-1fq8","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-a43dbc64","kind":"field_change","created_at":"2026-04-13T10:26:45.290646646Z","actor":"Denis Kiselev","issue_id":"EV-gs1r","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-ec0a4368","kind":"field_change","created_at":"2026-04-13T11:25:13.089935275Z","actor":"Denis Kiselev","issue_id":"EV-930z","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged in PR #687"}}
+{"id":"int-a59bbad4","kind":"field_change","created_at":"2026-04-13T16:01:10.349431405Z","actor":"Denis Kiselev","issue_id":"EV-fu7n","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.23.0] - 2026-04-14
+
+### Changed
+
+- **Internal CLI refactoring** — `lib/evilution/cli.rb` was decomposed into smaller, focused units for readability and maintainability; no user-visible behavior change (#485, PR #704)
+
+### Fixed
+
+- **`session show` / `session diff` / `util mutation` diff output double-spaced between lines** — the text printers piped each diff line through `io.puts` even though `String#each_line` already yields a trailing newline, so every diff line was separated by a blank line; now `line.chomp` strips the trailing newline before `puts` re-adds it, rendering diffs with correct spacing (PR #704)
+- **`subjects` summary printed "1 subjects, 1 mutations"** — the summary line always pluralized, producing grammatically incorrect output for single-element results; now pluralizes both nouns independently via a `pluralize` helper so single counts read "1 subject, 1 mutation" (PR #704)
+- **`session show` crashed on permission errors and other `SystemCallError`s** — `Session::Store#load` can raise `Errno::EACCES` or other `SystemCallError`s (e.g. permission denied on `File.read`) which were not rescued, causing a hard crash instead of a clean exit 2; now wraps `SystemCallError` as `Evilution::Error` in `Commands::SessionShow` for parity with `Commands::SessionDiff` (PR #704)
+
 ## [0.22.7] - 2026-04-13
 
 ### Fixed

data/README.md

@@ -95,7 +95,7 @@ Creates `.evilution.yml`:
 # save_session: false      # persist results under .evilution/results/
 # isolation: auto          # auto | fork | in_process (auto selects fork for Rails)
 # preload: null            # path to preload before forking; false to disable; auto-detects for Rails
-# skip_heredoc_literals: false  # skip all string literal mutations inside heredocs
+# skip_heredoc_literals: false  # skip string literal mutations inside heredocs (recommended for Rails: heredoc SQL/templates rarely have test coverage)
 # show_disabled: false     # report mutations skipped by disable comments
 # baseline_session: null   # path to session file for HTML comparison
 # ignore_patterns: []      # AST patterns to exclude (see docs/ast_pattern_syntax.md)
@@ -288,13 +288,12 @@ The server exposes the following tools:
 | Tool | Description |
 |---|---|
 | `evilution-mutate` | Run mutation testing on target files with structured JSON results |
-| `evilution-session-list` | Browse saved session history |
-| `evilution-session-show` | Display detailed session results |
-| `evilution-session-diff` | Compare two sessions (fixed/new/persistent survivors, score delta) |
+| `evilution-session` | Inspect mutation testing history — `action: list` browses saved sessions, `action: show` displays one, `action: diff` compares two (fixed/new/persistent survivors, score delta) |
+| `evilution-info` | Discovery before mutation — `action: subjects` lists mutatable methods with mutation counts, `action: tests` resolves which specs cover given sources, `action: environment` dumps the effective config |
 
 ### Verbosity Control
 
-The MCP tool accepts a `verbosity` parameter to control response size:
+The `evilution-mutate` tool accepts a `verbosity` parameter to control response size:
 
 | Level       | Default | What's included                                              |
 |-------------|---------|--------------------------------------------------------------|
@@ -304,11 +303,41 @@ The MCP tool accepts a `verbosity` parameter to control response size:
 
 Use `minimal` when context window budget is tight and you only need to see what survived. Use `full` when you need to inspect killed/neutral/equivalent entries for debugging.
 
+### Enriched Survived Entries
+
+Unlike `evilution --format json`, every survived entry returned by `evilution-mutate` carries extra fields so the agent can act without a second round-trip:
+
+| Field | What it gives you |
+|---|---|
+| `subject` | `Class#method` for the mutated subject — points at the exact method to test |
+| `spec_file` | Resolved spec/test path (when one exists) — e.g. an RSpec spec file or Minitest test file, so you can drop new tests straight into it |
+| `next_step` | Concrete natural-language hint — "add a test in X that fails against this mutation at Y:line" |
+
+These fields are added in addition to the existing `operator`, `file`, `line`, `diff`, `suggestion`, and `test_command` so agents can triage survivors in one pass.
+
 ### Concrete Test Suggestions
 
-The MCP tool accepts a `suggest_tests` boolean parameter (default: `false`). When enabled, survived mutation suggestions contain concrete test code that an agent can drop into a test file, instead of static description text. The MCP tool currently generates RSpec-style suggestions (`it`/`expect` blocks).
+The `evilution-mutate` tool accepts a `suggest_tests` boolean parameter (default: `false`). When enabled, survived mutation suggestions contain concrete test code that an agent can drop into a test file, instead of static description text. It currently generates RSpec-style suggestions (`it`/`expect` blocks).
+
+Pass `suggest_tests: true` in the `evilution-mutate` call to activate this mode. The CLI also supports `--suggest-tests`; when using the CLI, generated suggestions match the `--integration` setting (RSpec `it`/`expect` blocks or Minitest `def test_`/`assert_equal` methods).
 
-Pass `suggest_tests: true` in the MCP tool call to activate this mode. The CLI also supports `--suggest-tests`; when using the CLI, generated suggestions match the `--integration` setting (RSpec `it`/`expect` blocks or Minitest `def test_`/`assert_equal` methods).
+### Project Config File
+
+`evilution-mutate` and `evilution-info` load `.evilution.yml` (or `config/evilution.yml`) by default, matching `evilution` CLI behavior — so timeout, jobs, integration, target, ignore_patterns, and other project settings carry over without the agent having to re-pass them on every call. Explicit tool parameters still win over file settings.
+
+Pass `skip_config: true` to ignore the project config file. This skips loading `.evilution.yml` / `config/evilution.yml`, but MCP-specific overrides (JSON output, quiet mode, preload disabled) and explicit tool parameters still apply.
+
+### Iterative Workflow Parameters
+
+`evilution-mutate` exposes the full set of CLI knobs agents need for iterative TDD:
+
+| Parameter | Purpose |
+|---|---|
+| `incremental` | Cache killed/timeout results across runs — set `true` when iterating on the same files |
+| `integration` | `rspec` or `minitest` |
+| `isolation` | `auto`, `fork`, or `in_process` |
+| `baseline` | `false` to skip the baseline suite check when you already know it's green |
+| `save_session` | Persist results to `.evilution/results/` for inspection via `evilution-session` |
 
 > **Note**: `.mcp.json` is gitignored by default since it is a local editor/agent configuration file.
 

data/lib/evilution/cli/command.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+class Evilution::CLI::Command
+  def initialize(parsed_args, stdout: $stdout, stderr: $stderr)
+    @options = parsed_args.options
+    @files = parsed_args.files
+    @line_ranges = parsed_args.line_ranges
+    @stdin_error = parsed_args.stdin_error
+    @stdout = stdout
+    @stderr = stderr
+  end
+
+  def call
+    Evilution::CLI::Result.new(exit_code: perform)
+  rescue Evilution::Error => e
+    Evilution::CLI::Result.new(exit_code: 2, error: e)
+  end
+
+  private
+
+  def perform
+    raise NotImplementedError
+  end
+
+  def build_operator_options(config)
+    { skip_heredoc_literals: config.skip_heredoc_literals? }
+  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
+end

data/lib/evilution/cli/commands/environment_show.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/environment"
+require_relative "../../config"
+
+class Evilution::CLI::Commands::EnvironmentShow < Evilution::CLI::Command
+  private
+
+  def perform
+    config = Evilution::Config.new(**@options)
+    config_file = Evilution::Config::CONFIG_FILES.find { |path| File.exist?(path) }
+    Evilution::CLI::Printers::Environment.new(config, config_file: config_file).render(@stdout)
+    0
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:environment_show, Evilution::CLI::Commands::EnvironmentShow)

data/lib/evilution/cli/commands/init.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../../config"
+
+class Evilution::CLI::Commands::Init < Evilution::CLI::Command
+  private
+
+  def perform
+    path = ".evilution.yml"
+    if File.exist?(path)
+      @stderr.puts("#{path} already exists")
+      return 1
+    end
+
+    File.write(path, Evilution::Config.default_template)
+    @stdout.puts("Created #{path}")
+    0
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:init, Evilution::CLI::Commands::Init)

data/lib/evilution/cli/commands/mcp.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+
+class Evilution::CLI::Commands::Mcp < Evilution::CLI::Command
+  private
+
+  def perform
+    require_relative "../../mcp/server"
+    server = Evilution::MCP::Server.build
+    transport = ::MCP::Server::Transports::StdioTransport.new(server)
+    transport.open
+    0
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:mcp, Evilution::CLI::Commands::Mcp)

data/lib/evilution/cli/commands/run.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../commands"
+require_relative "../command"
+require_relative "../result"
+require_relative "../dispatcher"
+require_relative "../../config"
+require_relative "../../runner"
+require_relative "../../hooks"
+require_relative "../../hooks/registry"
+require_relative "../../hooks/loader"
+
+class Evilution::CLI::Commands::Run < Evilution::CLI::Command
+  def call
+    file_options = Evilution::Config.file_options
+    config = nil
+    raise Evilution::ConfigError, @stdin_error if @stdin_error
+
+    config = Evilution::Config.new(**@options, target_files: @files, line_ranges: @line_ranges)
+    hooks = build_hooks(config)
+    runner = Evilution::Runner.new(config: config, hooks: hooks)
+    summary = runner.call
+    exit_code = summary.success?(min_score: config.min_score) ? 0 : 1
+    Evilution::CLI::Result.new(exit_code: exit_code)
+  rescue Evilution::Error => e
+    handle_error(e, config, file_options)
+  end
+
+  private
+
+  def handle_error(error, config, file_options)
+    if json_format?(config, file_options)
+      @stdout.puts(JSON.generate(error_payload(error)))
+      Evilution::CLI::Result.new(exit_code: 2, error: error, error_rendered: true)
+    else
+      Evilution::CLI::Result.new(exit_code: 2, error: error)
+    end
+  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
+
+    fmt = @options[:format] || (file_options && file_options[:format])
+    fmt && fmt.to_sym == :json
+  end
+
+  def error_payload(error)
+    type = case error
+           when Evilution::ConfigError then "config_error"
+           when Evilution::ParseError  then "parse_error"
+           else "runtime_error"
+           end
+    payload = { type: type, message: error.message }
+    payload[:file] = error.file if error.respond_to?(:file) && error.file
+    { error: payload }
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:run, Evilution::CLI::Commands::Run)

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/session_diff"
+require_relative "../../session/store"
+require_relative "../../session/diff"
+
+class Evilution::CLI::Commands::SessionDiff < Evilution::CLI::Command
+  private
+
+  def perform
+    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])
+    result = Evilution::Session::Diff.new.call(base_data, head_data)
+    Evilution::CLI::Printers::SessionDiff.new(result, format: @options[:format]).render(@stdout)
+    0
+  rescue ::JSON::ParserError => e
+    raise Evilution::Error, "invalid session file: #{e.message}"
+  rescue SystemCallError => e
+    raise Evilution::Error, e.message
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:session_diff, Evilution::CLI::Commands::SessionDiff)

data/lib/evilution/cli/commands/session_gc.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../../session/store"
+
+class Evilution::CLI::Commands::SessionGc < Evilution::CLI::Command
+  private
+
+  def perform
+    raise Evilution::ConfigError, "--older-than is required for session gc" unless @options[:older_than]
+
+    cutoff = parse_duration(@options[:older_than])
+    store_opts = {}
+    store_opts[:results_dir] = @options[:results_dir] if @options[:results_dir]
+    store = Evilution::Session::Store.new(**store_opts)
+    deleted = store.gc(older_than: cutoff)
+
+    if deleted.empty?
+      @stdout.puts("No sessions to delete")
+    else
+      @stdout.puts("Deleted #{deleted.length} session#{"s" unless deleted.length == 1}")
+    end
+
+    0
+  end
+
+  def parse_duration(value)
+    match = value.match(/\A(\d+)([dhw])\z/)
+    unless match
+      raise Evilution::ConfigError,
+            "invalid --older-than format: #{value.inspect}. Use Nd, Nh, or Nw (e.g., 30d)"
+    end
+
+    amount = match[1].to_i
+    seconds = case match[2]
+              when "h" then amount * 3600
+              when "d" then amount * 86_400
+              when "w" then amount * 604_800
+              end
+    Time.now - seconds
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:session_gc, Evilution::CLI::Commands::SessionGc)

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/session_list"
+require_relative "../../session/store"
+
+class Evilution::CLI::Commands::SessionList < Evilution::CLI::Command
+  private
+
+  def perform
+    store_opts = {}
+    store_opts[:results_dir] = @options[:results_dir] if @options[:results_dir]
+    store = Evilution::Session::Store.new(**store_opts)
+    sessions = filter_sessions(store.list)
+
+    if sessions.empty?
+      @stdout.puts("No sessions found")
+      return 0
+    end
+
+    Evilution::CLI::Printers::SessionList.new(sessions, format: @options[:format]).render(@stdout)
+    0
+  end
+
+  def filter_sessions(sessions)
+    if @options[:since]
+      cutoff = parse_date(@options[:since])
+      sessions = sessions.select do |s|
+        ts = s[:timestamp]
+        next false unless ts.is_a?(String)
+
+        Time.parse(ts) >= cutoff
+      rescue ArgumentError
+        false
+      end
+    end
+    sessions = sessions.first(@options[:limit]) if @options[:limit]
+    sessions
+  end
+
+  def parse_date(value)
+    Time.parse(value)
+  rescue ArgumentError
+    raise Evilution::ConfigError, "invalid --since date: #{value.inspect}. Use YYYY-MM-DD format"
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:session_list, Evilution::CLI::Commands::SessionList)

data/lib/evilution/cli/commands/session_show.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/session_detail"
+require_relative "../../session/store"
+
+class Evilution::CLI::Commands::SessionShow < Evilution::CLI::Command
+  private
+
+  def perform
+    path = @files.first
+    raise Evilution::ConfigError, "session file path required" unless path
+
+    data = Evilution::Session::Store.new.load(path)
+    Evilution::CLI::Printers::SessionDetail.new(data, format: @options[:format]).render(@stdout)
+    0
+  rescue ::JSON::ParserError => e
+    raise Evilution::Error, "invalid session file: #{e.message}"
+  rescue ::SystemCallError => e
+    raise Evilution::Error, e.message
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:session_show, Evilution::CLI::Commands::SessionShow)

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/subjects"
+require_relative "../../config"
+require_relative "../../runner"
+require_relative "../../mutator"
+
+class Evilution::CLI::Commands::Subjects < Evilution::CLI::Command
+  private
+
+  def perform
+    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
+
+    entries, total = collect_entries(subjects, config)
+    Evilution::CLI::Printers::Subjects.new(entries, total_mutations: total).render(@stdout)
+    0
+  end
+
+  def collect_entries(subjects, config)
+    registry = Evilution::Mutator::Registry.default
+    filter = build_subject_filter(config)
+    operator_options = build_operator_options(config)
+    entries = []
+    total = 0
+
+    subjects.each do |subj|
+      count = registry.mutations_for(subj, filter: filter, operator_options: operator_options).length
+      total += count
+      entries << { name: subj.name, file_path: subj.file_path, line_number: subj.line_number, mutation_count: count }
+    ensure
+      subj.release_node!
+    end
+
+    [entries, total]
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:subjects, Evilution::CLI::Commands::Subjects)

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/tests_list"
+require_relative "../../config"
+require_relative "../../spec_resolver"
+require_relative "../../git/changed_files"
+
+class Evilution::CLI::Commands::TestsList < Evilution::CLI::Command
+  private
+
+  def perform
+    config = Evilution::Config.new(target_files: @files, line_ranges: @line_ranges, **@options)
+
+    if config.spec_files.any?
+      Evilution::CLI::Printers::TestsList.new(mode: :explicit, specs: config.spec_files).render(@stdout)
+      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
+    entries = source_files.map { |source| { source: source, spec: resolver.call(source) } }
+    Evilution::CLI::Printers::TestsList.new(mode: :resolved, entries: entries).render(@stdout)
+    0
+  end
+
+  def resolve_source_files(config)
+    return config.target_files unless config.target_files.empty?
+
+    Evilution::Git::ChangedFiles.new.call
+  rescue Evilution::Error
+    []
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:tests_list, Evilution::CLI::Commands::TestsList)

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "prism"
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/util_mutation"
+require_relative "../../config"
+require_relative "../../mutator/registry"
+require_relative "../../ast/parser"
+
+class Evilution::CLI::Commands::UtilMutation < Evilution::CLI::Command
+  private
+
+  def perform
+    source, file_path = resolve_util_mutation_source
+    subjects = parse_source_to_subjects(source, file_path)
+    config = Evilution::Config.new(**@options)
+    registry = Evilution::Mutator::Registry.default
+    operator_options = build_operator_options(config)
+    mutations = subjects.flat_map { |s| registry.mutations_for(s, operator_options: operator_options) }
+
+    if mutations.empty?
+      @stdout.puts("No mutations generated")
+      return 0
+    end
+
+    Evilution::CLI::Printers::UtilMutation.new(mutations, format: @options[:format]).render(@stdout)
+    0
+  ensure
+    @util_tmpfile.close! if @util_tmpfile
+  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
+end
+
+Evilution::CLI::Dispatcher.register(:util_mutation, Evilution::CLI::Commands::UtilMutation)

data/lib/evilution/cli/commands/version.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../../version"
+
+class Evilution::CLI::Commands::Version < Evilution::CLI::Command
+  private
+
+  def perform
+    @stdout.puts(Evilution::VERSION)
+    0
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:version, Evilution::CLI::Commands::Version)

data/lib/evilution/cli/commands.rb

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

data/lib/evilution/cli/dispatcher.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Evilution::CLI::Dispatcher
+  @commands = {}
+
+  class << self
+    def register(symbol, klass)
+      @commands[symbol] = klass
+    end
+
+    def lookup(symbol)
+      @commands.fetch(symbol) { raise KeyError, "unknown command: #{symbol.inspect}" }
+    end
+
+    def registered?(symbol)
+      @commands.key?(symbol)
+    end
+
+    private
+
+    attr_reader :commands
+  end
+end

data/lib/evilution/cli/parsed_args.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class Evilution::CLI
+  ParsedArgs = Struct.new(
+    :command, :options, :files, :line_ranges, :stdin_error, :parse_error,
+    keyword_init: true
+  ) do
+    def initialize(command:, options: {}, files: [], line_ranges: {}, stdin_error: nil, parse_error: nil)
+      super
+    end
+  end
+end