mutato 0.1.0

data/lib/mutato/change.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mutato
+  # `shown` is where the mutant is reported; offset and bytes are what it replaces.
+  Change = Data.define(:genre, :node, :shown, :offset, :bytes, :replacement, :description) do
+    def self.whole(node, replacement, description)
+      location = node.location
+      new(
+        genre: nil,
+        node:,
+        shown: location,
+        offset: location.start_offset,
+        bytes: location.length,
+        replacement:,
+        description:
+      )
+    end
+
+    def at(location)
+      with(shown: location, offset: location.start_offset, bytes: location.length)
+    end
+
+    def covering(extent)
+      offset, bytes = extent
+      with(offset:, bytes:)
+    end
+
+    def original(source)
+      source.byteslice(offset, bytes)
+    end
+
+    # Coverage marks a statement's first line only: continuation lines go by their statement.
+    def where(cursor)
+      span = (cursor.statement || node).location
+      {
+        line: shown.start_line,
+        col: shown.start_column + 1,
+        start_line: span.start_line,
+        end_line: span.end_line,
+        outer_lines: cursor.outer_lines(node)
+      }
+    end
+
+    def what(source)
+      { genre:, offset:, bytes:, original: original(source), replacement:, description: }
+    end
+  end
+  public_constant :Change
+end

data/lib/mutato/child.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Mutato
+  # `exit!` throughout: a child must not run the parent's at_exit handlers.
+  class Child
+    CHUNK = 65_536
+    private_constant :CHUNK
+
+    def self.run(timeout: nil, log: nil, &)
+      new(timeout, log).run(&)
+    end
+
+    # Whatever the block raises, the parent gets a result.
+    def self.attempt
+      yield
+    rescue SoftTimeout
+      { outcome: :timeout }
+    rescue Exception => error
+      {
+        outcome: :crashed,
+        detail: "#{error.class}: #{error.message}",
+        backtrace: Array(error.backtrace).first(5)
+      }
+    end
+
+    # A signal death (segfault, SIGTERM) counts against the mutant until confirmed.
+    def self.verdict(data, status)
+      return { outcome: :caught, failing: nil, signal: status.termsig } if status.signaled?
+      return { outcome: :crashed, detail: "exit status #{status.exitstatus}" } if data.empty?
+
+      Marshal.load(data)
+    end
+
+    def initialize(timeout, log)
+      @timeout = timeout
+      @log = log
+      @reader = nil
+      @pid = nil
+    end
+
+    # Named, not anonymous: Ruby 3.3.0 rejects `&` forwarded from inside a block.
+    def run(&block)
+      Mutato.config.run_hooks(:before_fork)
+      # A project may set default_internal; Marshal's bytes must not be transcoded.
+      @reader, writer = IO.pipe(binmode: true)
+      @pid = fork { work(writer, &block) }
+      collect(writer)
+    ensure
+      sweep
+    end
+
+    private
+
+    # A process group of its own: what the tests start and leave running dies with it.
+    def work(writer, &)
+      Process.setpgid(0, 0)
+      @reader.close
+      settle
+      deliver(writer, Child.attempt(&))
+    end
+
+    # Not the parent's INT/TERM handlers: a mutant that signals itself must end only the child.
+    def settle
+      %w[INT TERM].each { |signal| trap(signal, "DEFAULT") }
+      Mutato.config.run_hooks(:after_fork)
+      redirect
+    end
+
+    def redirect
+      STDIN.reopen(File::NULL)
+      log_output if @log
+    end
+
+    # The streams, not $stdout: a project's replacement object still writes to them.
+    def log_output
+      STDOUT.reopen(@log, "w")
+      STDERR.reopen(STDOUT)
+      STDOUT.sync = true
+      $stdout = STDOUT
+      $stderr = STDERR
+    end
+
+    def deliver(writer, result)
+      writer.write(Marshal.dump(result))
+    rescue SystemCallError
+      # The parent is gone, and there is no one to tell; still no at_exit handlers.
+    ensure
+      writer.close
+      STDOUT.flush
+      exit! 0
+    end
+
+    def collect(writer)
+      writer.close
+      data = +""
+      status = read_until_exit(data, @timeout && (Clock.now + @timeout))
+      status ? Child.verdict(data, status) : killed
+    end
+
+    # To the child's exit, not EOF: a process the tests fork holds the pipe. nil past the deadline.
+    def read_until_exit(data, deadline)
+      loop do
+        status = exited
+        drain(data)
+        return status if status || Clock.left(deadline)&.zero?
+
+        @reader.wait_readable(0.05)
+      end
+    end
+
+    def exited
+      Process.wait2(@pid, Process::WNOHANG)&.last
+    end
+
+    def drain(data)
+      while (chunk = @reader.read_nonblock(CHUNK, exception: false)).is_a?(String)
+        data << chunk
+      end
+    end
+
+    def killed
+      Process.kill("KILL", @pid)
+      Process.wait(@pid)
+      File.write(@log, "\nmutato: killed after #{@timeout.round(1)} s\n", mode: "a") if @log
+      { outcome: :timeout }
+    end
+
+    def sweep
+      @reader&.close
+      Process.kill("KILL", -@pid) if @pid
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+  end
+end

