evilution 0.23.0 → 0.25.0

data/README.md

@@ -27,6 +27,8 @@ Or standalone: `gem install evilution`
 evilution [command] [options] [files...]
 ```
 
+The shorter alias `evil` ships alongside `evilution` and accepts identical arguments (handy with `alias be='bundle exec'` → `be evil run ...`).
+
 ### Commands
 
 | Command              | Description                                        | Default |
@@ -42,6 +44,7 @@ evilution [command] [options] [files...]
 | `session gc --older-than D` | Garbage-collect sessions older than D (e.g. 30d) |         |
 | `util mutation`      | Preview mutations for a file or inline code         |         |
 | `environment show`   | Display runtime environment and settings            |         |
+| `compare --against A --current B` | Compare two saved session JSON files into fixed / new / persistent / flaky / reintroduced buckets |         |
 
 ### Options (for `run` command)
 
@@ -53,6 +56,9 @@ evilution [command] [options] [files...]
 | `--min-score FLOAT`          | Float   | 0.0          | Minimum mutation score (0.0–1.0) to pass.         |
 | `--spec FILES`               | Array   | _(none)_     | Spec files to run (comma-separated). Defaults to auto-detection via `SpecResolver`. |
 | `--spec-dir DIR`             | String  | _(none)_     | Include all `*_spec.rb` files in DIR recursively. Composable with `--spec`. |
+| `--spec-pattern GLOB`        | String  | _(none)_     | Restrict resolved spec candidates to files matching GLOB (e.g. `spec/models/**/*_spec.rb`). |
+| `--no-example-targeting`     | Boolean | _(enabled)_  | Disable per-mutation example targeting (always run every example in the resolved spec file). Example targeting scans each example body for symbols from the mutated method and runs only the matching subset. |
+| `--example-targeting-fallback MODE` | String | `full_file` | Behavior when no example matches: `full_file` (run the whole spec file) or `unresolved` (skip the mutation as `:unresolved`). |
 | `-j`, `--jobs N`             | Integer | 1            | Number of parallel workers. Uses demand-driven work distribution with pipe-based IPC. |
 | `--no-baseline`              | Boolean | _(enabled)_  | Skip baseline test suite check. By default, a baseline run detects pre-existing failures and marks those mutations as `neutral`. |
 | `--fail-fast [N]`            | Integer | _(none)_     | Stop after N surviving mutants (default 1 if no value given). |
@@ -69,6 +75,7 @@ evilution [command] [options] [files...]
 | `--no-preload`               | Boolean | _(enabled)_  | Disable parent-process preload.                     |
 | `--skip-heredoc-literals`    | Boolean | false        | Skip all string literal mutations inside heredocs.  |
 | `--show-disabled`            | Boolean | false        | Report mutations skipped by `# evilution:disable` comments. |
+| `--fallback-full-suite`      | Boolean | false        | When no matching spec/test resolves for a mutation, run the whole test suite instead of marking it `:unresolved` and skipping. |
 | `--baseline-session PATH`    | String  | _(none)_     | Saved session file for HTML report comparison.     |
 | `-e CODE`, `--eval CODE`     | String  | _(none)_     | Inline Ruby code for `util mutation` command.      |
 
@@ -100,6 +107,9 @@ Creates `.evilution.yml`:
 # baseline_session: null   # path to session file for HTML comparison
 # ignore_patterns: []      # AST patterns to exclude (see docs/ast_pattern_syntax.md)
 # progress: true           # TTY progress bar
