mutaruby 0.1.0

data/lib/mutaruby/command.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+module Mutaruby
+  # Runs the user's test command once, in a fresh process (a new shell and everything it starts), inside a sandbox.
+  # Exit status 0 means the tests passed. A run that exceeds the timeout is killed together with its whole process group.
+  class Command
+    Result = Struct.new(:status, :exitstatus, :seconds, :output, keyword_init: true) do
+      def passed? = status == :passed
+      def timeout? = status == :timeout
+    end
+
+    OUTPUT_TAIL = 4000
+
+    def initialize(command, root:, env: {})
+      @command = command
+      @root = File.expand_path(root)
+      @env = env
+      @live = {}
+      @lock = Mutex.new
+    end
+
+    # Kills every run still in progress (used when mutaruby itself is interrupted: the runs live in their own process
+    # groups, so a Ctrl-C in the terminal does not reach them).
+    def kill_all
+      pids = @lock.synchronize { @live.keys }
+      pids.each { |pid| kill_group(pid) }
+    end
+
+    # dir: sandbox project dir. timeout: seconds (nil = none). capture: keep an output tail (for the baseline report).
+    def run(dir, timeout: nil, env: {}, capture: false)
+      log = capture ? Tempfile.new('mutaruby-out') : nil
+      out = log ? log.path : File::NULL
+      started = monotonic
+      pid = Process.spawn(child_env(dir).merge(@env).merge(env), '/bin/sh', '-c', @command,
+                          chdir: dir, pgroup: true, in: File::NULL, out: out, err: out)
+      @lock.synchronize { @live[pid] = true }
+      waiter = Process.detach(pid)
+      timed_out = waiter.join(timeout).nil? if timeout
+      if timed_out
+        kill_group(pid)
+        waiter.join
+      end
+      st = waiter.value
+      @lock.synchronize { @live.delete(pid) }
+      status = if timed_out then :timeout
+               elsif st.success? then :passed
+               else :failed
+               end
+      Result.new(status: status, exitstatus: st.exitstatus, seconds: monotonic - started,
+                 output: log ? tail(log.path) : nil)
+    ensure
+      log&.close!
+    end
+
+    private
+
+    # Bundler exports the ORIGINAL Gemfile path to child processes. Left as is, `bundle exec` in the sandbox would
+    # resolve the Gemfile (and a `gemspec` line's lib/ directory) from the user's checkout and test the unmutated code.
+    def child_env(dir)
+      # The per-mutant variables are always set or cleared explicitly, so a mutaruby run nested inside another one's
+      # test command does not inherit the outer run's mutant id.
+      env = { 'MUTARUBY' => '1', 'MUTARUBY_MUTANT_ID' => nil, 'MUTARUBY_FILE' => nil }
+      %w[BUNDLE_GEMFILE BUNDLE_APP_CONFIG].each do |k|
+        v = ENV.fetch(k, nil)
+        next unless v
+
+        full = File.expand_path(v)
+        env[k] = full.start_with?("#{@root}/") ? File.join(dir, full.delete_prefix("#{@root}/")) : v
+      end
+      env
+    end
+
+    def kill_group(pid)
+      Process.kill('TERM', -pid)
+      deadline = monotonic + 2
+      sleep 0.05 while monotonic < deadline && alive?(pid)
+      Process.kill('KILL', -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def alive?(pid)
+      Process.kill(0, -pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def tail(path)
+      s = File.binread(path)
+      s = s[-OUTPUT_TAIL..] if s.bytesize > OUTPUT_TAIL
+      s.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/mutaruby/generator.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require_relative 'parsing'
+require_relative 'mutation'
+require_relative 'splicer'
+
+module Mutaruby
+  # Walks a file's AST (the `parser` gem) and produces every mutant of it. Each mutant is ONE splice of the original
+  # source at the character offsets of an AST node (or of one of its tokens), so comments, formatting and the rest of
+  # the file are untouched. Mutants that no longer parse, and mutants whose text equals an earlier one, are dropped.
+  class Generator
+    # Operator id => one-line description. The README documents each with an example.
+    OPERATORS = {
+      'arithmetic' => 'swap + - * / % ** (a + b -> a - b, a * b -> a / b, a % b -> a * b, a ** b -> a * b)',
+      'comparison' => 'boundary / equality swaps (== <-> !=, < -> <=, <= -> <, > -> >=, >= -> >, <=> -> ==, === -> !=, =~ <-> !~)',
+      'bitwise' => 'swap & | ^ << >> (a & b -> a | b, a << b -> a >> b)',
+      'logical-swap' => '&& <-> ||, and <-> or',
+      'logical-drop-left' => 'a && b -> b, a || b -> b',
+      'logical-drop-right' => 'a && b -> a, a || b -> a',
+      'negation-removal' => '!x -> x, not x -> x',
+      'unary-minus-removal' => '-x -> x',
+      'condition-negate' => 'if c / unless c / c ? a : b: c -> !(c)',
+      'condition-true' => 'if c: c -> true',
+      'condition-false' => 'if c: c -> false',
+      'loop-condition-negate' => 'while c / until c: c -> !(c)',
+      'loop-condition-false' => 'while c: c -> false',
+      'literal-int' => 'n -> n + 1, n - 1, 0, 1 (each distinct value once)',
+      'literal-float' => 'x -> 0.0, x + 1.0',
+      'literal-string' => '"abc" -> "", "" -> "mutaruby"',
+      'literal-symbol' => ':sym -> :__mutaruby__',
+      'literal-boolean' => 'true <-> false',
+      'literal-nil' => 'nil -> true',
+      'literal-array' => '[a, b] -> []',
+      'literal-hash' => '{ k => v } -> {}',
+      'range-swap' => 'a..b <-> a...b',
+      'return-nil' => 'return x -> return nil',
+      'method-body-nil' => 'def m; body; end -> def m; nil; end',
+      'method-body-bool' => 'def m?; body; end -> true / false (predicate methods only)',
+      'statement-delete' => 'one statement of a multi-statement body -> nil',
+      'argument-removal' => 'f(a, b) -> f(b), f(a) (one argument removed at a time)',
+      'call-to-receiver' => 'recv.m(args) -> recv',
+      'call-to-argument' => 'recv.m(a, ...) -> a',
+      'predicate-true' => 'x.m? -> true',
+      'predicate-false' => 'x.m? -> false',
+      'safe-navigation' => 'a&.m -> a.m',
+      'raise-removal' => 'raise X -> nil (also fail)',
+      'op-assign' => 'swap compound assignment (+= <-> -=, *= <-> /=, |= <-> &=, <<= <-> >>=)',
+      'or-assign' => 'a ||= b -> a = b',
+      'and-assign' => 'a &&= b -> a = b'
+    }.freeze
+
+    SWAPS = {
+      'arithmetic' => { :+ => :-, :- => :+, :* => :/, :/ => :*, :% => :*, :** => :* },
+      'comparison' => { :== => :!=, :!= => :==, :< => :<=, :<= => :<, :> => :>=, :>= => :>, :<=> => :==,
+                        :=== => :!=, :=~ => :!~, :!~ => :=~ },
+      'bitwise' => { :& => :|, :| => :&, :^ => :&, :<< => :>>, :>> => :<< }
+    }.freeze
+    OP_ASSIGN = { :+ => :-, :- => :+, :* => :/, :/ => :*, :| => :&, :& => :|, :<< => :>>, :>> => :<< }.freeze
+
+    # Calls that are declarations, not computations: their arguments are never removed and their string arguments are
+    # never emptied (a mutant of `require 'json'` that requires "" is noise, not a test gap).
+    DECLARATIONS = %i[require require_relative load autoload attr_reader attr_writer attr_accessor include extend prepend
+                      private public protected module_function private_constant public_constant
+                      private_class_method public_class_method define_method alias_method raise fail].freeze
+    VISIBILITY = %i[private public protected module_function].freeze
+    # Definitions are not deleted as statements: deleting a whole class or method is caught by any test that touches
+    # it, and the interesting mutants are inside (method-body-nil and the operators on the body).
+    STRUCTURAL = %i[module class sclass def defs].freeze
+    PREDICATE_SKIP = %i[block_given? frozen? respond_to? respond_to_missing? nil?].freeze
+    DISABLE_MARK = 'mutaruby:disable'
+
+    attr_reader :errors
+
+    # path: file path for messages; rel: path relative to the project root (stored on the mutants).
+    def initialize(source, path:, rel: path, operators: nil)
+      @src = source
+      @path = path
+      @rel = rel
+      @operators = operators # nil = all, else a Set of ids
+      @valid_encoding = source.valid_encoding?
+      @lines = @valid_encoding ? source.split("\n", -1) : []
+      @occurrence = occurrence_index(@lines)
+      @errors = []
+    end
+
+    def mutations
+      @mutations ||= build
+    end
+
+    private
+
+    def build
+      unless @valid_encoding
+        @errors << "#{@path}: cannot parse (not valid #{@src.encoding}); skipped"
+        return []
+      end
+      ast = Parsing.parse(@path, @src)
+      @out = []
+      @seen = {}
+      @scope = []  # namespace names ("Foo", "Bar")
+      @meth = []   # enclosing method names, qualified
+      @singleton = 0
+      walk(ast, nil) if ast
+      @out.each_with_index { |m, i| m.id = i }
+      @out
+    rescue Parser::SyntaxError, EncodingError, ArgumentError => e
+      @errors << "#{@path}: cannot parse (#{e.message}); skipped"
+      []
+    end
+
+    def occurrence_index(lines)
+      seen = Hash.new(0)
+      lines.each_with_index.to_h { |l, i| [i + 1, seen[l.strip] += 1] }
+    end
+
+    def enabled?(op)
+      @operators.nil? || @operators.include?(op)
+    end
+
+    # Splices `repl` over `range` (a Parser::Source::Range) and records the mutant if it is new and still parses.
+    def add(range, repl, op)
+      return unless enabled?(op)
+
+      orig = range.source
+      return if orig == repl
+
+      lineno = range.line
+      line = @lines[lineno - 1].to_s
+      return if line.include?(DISABLE_MARK)
+
+      text = Splicer.splice(@src, range.begin_pos, range.end_pos, orig, repl)
+      return if @seen[text]
+
+      @seen[text] = true
+      return unless Parsing.valid?(@path, text)
+
+      @out << Mutation.new(file: @rel, operator: op, orig: orig, repl: repl, lineno: lineno, line_text: line.strip,
+                           occurrence: @occurrence[lineno], method: @meth.last, text: text)
+    end
+
+    def declaration?(node)
+      node&.type == :send && DECLARATIONS.include?(node.children[1])
+    end
+
+    def src_of(node)
+      node.loc.expression.source
+    end
+
+    def walk(node, parent)
+      return unless node.is_a?(Parser::AST::Node)
+
+      case node.type
+      when :module, :class
+        visit(node, parent)
+        @scope.push(src_of(node.children[0]))
+        node.children.each { |c| walk(c, node) }
+        @scope.pop
+      when :sclass
+        visit(node, parent)
+        @singleton += 1
+        node.children.each { |c| walk(c, node) }
+        @singleton -= 1
+      when :def, :defs
+        @meth.push(qualified(node))
+        visit(node, parent)
+        node.children.each { |c| walk(c, node) }
+        @meth.pop
+      else
+        visit(node, parent)
+        node.children.each { |c| walk(c, node) }
+      end
+    end
+
+    def qualified(node)
+      ns = @scope.join('::')
+      if node.type == :defs
+        "#{ns.empty? ? src_of(node.children[0]) : ns}.#{node.children[1]}"
+      elsif @singleton.positive?
+        "#{ns}.#{node.children[0]}"
+      else
+        ns.empty? ? node.children[0].to_s : "#{ns}##{node.children[0]}"
+      end
+    end
+
+    def visit(n, parent)
+      case n.type
+      when :send, :csend then visit_send(n, parent)
+      when :and, :or then visit_logical(n)
+      when :if then visit_if(n)
+      when :while, :until, :while_post, :until_post then visit_loop(n)
+      when :int then visit_int(n)
+      when :float then visit_float(n)
+      when :str then visit_str(n, parent)
+      when :sym
+        add(n.loc.expression, ':__mutaruby__', 'literal-symbol') if n.loc.expression.source.match?(/\A:[A-Za-z_]\w*[?!=]?\z/) &&
+                                                                    !declaration?(parent)
+      when :true then add(n.loc.expression, 'false', 'literal-boolean')
+      when :false then add(n.loc.expression, 'true', 'literal-boolean')
+      when :nil then add(n.loc.expression, 'true', 'literal-nil')
+      when :array
+        add(n.loc.expression, '[]', 'literal-array') if n.children.any? && n.loc.begin&.source == '['
+      when :hash
+        add(n.loc.expression, '{}', 'literal-hash') if n.children.any? && n.loc.begin&.source == '{'
+      when :irange, :erange
+        # an endless range (a..) means the same with either operator
+        add(n.loc.operator, n.type == :irange ? '...' : '..', 'range-swap') unless n.children[1].nil?
+      when :return
+        add(n.loc.expression, 'return nil', 'return-nil') if n.children.any?
+      when :op_asgn
+        sw = OP_ASSIGN[n.children[1]]
+        add(n.loc.operator, "#{sw}=", 'op-assign') if sw
+      when :or_asgn then add(n.loc.operator, '=', 'or-assign')
+      when :and_asgn then add(n.loc.operator, '=', 'and-assign')
+      when :begin, :kwbegin then visit_body(n)
+      when :def, :defs then visit_def(n)
+      end
+    end
+
+    def visit_send(n, parent)
+      recv, meth, *args = *n
+      sel = n.loc.selector
+      SWAPS.each do |op, table|
+        add(sel, table[meth].to_s, op) if table.key?(meth) && recv && args.size == 1 && sel
+      end
+      if meth == :! && recv
+        add(n.loc.expression, src_of(recv), 'negation-removal')
+      elsif meth == :-@ && recv
+        add(n.loc.expression, src_of(recv), 'unary-minus-removal')
+      end
+      add(n.loc.dot, '.', 'safe-navigation') if n.type == :csend && n.loc.dot
+      if recv.nil? && %i[raise fail].include?(meth)
+        add(n.loc.expression, 'nil', 'raise-removal')
+        return
+      end
+      name = meth.to_s
+      if name.end_with?('?') && !PREDICATE_SKIP.include?(meth)
+        add(n.loc.expression, 'true', 'predicate-true')
+        add(n.loc.expression, 'false', 'predicate-false')
+      end
+      plain = name.match?(/\A[a-z_]\w*[?!]?\z/) # a named method, not an operator or a writer
+      block_call = parent&.type == :block && parent.children[0].equal?(n)
+      if recv && plain && sel && !block_call
+        add(n.loc.expression, src_of(recv), 'call-to-receiver')
+        first = args.first
+        add(n.loc.expression, src_of(first), 'call-to-argument') if first && !%i[block_pass splat kwsplat hash].include?(first.type)
+      end
+      remove_arguments(n, args) if plain && !DECLARATIONS.include?(meth) && args.any? && parent&.type != :masgn
+    end
+
+    def remove_arguments(n, args)
+      return if args.size > 6
+
+      first = args.first.loc.expression
+      last = args.last.loc.expression
+      range = first.join(last)
+      args.each_index do |i|
+        rest = args.each_with_index.reject { |_, j| j == i }.map { |a, _| src_of(a) }
+        add(range, rest.join(', '), 'argument-removal')
+      end
+    end
+
+    def visit_logical(n)
+      l, r = *n
+      kw = n.loc.operator.source
+      repl = { '&&' => '||', '||' => '&&', 'and' => 'or', 'or' => 'and' }.fetch(kw)
+      add(n.loc.operator, repl, 'logical-swap')
+      add(n.loc.expression, src_of(l), 'logical-drop-right')
+      add(n.loc.expression, src_of(r), 'logical-drop-left')
+    end
+
+    def visit_if(n)
+      cond = n.children[0]
+      return unless cond.is_a?(Parser::AST::Node)
+
+      add(cond.loc.expression, "!(#{src_of(cond)})", 'condition-negate')
+      add(cond.loc.expression, 'true', 'condition-true')
+      add(cond.loc.expression, 'false', 'condition-false')
+    end
+
+    def visit_loop(n)
+      cond = n.children[0]
+      add(cond.loc.expression, "!(#{src_of(cond)})", 'loop-condition-negate')
+      add(cond.loc.expression, 'false', 'loop-condition-false') if %i[while while_post].include?(n.type)
+    end
+
+    def visit_int(n)
+      v = n.children[0]
+      [v + 1, v - 1, 0, 1].uniq.reject { |x| x == v }.each { |x| add(n.loc.expression, x.to_s, 'literal-int') }
+    end
+
+    def visit_float(n)
+      v = n.children[0]
+      add(n.loc.expression, '0.0', 'literal-float') unless v.zero?
+      add(n.loc.expression, (v + 1.0).to_s, 'literal-float') if v.finite?
+    end
+
+    def visit_str(n, parent)
+      return if parent && %i[dstr xstr dsym regexp].include?(parent.type)
+      return if declaration?(parent)
+
+      q = n.loc.respond_to?(:begin) && n.loc.begin ? n.loc.begin.source : nil
+      return unless ['"', "'"].include?(q)
+
+      if n.children[0].empty?
+        add(n.loc.expression, "#{q}mutaruby#{q}", 'literal-string')
+      else
+        add(n.loc.expression, "#{q}#{q}", 'literal-string')
+      end
+    end
+
+    def visit_body(n)
+      kids = n.children
+      return unless kids.size > 1
+
+      kids.each do |k|
+        next unless k.is_a?(Parser::AST::Node)
+        next if STRUCTURAL.include?(k.type)
+        next if k.type == :send && k.children[0].nil? && VISIBILITY.include?(k.children[1]) && k.children.size == 2
+
+        add(k.loc.expression, 'nil', 'statement-delete')
+      end
+    end
+
+    def visit_def(n)
+      body = n.children.last
+      return unless body.is_a?(Parser::AST::Node)
+
+      add(body.loc.expression, 'nil', 'method-body-nil')
+      name = n.type == :def ? n.children[0] : n.children[1]
+      return unless name.to_s.end_with?('?')
+
+      add(body.loc.expression, 'true', 'method-body-bool')
+      add(body.loc.expression, 'false', 'method-body-bool')
+    end
+  end
+end

data/lib/mutaruby/ignore_file.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Mutaruby
+  # The ignore file lists equivalent mutants: mutants that cannot be killed because they do not change behaviour.
+  #
+  # An entry names one mutation SITE, not a line number:
+  #
+  #   - file: lib/calc.rb                 # relative to the project root
+  #     operator: comparison              # operator id
+  #     line: "return 0 if n <= 0"        # the source line, whitespace-trimmed
+  #     occurrence: 2                     # Nth line with exactly that text in the file (required if it is not unique)
+  #     method: "Calc#clamp"              # optional: enclosing method
+  #     mutation: "<= => <"               # optional: narrows the entry to one change at the site
+  #     lineno: 41                        # optional hint for humans; never used for matching (it drifts)
+  #     reason: "n is never negative here"   # REQUIRED
+  #
+  # Line numbers drift whenever code above them changes, so they are a hint only. The key is the text of the line plus
+  # its occurrence among identical lines, plus the enclosing method: editing other code does not invalidate it, and
+  # editing the line itself does (the entry becomes STALE and is reported, so it gets re-reviewed).
+  class IgnoreFile
+    class Invalid < StandardError; end
+
+    Entry = Struct.new(:file, :operator, :line, :occurrence, :method, :mutation, :lineno, :reason, :index,
+                       keyword_init: true) do
+      def label
+        "##{index + 1} #{file}#{lineno ? ":#{lineno}" : ''} #{operator} #{line.inspect}" \
+          "#{occurrence ? " (occurrence #{occurrence})" : ''}#{method ? " in #{method}" : ''}"
+      end
+    end
+
+    KEYS = %w[file operator line occurrence method mutation lineno reason].freeze
+
+    attr_reader :entries, :path
+
+    def self.load(path)
+      new(YAML.safe_load(File.read(path), permitted_classes: [], aliases: false), path: path)
+    rescue Psych::SyntaxError => e
+      raise Invalid, "#{path}: not valid YAML (#{e.message})"
+    end
+
+    def initialize(data, path: '(ignore file)')
+      @path = path
+      data = data['ignore'] if data.is_a?(Hash) && data.key?('ignore')
+      data ||= []
+      raise Invalid, "#{path}: expected a list of entries" unless data.is_a?(Array)
+
+      @entries = data.each_with_index.map { |raw, i| parse_entry(raw, i) }
+    end
+
+    # Static validation against the current sources: { rel_path => source }. Returns error strings.
+    def validate(sources)
+      errs = []
+      @entries.each do |e|
+        src = sources[e.file]
+        next unless src # file not part of this run
+
+        count = src.split("\n", -1).count { |l| l.strip == e.line }
+        if count.zero?
+          errs << "STALE (the line is no longer in the file; re-review or remove the entry): #{e.label}"
+        elsif e.occurrence.nil? && count > 1
+          errs << "AMBIGUOUS (the line occurs #{count} times; add `occurrence`): #{e.label}"
+        elsif e.occurrence && e.occurrence > count
+          errs << "STALE (occurrence #{e.occurrence} but the line now occurs #{count} time(s)): #{e.label}"
+        end
+      end
+      errs
+    end
+
+    # The entry covering this mutant, or nil.
+    def match(mutation)
+      @entries.find do |e|
+        e.file == mutation.file && e.operator == mutation.operator && e.line == mutation.line_text &&
+          (e.occurrence || 1) == mutation.occurrence &&
+          (e.method.nil? || e.method == mutation.method) &&
+          (e.mutation.nil? || normalize(e.mutation) == mutation.change)
+      end
+    end
+
+    # Entries for files in `complete_files` that matched no surviving mutant: the mutant is now killed, or the code
+    # changed. Either way the entry must be removed or re-reviewed.
+    def stale(matched_entries, complete_files)
+      @entries.reject { |e| matched_entries.include?(e) }.select { |e| complete_files.include?(e.file) }
+    end
+
+    # YAML stubs for the given survivors (reason left empty on purpose: the file is rejected until it is filled in).
+    def self.stub_for(mutations, sources)
+      mutations.map do |m|
+        h = { 'file' => m.file, 'operator' => m.operator, 'line' => m.line_text }
+        count = sources[m.file].to_s.split("\n", -1).count { |l| l.strip == m.line_text }
+        h['occurrence'] = m.occurrence if count > 1
+        h['method'] = m.method if m.method
+        h['mutation'] = m.change
+        h['lineno'] = m.lineno
+        h['reason'] = ''
+        h
+      end.to_yaml
+    end
+
+    private
+
+    def normalize(s)
+      s.to_s.gsub(/\s+/, ' ').strip
+    end
+
+    def parse_entry(raw, i)
+      where = "#{@path}: entry ##{i + 1}"
+      raise Invalid, "#{where}: expected a mapping" unless raw.is_a?(Hash)
+
+      unknown = raw.keys.map(&:to_s) - KEYS
+      raise Invalid, "#{where}: unknown key(s) #{unknown.join(', ')}" if unknown.any?
+
+      %w[file operator line reason].each do |k|
+        v = raw[k]
+        raise Invalid, "#{where}: `#{k}` is required" if v.nil? || v.to_s.strip.empty?
+      end
+      %w[occurrence lineno].each do |k|
+        v = raw[k]
+        raise Invalid, "#{where}: `#{k}` must be a positive integer" unless v.nil? || (v.is_a?(Integer) && v.positive?)
+      end
+      unless Generator::OPERATORS.key?(raw['operator'].to_s)
+        raise Invalid, "#{where}: unknown operator #{raw['operator'].inspect}"
+      end
+
+      Entry.new(file: raw['file'].to_s.sub(%r{\A\./}, ''), operator: raw['operator'].to_s, line: raw['line'].to_s.strip,
+                occurrence: raw['occurrence'], method: raw['method']&.to_s, mutation: raw['mutation']&.to_s,
+                lineno: raw['lineno'], reason: raw['reason'].to_s.strip, index: i)
+    end
+  end
+end

data/lib/mutaruby/mutation.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mutaruby
+  # One mutant: a single source edit of one file.
+  #
+  #   file       path of the mutated file, relative to the project root
+  #   operator   operator id (see OPERATORS / README)
+  #   orig, repl the replaced source slice and its replacement
+  #   lineno     1-based line where the replaced slice starts
+  #   line_text  that line, stripped (part of the site key)
+  #   occurrence 1-based index of line_text among the identical (stripped) lines of the file (part of the site key)
+  #   method     enclosing method, qualified: "Foo::Bar#baz" (instance), "Foo::Bar.baz" (singleton), nil at top level
+  #   text       the complete mutated file
+  Mutation = Struct.new(:id, :file, :operator, :orig, :repl, :lineno, :line_text, :occurrence, :method, :text,
+                        keyword_init: true) do
+    def short(str, max = 80)
+      s = str.gsub(/\s+/, ' ')
+      s.length > max ? "#{s[0, max - 3]}..." : s
+    end
+
+    # Human label: "comparison: > => >="
+    def label
+      "#{operator}: #{short(orig)} => #{short(repl)}"
+    end
+
+    # Normalised "orig => repl" (whitespace collapsed); the optional `mutation` field of an ignore entry.
+    def change
+      "#{orig.gsub(/\s+/, ' ').strip} => #{repl.gsub(/\s+/, ' ').strip}"
+    end
+
+    def location
+      "#{file}:#{lineno}"
+    end
+
+    # The mutated region with one line of context, as a minimal unified-style diff.
+    def diff(original_source)
+      lines = original_source.lines
+      mlines = text.lines
+      i = lineno - 1
+      orig_n = orig.count("\n") + 1
+      repl_n = repl.count("\n") + 1
+      out = []
+      (lines[i, orig_n] || []).each { |l| out << "- #{l.chomp}" }
+      (mlines[i, repl_n] || []).each { |l| out << "+ #{l.chomp}" }
+      out.join("\n")
+    end
+
+    def to_h
+      { id: id, file: file, lineno: lineno, operator: operator, method: method, line_text: line_text,
+        occurrence: occurrence, orig: orig, repl: repl, change: change, label: label }
+    end
+  end
+end

data/lib/mutaruby/parsing.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'parser'
+
+module Mutaruby
+  # Picks the newest `parser` grammar that is not newer than the running Ruby. `parser/current` prints a warning on
+  # Rubies it does not know yet; choosing the class ourselves keeps the output clean and the behaviour explicit.
+  module Parsing
+    class << self
+      def parser_class
+        @parser_class ||= begin
+          major, minor = RUBY_VERSION.split('.').map(&:to_i)
+          wanted = (major * 10) + minor
+          found = nil
+          wanted.downto(31) do |v|
+            begin
+              require "parser/ruby#{v}"
+              found = Parser.const_get("Ruby#{v}")
+              break
+            rescue LoadError, NameError
+              next
+            end
+          end
+          found || raise(Error, "no parser grammar available for Ruby #{RUBY_VERSION}")
+        end
+      end
+
+      def buffer(path, source)
+        Parser::Source::Buffer.new(path, source: source)
+      end
+
+      # Parse `source`; returns the AST or raises Parser::SyntaxError.
+      def parse(path, source)
+        p = parser_class.new
+        p.diagnostics.all_errors_are_fatal = true
+        p.diagnostics.ignore_warnings = true
+        p.parse(buffer(path, source))
+      end
+
+      def valid?(path, source)
+        parse(path, source)
+        true
+      rescue Parser::SyntaxError, EncodingError, ArgumentError
+        false
+      end
+    end
+  end
+end