data/lib/mutato/cli.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "abort"
+require_relative "annotations"
+require_relative "baseline"
+require_relative "boot"
+require_relative "campaign"
+require_relative "child"
+require_relative "clock"
+require_relative "console"
+require_relative "coverage_listener"
+require_relative "covering"
+require_relative "diff"
+require_relative "equivalence"
+require_relative "experience"
+require_relative "flags"
+require_relative "group_hooks"
+require_relative "hits"
+require_relative "measure"
+require_relative "mode"
+require_relative "options"
+require_relative "output"
+require_relative "report"
+require_relative "rspec_adapter"
+require_relative "run"
+require_relative "selection"
+require_relative "session"
+require_relative "soft_timeout"
+require_relative "suite"
+require_relative "trial"
+require_relative "watchdog"
+
+module Mutato
+  class CLI
+    USAGE = <<~USAGE
+      usage: mutato list|run|control PATH... [options]
+        list     the mutants that would be tried, without running anything
+        run      baseline, then every mutant; survivors are the output
+        control  reinstall every method unchanged; all must come out missed
+      options:
+        -h, --help  -v, --version  this text, the version
+        --spec ARGS                rspec arguments: paths, --tag, ... (default spec)
+        --config FILE              hooks and skips (default .mutato.rb)
+        --diff FILE|-              only mutate lines a unified diff adds or changes
+        --format github|plain      survivors as annotations or path:line:col lines
+        --limit N  --sample N  --genre a,b  --only ID,ID
+        --out DIR (default mutato.out)  --timeout-min SECONDS (default 10)
+    USAGE
+    MODES = { "run" => Mode::Run, "control" => Mode::Control }.freeze
+    COMMANDS = ["list", *MODES.keys].freeze
+    private_constant :USAGE, :MODES, :COMMANDS
+
+    # Returns the exit code; an Abort from anywhere, flag parsing included, ends here.
+    def self.call(argv, console: Console.new)
+      new(argv, console:).call
+    rescue Abort => error
+      console.say(error.message)
+      error.code
+    ensure
+      console.flush
+    end
+
+    def initialize(argv, console:)
+      @console = console
+      # Loaded test code may rewrite ARGV.
+      argv = argv.dup
+      @options = parse(argv)
+      @command = argv.shift
+      @paths = argv.freeze
+    end
+
+    def call
+      return show(info) if info
+
+      prepare
+      dispatch(Selection.new(@paths, @options))
+    end
+
+    private
+
+    def info
+      return USAGE if @options.help
+
+      "mutato #{VERSION}" if @options.version
+    end
+
+    def prepare
+      check_paths
+      load_config
+      ARGV.clear
+    end
+
+    # OptionParser reports a bad flag by raising; the user gets one line.
+    def parse(argv)
+      Options.parse(argv)
+    rescue OptionParser::ParseError => error
+      @console.die("#{error.message}; mutato --help lists the options")
+    end
+
+    def show(text)
+      @console.out(text)
+      0
+    end
+
+    def check_paths
+      @console.die(USAGE) unless COMMANDS.include?(@command) && @paths.any?
+      missing = @paths.reject { |path| File.exist?(path) }
+      @console.die("no such path: #{missing.join(", ")}") if missing.any?
+    end
+
+    def load_config
+      named = @options.config
+      config = named || ".mutato.rb"
+      exists = File.exist?(config)
+      @console.die("no such config: #{config}") if named && !exists
+      load config if exists
+    end
+
+    def dispatch(selection)
+      return list(selection) if @command == "list"
+
+      Session.new(MODES.fetch(@command), selection, @console).call
+    end
+
+    def list(selection)
+      mutations = selection.chosen(selection.mutations)
+      print_listing(mutations)
+      @console.say(*selection.summary(mutations))
+      0
+    end
+
+    # On stdout, and out before the summary follows on stderr.
+    def print_listing(mutations)
+      mutations.each { |mutation| @console.out(mutation.listing) }
+      @console.flush
+    end
+  end
+end