+# example_targeting: true  # per-mutation example targeting via body-token scan
+# example_targeting_fallback: full_file  # full_file | unresolved
+# spec_pattern: null       # restrict resolved spec candidates to files matching GLOB
 ```
 
 **Precedence**: CLI flags override `.evilution.yml` values.
@@ -141,7 +151,11 @@ Use `--format json` for machine-readable output. Schema:
     "survived": "integer — mutations NOT detected (test passed = gap in coverage)",
     "timed_out": "integer — mutations that exceeded timeout",
     "errors": "integer   — mutations that caused unexpected errors",
-    "score": "float      — killed / (total - errors), range 0.0-1.0, rounded to 4 decimals",
+    "neutral": "integer  — mutations whose tests already failed before mutation (baseline failure)",
+    "equivalent": "integer — mutations proven to have identical behavior to the original",
+    "unresolved": "integer — mutations where no spec file resolved (coverage gap, not a failure)",
+    "unparseable": "integer — mutations whose mutated source did not parse (short-circuited, never executed)",
+    "score": "float      — killed / (total - errors - neutral - equivalent - unresolved - unparseable), range 0.0-1.0, rounded to 4 decimals",
     "duration": "float   — total wall-clock seconds, rounded to 4 decimals",
     "peak_memory_mb": "float (optional) — peak RSS across all mutation child processes, in MB"
   },
@@ -150,9 +164,10 @@ Use `--format json` for machine-readable output. Schema:
       "operator": "string — mutation operator name (see Operators table)",
       "file": "string    — relative path to mutated file",
       "line": "integer   — line number of the mutation",
-      "status": "string  — result status: 'survived', 'killed', 'timeout', or 'error'",
+      "status": "string  — result status: 'survived', 'killed', 'timeout', 'error', 'neutral', 'equivalent', 'unresolved', or 'unparseable'",
       "duration": "float — seconds this mutation took, rounded to 4 decimals",
-      "diff": "string    — unified diff snippet",
+      "diff": "string    — legacy +/- diff snippet",
+      "unified_diff": "string (optional, survived only) — git-style unified diff with `--- a/file`, `+++ b/file`, `@@` hunk header and sdiff body; omitted when source slices are unavailable",
       "suggestion": "string — actionable hint for surviving mutants (survived only)"
     }
   ],
@@ -167,6 +182,10 @@ Use `--format json` for machine-readable output. Schema:
     }
   ],
   "killed": ["... same shape as survived entries ..."],
+  "neutral": ["... same shape as survived entries ..."],
+  "equivalent": ["... same shape as survived entries ..."],
+  "unresolved": ["... same shape as survived entries — coverage gap: no spec file resolved for these mutations"],
+  "unparseable": ["... same shape as survived entries — mutated source failed to parse and was never executed"],
   "timed_out": ["... same shape as survived entries ..."],
   "errors": [
     {
@@ -181,6 +200,21 @@ Use `--format json` for machine-readable output. Schema:
 
 **Key metric**: `summary.score` — the mutation score. Higher is better. 1.0 means all mutations were caught.
 
+### Mutation Statuses
+
+| Status       | Meaning                                                               | Counted in score? |
+|--------------|-----------------------------------------------------------------------|-------------------|
+| `killed`     | A test failed when the mutation was applied — test suite caught it    | numerator + denominator |
+| `survived`   | No test failed — gap in coverage                                       | denominator only  |
+| `timeout`    | Test run exceeded `--timeout` — treated like survived for scoring     | denominator only  |
+| `error`      | Mutation caused an unexpected error (syntax error, boot failure, etc.) | excluded from denominator |
+| `neutral`    | Baseline tests already failed before mutation — not a meaningful signal | excluded          |
+| `equivalent` | Mutation is provably identical to the original (e.g. no-op replacement) | excluded          |
+| `unresolved` | No spec file resolved for the mutated source — **coverage gap, not a failure**. Use `--fallback-full-suite` to run the full suite instead. | excluded |
+| `unparseable` | Mutated source failed to parse (e.g. dangling heredoc opener after `method_body_replacement`). Short-circuited — never executed. | excluded |
+
+Unresolved mutations indicate a missing test mapping — the file has no corresponding test file that the resolver could find (for example, an RSpec `_spec.rb` file or a Minitest `_test.rb` file, depending on configuration). They are reported separately so you can act on them (add a test, adjust test naming, or opt in to the full-suite fallback) without inflating the error count.
+
 ## Mutation Operators (72 total)
 
 Each operator name is stable and appears in JSON output under `survived[].operator`.
@@ -313,7 +347,7 @@ Unlike `evilution --format json`, every survived entry returned by `evilution-mu
 | `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.
+These fields are added in addition to the existing `operator`, `file`, `line`, `diff`, `unified_diff`, `suggestion`, and `test_command` so agents can triage survivors in one pass.
 
 ### Concrete Test Suggestions
 
@@ -418,6 +452,49 @@ bundle exec evilution run lib/ --format json --min-score 0.8 --quiet
 
 Note: `--quiet` suppresses all stdout output (including JSON). Use it in CI only when you care about the exit code and do not need JSON output.
 
+### 9. Regression tracking across runs (`compare`)
+
+```bash
+bundle exec evilution run lib/ --format json --save-session
+# later, after edits:
+bundle exec evilution run lib/ --format json --save-session
+
+bundle exec evilution compare \
+  --against .evilution/results/<earlier>.json \
+  --current  .evilution/results/<later>.json \
+  --format json
+```
+
+Output buckets:
+
+| Bucket          | Meaning |
+|-----------------|---------|
+| `fixed`         | Survived previously, killed now — the new test actually landed |
+| `new`           | Did not exist previously, surviving now — a fresh gap |
+| `persistent`    | Survived in both runs — carry-over debt |
+| `reintroduced`  | Killed previously, survived now — regression |
+| `flaky`         | Status flipped and back — unstable test |
+
+Use in CI to gate merges on `reintroduced` being empty, or to surface `new` survivors for reviewer attention without failing the build on `persistent` debt.
+
+## Parallel Runs with SQLite
+
+Running with `-j N` forks worker processes. If your Rails app uses SQLite, every worker opens the same `db/test.sqlite3` file, and concurrent writers collide on the database-level lock. Symptoms: `ActiveRecord::StatementTimeout`, `SQLite3::BusyException`, and slow runs. Evilution classifies these crashes as `:neutral` (see [EV-toid / #814](https://github.com/taxdome/evilution/issues/814)) so the mutation score is not polluted, but the wall-clock penalty remains.
+
+Evilution follows the [`parallel_tests`](https://github.com/grosser/parallel_tests) convention: each worker receives a `TEST_ENV_NUMBER` environment variable (`""` for worker 1, `"2"` for worker 2, `"3"` for worker 3, …). Interpolate it into `config/database.yml` so each worker gets its own SQLite file:
+
+```yaml
+test:
+  adapter: sqlite3
+  database: db/test<%= ENV['TEST_ENV_NUMBER'] %>.sqlite3
+  pool: 5
+  timeout: 5000
+```
+
+After the first `jobs > 1` run, each worker creates its own file (`db/test.sqlite3`, `db/test2.sqlite3`, …). Seed each with `rake db:test:prepare` before running Evilution, or ensure your preload sets up schema on connect.
+
+When Evilution detects a parallel run against a SQLite-backed `config/database.yml`, it prints a one-time startup warning pointing to this section.
+
 ## Development
 
 ### Memory leak check

data/exe/evil

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "evilution"
+
+exit Evilution::CLI.new(ARGV).call

data/lib/evilution/ast/source_surgeon.rb

@@ -1,11 +1,25 @@
 # frozen_string_literal: true
 
+require "prism"
+
 require_relative "../ast"
 
 module Evilution::AST::SourceSurgeon
+  Result = Struct.new(:source, :status, keyword_init: true) do
+    def ok?
+      status == :ok
+    end
+
+    def unparseable?
+      status == :unparseable
+    end
+  end
+
   def self.apply(source, offset:, length:, replacement:)
     binary = source.b
     binary[offset, length] = replacement.b
-    binary.force_encoding(source.encoding)
+    mutated = binary.force_encoding(source.encoding)
+    status = Prism.parse(mutated).success? ? :ok : :unparseable
+    Result.new(source: mutated, status: status).freeze
   end
 end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../commands"
+require_relative "../command"
+require_relative "../dispatcher"
+require_relative "../printers/compare"
+require_relative "../../compare"
+require_relative "../../compare/categorizer"
+require_relative "../../compare/detector"
+require_relative "../../compare/normalizer"
+
+class Evilution::CLI::Commands::Compare < Evilution::CLI::Command
+  SUPPORTED_FORMATS = %i[json text].freeze
+
+  private
+
+  def perform
+    paths = resolve_paths
+    raise Evilution::ConfigError, "exactly two file paths required for compare" unless paths.length == 2
+
+    fmt = @options[:format] || :json
+    raise Evilution::ConfigError, "compare supports --format text or json, got #{fmt.inspect}" unless SUPPORTED_FORMATS.include?(fmt)
+
+    against = load_and_normalize(paths[0])
+    current = load_and_normalize(paths[1])
+    buckets = Evilution::Compare::Categorizer.call(against, current)
+    Evilution::CLI::Printers::Compare.new(buckets, format: fmt).render(@stdout)
+    0
+  end
+
+  # Flags bind to roles (--against -> slot 0, --current -> slot 1);
+  # positional @files fill whatever role the flags didn't claim, in order.
+  # Extra positional args after both slots are filled are a user error.
+  def resolve_paths
+    positional = @files.dup
+    against = @options[:against] || positional.shift
+    current = @options[:current] || positional.shift
+
+    raise Evilution::ConfigError, "exactly two file paths required for compare" unless positional.empty?
+
+    [against, current].compact
+  end
+
+  def load_and_normalize(path)
+    raise Evilution::Error, "file not found: #{path}" unless File.exist?(path)
+
+    json = JSON.parse(File.read(path))
+    tool = Evilution::Compare::Detector.call(json)
+    normalize(json, tool)
+  rescue ::JSON::ParserError => e
+    raise Evilution::Error, "invalid JSON in #{path}: #{e.message}"
+  rescue Evilution::Compare::InvalidInput => e
+    raise Evilution::Error, "#{path}: #{e.message}"
+  rescue SystemCallError => e
+    raise Evilution::Error, e.message
+  end
+
+  def normalize(json, tool)
+    normalizer = Evilution::Compare::Normalizer.new
+    case tool
+    when :mutant    then normalizer.from_mutant(json)
+    when :evilution then normalizer.from_evilution(json)
+    end
+  end
+end
+
+Evilution::CLI::Dispatcher.register(:compare, Evilution::CLI::Commands::Compare)

data/lib/evilution/cli/parser/command_extractor.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class Evilution::CLI::Parser::CommandExtractor
+  SIMPLE_COMMANDS = {
+    "version" => :version,
+    "init" => :init,
+    "mcp" => :mcp,
+    "subjects" => :subjects,
+    "compare" => :compare
+  }.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
+
+  Result = Struct.new(:command, :remaining_argv, :parse_error)
+
+  def self.call(argv)
+    new(argv).call
+  end
+
+  def initialize(argv)
+    @argv = argv.dup
+    @command = :run
+    @parse_error = nil
+  end
+
+  def call
+    extract
+    Result.new(@command, @argv, @parse_error)
+  end
+
+  private
+
+  def extract
+    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
+end

data/lib/evilution/cli/parser/file_args.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Evilution::CLI::Parser::FileArgs
+  module_function
+
+  def parse(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 expand_spec_dir(dir)
+    unless File.directory?(dir)
+      warn("Error: #{dir} is not a directory")
+      return []
+    end
+
+    Dir.glob(File.join(dir, "**/*_spec.rb"))
+  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
+end

data/lib/evilution/cli/parser/options_builder.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../../version"
+require_relative "file_args"
+
+class Evilution::CLI::Parser::OptionsBuilder
+  def self.build(options)
+    new(options).build
+  end
+
+  def initialize(options)
+    @options = options
+  end
+
+  def build
+    OptionParser.new do |opts|
+      opts.banner = "Usage: evilution [command] [options] [files...]"
+      opts.version = Evilution::VERSION
+      add_separators(opts)
+      add_core_options(opts)
+      add_filter_options(opts)
+      add_flag_options(opts)
+      add_extra_flag_options(opts)
+      add_session_options(opts)
+      add_compare_options(opts)
+    end
+  end
+
+  private
+
+  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}, compare, mcp, version"
+    opts.separator ""
+    opts.separator "Options:"
+  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("--spec-pattern GLOB",
+            "Restrict resolved spec candidates to files matching GLOB") { |p| @options[:spec_pattern] = p }
+    opts.on("--no-example-targeting",
+            "Disable per-mutation example targeting (run all examples in resolved spec files)") do
+      @options[:example_targeting] = false
+    end
+    opts.on("--example-targeting-fallback MODE", %w[full_file unresolved],
+            "Fallback when example targeting finds no match: full_file (default) or unresolved") do |m|
+      @options[:example_targeting_fallback] = m
+    end
+    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 }
+  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("--fallback-full-suite", "Run the whole test suite when no matching spec/test resolves " \
+                                     "for a mutation (default: mark the mutation :unresolved and skip)") do
+      @options[:fallback_to_full_suite] = 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 add_compare_options(opts)
+    opts.on("--against PATH", "Prior mutation run to compare against (used with `compare` command)") do |p|
+      @options[:against] = p
+    end
+    opts.on("--current PATH", "Current mutation run to compare (used with `compare` command)") do |p|
+      @options[:current] = p
+    end
+  end
+
+  def expand_spec_dir(dir)
+    specs = Evilution::CLI::Parser::FileArgs.expand_spec_dir(dir)
+    @options[:spec_files] = Array(@options[:spec_files]) + specs
+  end
+end

data/lib/evilution/cli/parser/stdin_reader.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "file_args"
+
+class Evilution::CLI::Parser::StdinReader
+  Result = Struct.new(:files, :ranges, :error)
+
+  def self.call(io, existing_files:)
+    new(io, existing_files: existing_files).call
+  end
+
+  def initialize(io, existing_files:)
+    @io = io
+    @existing_files = existing_files
+  end
+
+  def call
+    return Result.new([], {}, "--stdin cannot be combined with positional file arguments") if @existing_files.any?
+
+    lines = []
+    @io.each_line do |line|
+      line = line.strip
+      lines << line unless line.empty?
+    end
+    files, ranges = Evilution::CLI::Parser::FileArgs.parse(lines)
+    Result.new(files, ranges, nil)
+  end
+end