evilution 0.24.0 → 0.25.0

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

@@ -5,7 +5,8 @@ class Evilution::CLI::Parser::CommandExtractor
     "version" => :version,
     "init" => :init,
     "mcp" => :mcp,
-    "subjects" => :subjects
+    "subjects" => :subjects,
+    "compare" => :compare
   }.freeze
 
   SESSION_SUBCOMMANDS = {

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

@@ -23,6 +23,7 @@ class Evilution::CLI::Parser::OptionsBuilder
       add_flag_options(opts)
       add_extra_flag_options(opts)
       add_session_options(opts)
+      add_compare_options(opts)
     end
   end
 
@@ -33,7 +34,7 @@ class Evilution::CLI::Parser::OptionsBuilder
     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 "         util {mutation}, environment {show}, compare, mcp, version"
     opts.separator ""
     opts.separator "Options:"
   end
@@ -48,6 +49,16 @@ class Evilution::CLI::Parser::OptionsBuilder
     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|
@@ -96,6 +107,15 @@ class Evilution::CLI::Parser::OptionsBuilder
     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

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

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

data/lib/evilution/cli.rb

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

data/lib/evilution/compare/categorizer.rb

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

data/lib/evilution/compare/detector.rb

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

data/lib/evilution/compare/fingerprint.rb

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

data/lib/evilution/compare/normalizer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+require_relative "record"
+require_relative "fingerprint"
+
+class Evilution::Compare::Normalizer
+  EVILUTION_BUCKETS = %w[killed survived timed_out errors neutral equivalent unresolved unparseable].freeze
+  EVILUTION_STATUS_MAP = {
+    "killed" => :killed,
+    "survived" => :survived,
+    "timeout" => :timeout,
+    "error" => :error,
+    "neutral" => :neutral,
+    "equivalent" => :equivalent,
+    "unresolved" => :unresolved,
+    "unparseable" => :unparseable
+  }.freeze
+
+  def from_evilution(json)
+    records = []
+    EVILUTION_BUCKETS.each do |bucket|
+      Array(json[bucket]).each do |entry|
+        records << build_evilution_record(entry, index: records.size)
+      end
+    end
+    records
+  end
+
+  def from_mutant(json)
+    records = []
+    Array(json["subject_results"]).each do |subject|
+      source_path = subject["source_path"] or
+        raise Evilution::Compare::InvalidInput.new("missing 'source_path' on subject", index: records.size)
+      Array(subject["coverage_results"]).each do |cov|
+        records << build_mutant_record(cov, source_path: source_path, index: records.size)
+      end
+    end
+    records
+  end
+
+  private
+
+  def build_evilution_record(entry, index:)
+    file_path = entry["file"] or raise Evilution::Compare::InvalidInput.new("missing 'file' in record", index: index)
+    line = entry["line"] or raise Evilution::Compare::InvalidInput.new("missing 'line' in record", index: index)
+    diff = entry["diff"].to_s
+    status = EVILUTION_STATUS_MAP[entry["status"]] ||
+             raise(Evilution::Compare::InvalidInput.new("unknown status #{entry["status"].inspect}", index: index))
+    body = Evilution::Compare::Fingerprint.extract_from_evilution_diff(diff)
+    Evilution::Compare::Record.new(
+      source: :evilution,
+      file_path: file_path,
+      line: line,
+      status: status,
+      fingerprint: Evilution::Compare::Fingerprint.compute(file_path: file_path, line: line, body: body),
+      operator: entry["operator"],
+      diff_body: diff,
+      raw: entry
+    )
+  end
+
+  def build_mutant_record(cov, source_path:, index:)
+    mr = cov["mutation_result"] or raise Evilution::Compare::InvalidInput.new("missing mutation_result", index: index)
+    cr = cov["criteria_result"] or raise Evilution::Compare::InvalidInput.new("missing criteria_result", index: index)
+    ident = mr["mutation_identification"].to_s
+    line = parse_mutant_line(ident, index)
+    diff = mr["mutation_diff"].to_s
+    status = derive_mutant_status(mr, cr, index)
+    body = Evilution::Compare::Fingerprint.extract_from_mutant_diff(diff)
+    Evilution::Compare::Record.new(
+      source: :mutant,
+      file_path: source_path,
+      line: line,
+      status: status,
+      fingerprint: Evilution::Compare::Fingerprint.compute(file_path: source_path, line: line, body: body),
+      operator: nil,
+      diff_body: diff,
+      raw: { "mutation_result" => mr, "criteria_result" => cr, "source_path" => source_path }
+    )
+  end
+
+  # mutant_identification format: <type>:<subject>:<path>:<line>:<sha1[0..4]>.
+  # Line is always the second-to-last colon-separated field. Works with paths
+  # containing colons (e.g. Windows drive letters) because we index from the
+  # right, but a malformed path-less identification will raise InvalidInput.
+  def parse_mutant_line(ident, index)
+    parts = ident.split(":")
+    raise Evilution::Compare::InvalidInput.new("cannot parse line from #{ident.inspect}", index: index) if parts.length < 5
+
+    Integer(parts[-2])
+  rescue ArgumentError
+    raise Evilution::Compare::InvalidInput.new("non-integer line in #{ident.inspect}", index: index)
+  end
+
+  def derive_mutant_status(mr, cr, index)
+    type = mr["mutation_type"]
+    return :neutral if %w[neutral noop].include?(type)
+    return :timeout if cr["timeout"]
+    return :error   if cr["process_abort"]
+    return :killed  if cr["test_result"]
+    return :survived if type == "evil"
+
+    raise Evilution::Compare::InvalidInput.new("unknown mutant result shape: type=#{type.inspect} cr=#{cr.inspect}", index: index)
+  end
+end

data/lib/evilution/compare/record.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+
+module Evilution::Compare
+  Record = Data.define(
+    :source,
+    :file_path,
+    :line,
+    :status,
+    :fingerprint,
+    :operator,
+    :diff_body,
+    :raw
+  )
+end

data/lib/evilution/compare.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/OneClassPerFile
+module Evilution::Compare
+end
+
+class Evilution::Compare::InvalidInput < StandardError
+  attr_reader :index
+
+  def initialize(message, index: nil)
+    super(message)
+    @index = index
+  end
+end
+# rubocop:enable Style/OneClassPerFile