data/lib/mutato/clock.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mutato
+  # Seconds from a clock the system never sets back.
+  module Clock
+    module_function
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def since(started)
+      now - started
+    end
+
+    # Seconds until the deadline, never negative; nil without one.
+    def left(deadline)
+      [deadline - now, 0].max if deadline
+    end
+  end
+end

data/lib/mutato/config.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mutato
+  class Config
+    Skip = Data.define(:pattern, :reason)
+    private_constant :Skip
+
+    attr_reader :hooks
+
+    def initialize
+      @hooks = Hash.new { |hash, name| hash[name] = [] }
+      @skips = []
+      @arid = Set.new
+    end
+
+    def run_hooks(name)
+      @hooks.fetch(name, []).each(&:call)
+    end
+
+    # A String names one method exactly; a Regexp matches the qualified name.
+    def skip(pattern, reason)
+      pattern = /\A#{Regexp.escape(pattern)}\z/ if pattern.is_a?(String)
+      @skips << Skip.new(pattern:, reason:)
+    end
+
+    def skip_reason(qualified)
+      @skips.find { |skip| skip.pattern.match?(qualified) }
+        &.reason
+    end
+
+    def arid(*names)
+      @arid.merge(names.map(&:to_s))
+    end
+
+    def arid?(name)
+      @arid.include?(name.to_s)
+    end
+  end
+end

data/lib/mutato/console.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "abort"
+
+module Mutato
+  # The real streams, duped at start: the project under test may replace $stdout.
+  class Console
+    def initialize(out: $stdout.dup, err: $stderr.dup)
+      @out = out
+      @err = err
+      @err.sync = true
+    end
+
+    # Not Kernel#warn: RUBYOPT=-W0 silences that.
+    def say(*lines)
+      lines.each { |line| @err.puts(line) }
+    end
+
+    def out(line)
+      @out.puts(line)
+    end
+
+    # CLI.call reports it and returns the code.
+    def die(message, code: 1)
+      raise Abort.new(message, code:)
+    end
+
+    # Stderr is unbuffered already.
+    def flush
+      @out.flush
+    end
+  end
+end

data/lib/mutato/coverage_listener/tally.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mutato
+  class CoverageListener
+    Tally = Struct.new(:line_map, :durations, :failed, :seen, :began) do
+      def self.fresh
+        new(Hash.new { |hash, key| hash[key] = [] }, {}, [], Set.new, Clock.now)
+      end
+
+      def finish(example, seconds, hits)
+        id = example.id
+        durations[id] = seconds
+        failed << id if example.execution_result.status == :failed
+        hits.each { |key| line_map[key] << id }
+      end
+
+      # Read right after the run: its time less the tests' is the hooks'. A Hash with a
+      # default block cannot be marshalled.
+      def to_h
+        hooks = [Clock.since(began) - durations.values.sum, 0].max
+        super.except(:began).merge(line_map: line_map.to_a.to_h, hooks:)
+      end
+    end
+    public_constant :Tally
+  end
+end

data/lib/mutato/coverage_listener.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "coverage"
+require_relative "coverage_listener/tally"
+
+module Mutato
+  # Each read clears the counters, so one read per example gives exactly its lines.
+  class CoverageListener
+    EVENTS = %i[example_group_started example_started example_finished].freeze
+    public_constant :EVENTS
+
+    attr_reader :tally
+
+    def initialize(prefixes)
+      @prefixes = prefixes
+      @tally = Tally.fresh
+      @hooks = GroupHooks.new
+      @started = Clock.now
+    end
+
+    def example_group_started(_notification)
+      @hooks.credit_suite(@tally.line_map) { read_hits }
+      @hooks.expect_hooks
+    end
+
+    def example_started(notification)
+      @started = Clock.now
+      @hooks.credit(notification.example.example_group, @tally.line_map) { read_hits }
+    end
+
+    def example_finished(notification)
+      @tally.finish(notification.example, Clock.since(@started), read_hits)
+    end
+
+    private
+
+    def read_hits
+      Coverage.result(stop: false, clear: true).flat_map do |path, data|
+        next [] unless path.start_with?(*@prefixes)
+
+        @tally.seen << path
+        Hits.keys(path, data)
+      end
+    end
+  end
+end

data/lib/mutato/covering.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Mutato
+  class Covering
+    def initialize(mutation, baseline)
+      @mutation = mutation
+      @baseline = baseline
+      @path = File.expand_path(mutation.file)
+    end
+
+    def ids
+      ids = stored? ? [] : @baseline.covering(@path, lines)
+      @baseline.prioritize(ids, @mutation.file)
+    end
+
+    def absence
+      return :unloaded unless @baseline.loaded?(@path)
+      # An endless def gets no line event when called.
+      return :uncovered if @mutation.subject.node.equal_loc
+
+      if @baseline.booted?(@path, stored? ? holding : lines)
+        :"load-time"
+      else
+        :uncovered
+      end
+    end
+
+    private
+
+    # Blocks run later than their method: outside one, skip its lines; inside, use its statement.
+    def lines
+      span = @mutation.span.to_a
+      @mutation.outer_lines ? span : span - @mutation.subject.block_lines
+    end
+
+    # All its lines outside blocks: a multi-line literal's line event is on its first element.
+    def holding
+      @mutation.outer_lines.to_a - @mutation.subject.block_lines
+    end
+
+    def stored?
+      @mutation.outer_lines && @baseline.covering(@path, holding).empty?
+    end
+  end
+end

data/lib/mutato/diff.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mutato
+  class Diff
+    def self.read(option)
+      new(option == "-" ? $stdin.read : File.read(option))
+    end
+
+    # `+++ b/lib/a.rb`, maybe a tab and timestamp after (diff -u, hg); c/ i/ o/ w/ from git.
+    def self.path(row)
+      row.delete_prefix("+++ ").partition("\t").first.strip.sub(%r{\A[abciow]/}, "")
+    end
+
+    def initialize(text)
+      @lines = Hash.new { |hash, file| hash[file] = [] }
+      @file = nil
+      @line = 0
+      # Only the paths matter; a stray byte elsewhere must not stop the reading.
+      text.dup.force_encoding(Encoding::UTF_8).scrub.each_line { |row| take(row) }
+    end
+
+    # Both paths from the current directory: `lib`, `./lib` and an absolute path agree.
+    def touches?(file, range)
+      @lines.fetch(File.expand_path(file), []).any? { |line| range.cover?(line) }
+    end
+
+    private
+
+    def take(row)
+      if row.start_with?("+++ ") then @file = File.expand_path(Diff.path(row))
+      elsif (hunk = row.match(/\A@@ -\d+(?:,\d+)? \+(\d+)/)) then @line = Integer(hunk[1], 10)
+      elsif row.start_with?("+") then added
+      elsif row.start_with?(" ") then @line += 1
+      end
+    end
+
+    def added
+      @lines[@file] << @line
+      @line += 1
+    end
+  end
+end

data/lib/mutato/emitter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Mutato
+  class Emitter
+    attr_reader :source, :mutations
+
+    def initialize(file, source)
+      @file = file
+      @source = source
+      @seen = Set.new
+      @mutations = []
+    end
+
+    def add(change, subject, cursor)
+      replacement = change.replacement
+      return if change.original(@source) == replacement
+      return unless @seen.add?([change.offset, change.bytes, replacement])
+
+      @mutations << Mutation.new(
+        id: id_for(change, subject),
+        file: @file,
+        subject:,
+        **change.where(cursor),
+        **change.what(@source)
+      )
+    end
+
+    private
+
+    # The offset within the def: distinct for two `+` on a line, stable when other code moves.
+    def id_for(change, subject)
+      within = change.offset - subject.node.location.start_offset
+      parts = [
+        @file,
+        subject.qualified,
+        change.genre,
+        within,
+        change.original(@source),
+        change.replacement
+      ]
+      Digest::SHA1.hexdigest(parts.join("\0"))[0, 12]
+    end
+  end
+end

data/lib/mutato/equivalence.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mutato
+  module Equivalence
+    # BasicObject's is empty; Struct's, given nothing, sets members to the nil they hold.
+    EMPTY = [BasicObject.instance_method(:initialize), Struct.instance_method(:initialize)].freeze
+    private_constant :EMPTY
+
+    module_function
+
+    # In a module, where `super` goes depends on the class that includes it.
+    def equivalent?(mutation)
+      subject = mutation.subject
+      empty_super?(mutation) && loaded?(subject) &&
+        EMPTY.include?(Installer.current(subject)&.super_method)
+    end
+
+    # A class only the tests load is unknown here; its mutant runs, and the child loads it.
+    def loaded?(subject)
+      name = subject.owner_name
+      name.empty? || Object.const_defined?(name)
+    end
+
+    # A bare `super` with parameters passes them on.
+    def empty_super?(mutation)
+      text = mutation.original
+      text == "super()" || (text == "super" && mutation.subject.node.parameters.nil?)
+    end
+  end
+end

data/lib/mutato/experience.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mutato
+  # culprits: per test sequence, the test that failed it unmutated, or nil when it passed.
+  Experience = Struct.new(:flaky, :culprits) do
+    def self.fresh
+      new(Set.new, {})
+    end
+  end
+  public_constant :Experience
+end