mutato 0.1.0

data/lib/mutato/installer/header.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Mutato
+  class Installer
+    # What a mutant needs from its file: the frozen-string comment and top-level `using`.
+    module Header
+      module_function
+
+      # The code's second line is the def's; the header goes above the first.
+      def evaluate(code, subject)
+        path = File.expand_path(subject.file)
+        head = of(path)
+        source = head + code
+        TOPLEVEL_BINDING.eval(source, path, subject.node.location.start_line - 1 - head.count("\n"))
+      end
+
+      def of(path)
+        result = Prism.parse_file(path)
+        "#{frozen_line(result)}#{usings(result)}"
+      end
+
+      def frozen_line(result)
+        frozen = result.magic_comments.any? { |comment| Header.frozen?(comment) }
+        "# frozen_string_literal: true\n" if frozen
+      end
+
+      # Ruby accepts dashes and any case in the key and the value.
+      def frozen?(comment)
+        comment.key.tr("-", "_").casecmp?("frozen_string_literal") && comment.value.casecmp?("true")
+      end
+
+      def usings(result)
+        calls = result.value.statements.body.select { |node| Nodes.using?(node) }
+        calls.sum("") { |node| "#{node.slice}; " }
+      end
+    end
+  end
+end

data/lib/mutato/installer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "installer/header"
+
+module Mutato
+  # Wrapped in the original nesting, so constant lookup in the mutant still works.
+  class Installer
+    class Unviable < StandardError
+    end
+    public_constant :Unviable
+
+    # Whatever stops the mutated method from loading makes the mutant unviable.
+    def self.install(subject, def_source)
+      quietly { new(subject).install(def_source) }
+    rescue ScriptError, StandardError => error
+      raise Unviable, "#{error.class}: #{error.message.lines.first.to_s.strip}"
+    end
+
+    # The method as it is now, to tell if the tests replaced the installed one.
+    def self.current(subject)
+      new(subject).current
+    end
+
+    def self.methods_of(owner)
+      owner.instance_methods(false) + owner.private_instance_methods(false)
+    end
+
+    # Redefining warns under -w, which a suite failing on warnings turns into unviable mutants.
+    def self.quietly
+      verbose = $VERBOSE
+      $VERBOSE = nil
+      yield
+    ensure
+      $VERBOSE = verbose
+    end
+
+    def initialize(subject)
+      @subject = subject
+      @name = subject.name
+    end
+
+    def install(def_source)
+      owner = loaded_owner
+      visibility = visibility_of(owner)
+      twins = twins_of(owner)
+      Header.evaluate(wrap(def_source, visibility), @subject)
+      restore(owner, visibility, twins)
+    end
+
+    def current
+      owner = resolve_owner
+      owner.instance_method(@name) if defines?(owner)
+    end
+
+    def wrap(def_source, visibility)
+      "#{openers.join(" ")}\n#{prefix(visibility)}#{def_source}\n#{" end" * @subject.chain.size}"
+    end
+
+    private
+
+    def openers
+      @subject.chain.map { |kind, name| kind == :sclass ? "class << self;" : "#{kind} #{name};" }
+    end
+
+    # `private def` keeps a method_added hook from seeing a public def.
+    def prefix(visibility)
+      visibility == :public || @subject.singleton ? "" : "#{visibility} "
+    end
+
+    # A class a framework loads on first use is loaded from the file.
+    def loaded_owner
+      name = @subject.owner_name
+      require File.expand_path(@subject.file) unless name.empty? || Object.const_defined?(name)
+      resolve_owner
+    end
+
+    # Aliases of the old body, and module_function's singleton copy, must follow.
+    def twins_of(owner)
+      return [] unless defines?(owner)
+
+      target = owner.instance_method(@name)
+      Installer.methods_of(owner).select do |name|
+        name != @name && owner.instance_method(name) == target
+      end
+    end
+
+    def defines?(owner)
+      owner.method_defined?(@name) || owner.private_method_defined?(@name)
+    end
+
+    # The visibility methods are private, hence __send__.
+    def restore(owner, visibility, twins)
+      twins.each { |name| owner.alias_method(name, @name) }
+      owner.__send__(:module_function, @name) if visibility == :private && module_function?(owner)
+      owner.__send__(visibility, @name) if @subject.singleton && visibility != :public
+      owner.instance_method(@name)
+    end
+
+    def module_function?(owner)
+      owner.instance_of?(Module) && owner.singleton_methods(false).include?(@name)
+    end
+
+    def resolve_owner
+      receiver = @subject.receiver
+      owner = receiver ? lexical(receiver) : nesting_owner
+      return owner if !@subject.singleton || @subject.chain.last == [:sclass, nil]
+
+      owner.singleton_class
+    end
+
+    def nesting_owner
+      @subject.chain.reduce(Object) do |mod, (kind, name)|
+        kind == :sclass ? mod.singleton_class : mod.const_get(name)
+      end
+    end
+
+    # A constant as the code naming it sees it: from the innermost nesting outward.
+    def lexical(name)
+      nestings = @subject.chain.filter_map(&:last).reduce([Object]) do |found, part|
+        found << found.last.const_get(part)
+      end
+      nestings.reverse.find { |mod| mod.const_defined?(name) }
+        .const_get(name)
+    end
+
+    def visibility_of(owner)
+      return :private if owner.private_method_defined?(@name, false)
+      return :protected if owner.protected_method_defined?(@name, false)
+
+      :public
+    end
+  end
+end

data/lib/mutato/measure.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mutato
+  Measure = Data.define(:status, :line_map, :durations, :failed, :seen, :hooks) do
+    # A set: an array here would take a minute on a large suite.
+    def self.judged(ids, judges)
+      ids.select { |id| judges.include?(id) }
+    end
+
+    def summary(seconds)
+      format(
+        "baseline: status %<status>d, %<seconds>.2fs, %<lines>d covered lines, %<tests>d tests",
+        status:,
+        seconds:,
+        lines: line_map.size,
+        tests: durations.size
+      )
+    end
+
+    def all_failed?
+      durations.size == failed.size
+    end
+
+    # Only tests that ran and passed can judge a mutant; a group hook may credit others.
+    def baseline(**rest)
+      judges = (durations.keys - failed).to_set
+      Baseline.new(
+        line_map: line_map.transform_values { |ids| Measure.judged(ids, judges) },
+        durations:,
+        order: durations.each_key.with_index.to_h,
+        hooks:,
+        **rest
+      )
+    end
+  end
+  public_constant :Measure
+end

data/lib/mutato/mode/control.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Mutato
+  module Mode
+    # A control that exercised nothing proved nothing: exit 3.
+    module Control
+      module_function
+
+      def todo(selection)
+        selection.controls
+      end
+
+      def exit_code(outcomes)
+        return 1 if Mode.failed_controls(outcomes).any?
+
+        outcomes.any? { |outcome| Mode.exercised?(outcome) } ? 0 : 3
+      end
+
+      def summary(outcomes)
+        bad = Mode.failed_controls(outcomes)
+        return verdict(outcomes) if bad.empty?
+
+        [
+          "control FAILED:",
+          *bad.map do |outcome|
+            "  #{outcome.fetch(:outcome)} #{outcome.fetch(:label)}"
+          end
+        ]
+      end
+
+      def verdict(outcomes)
+        exercised = outcomes.select { |outcome| Mode.exercised?(outcome) }
+        if exercised.empty?
+          return ["control proved nothing: no reinstalled method was exercised by a test"]
+        end
+
+        ["control OK: #{exercised.size} of #{outcomes.size} reinstalled methods passed their tests"]
+      end
+
+      def annotate(_outcomes, _console, _format); end
+    end
+  end
+end

data/lib/mutato/mode/run.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mutato
+  module Mode
+    module Run
+      module_function
+
+      def todo(selection)
+        selection.mutations
+      end
+
+      def exit_code(outcomes)
+        Mode.missed(outcomes).any? ? 2 : 0
+      end
+
+      def summary(outcomes)
+        lines = Mode.missed(outcomes).map do |outcome|
+          "  #{outcome.fetch(:id)}  #{outcome.fetch(:label)}#{flaky_note(outcome)}"
+        end
+        lines.empty? ? [] : ["\nMISSED:", *lines]
+      end
+
+      def flaky_note(outcome)
+        excluded = outcome.fetch(:flaky, [])
+        "  (#{excluded.size} flaky tests excluded)" if excluded.any?
+      end
+
+      def annotate(outcomes, console, format)
+        Annotations.new(console).show(outcomes, format)
+      end
+    end
+  end
+end

data/lib/mutato/mode.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "mode/control"
+require_relative "mode/run"
+
+module Mutato
+  module Mode
+    MISSED = %i[missed unjudged].freeze
+    PASSING_CONTROL = %i[missed uncovered load-time unloaded].freeze
+    private_constant :MISSED, :PASSING_CONTROL
+
+    module_function
+
+    def missed(outcomes)
+      outcomes.select { |outcome| MISSED.include?(outcome.fetch(:outcome)) }
+    end
+
+    def exercised?(outcome)
+      outcome.fetch(:examples).positive?
+    end
+
+    def failed_controls(outcomes)
+      outcomes.reject { |outcome| PASSING_CONTROL.include?(outcome.fetch(:outcome)) }
+    end
+  end
+end

data/lib/mutato/mutation.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Mutato
+  Mutation = Data.define(
+    :id,
+    :file,
+    :subject,
+    :genre,
+    :line,
+    :col,
+    :start_line,
+    :end_line,
+    :outer_lines,
+    :offset,
+    :bytes,
+    :original,
+    :replacement,
+    :description
+  ) do
+    # The span starts below the def line, which runs at load; a one-liner's is empty: uncovered.
+    def self.control(subject)
+      location = subject.node.location
+      first = location.start_line
+      new(
+        id: "control-#{subject.qualified.tr("/", "_")}",
+        file: subject.file,
+        subject:,
+        genre: :control,
+        line: first,
+        col: 1,
+        start_line: first + 1,
+        end_line: location.end_line,
+        outer_lines: nil,
+        offset: location.start_offset,
+        bytes: 0,
+        original: "",
+        replacement: "",
+        description: "reinstall #{subject} unchanged"
+      )
+    end
+
+    def label
+      "#{file}:#{line}:#{col}: [#{genre}] #{description}"
+    end
+
+    alias_method :to_s, :label
+
+    def listing
+      "#{id}  #{label}  (#{subject})"
+    end
+
+    def span
+      start_line..end_line
+    end
+
+    def record(ids)
+      {
+        id:,
+        label:,
+        genre:,
+        file:,
+        line:,
+        col:,
+        description:,
+        examples: ids.size,
+        ids:,
+        seconds: 0.0
+      }
+    end
+
+    def apply(source)
+      mutated = source.b
+      mutated[offset, bytes] = replacement.b
+      mutated.force_encoding(source.encoding)
+    end
+
+    def mutated_source(file_source)
+      mutated = apply(file_source)
+      delta = replacement.bytesize - bytes
+      location = subject.node.location
+      mutated.b[location.start_offset, location.length + delta].force_encoding(file_source.encoding)
+    end
+  end
+  public_constant :Mutation
+end

data/lib/mutato/nodes.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Mutato
+  module Nodes
+    BLOCKS = [Prism::BlockNode, Prism::LambdaNode].freeze
+    CONDITIONALS = [Prism::IfNode, Prism::UnlessNode].freeze
+    HEREDOC_CAPABLE = [
+      Prism::StringNode,
+      Prism::InterpolatedStringNode,
+      Prism::XStringNode,
+      Prism::InterpolatedXStringNode
+    ].freeze
+    LITERALS = [
+      Prism::StringNode,
+      Prism::SymbolNode,
+      Prism::IntegerNode,
+      Prism::FloatNode,
+      Prism::NilNode,
+      Prism::TrueNode,
+      Prism::FalseNode
+    ].freeze
+    MEMO_GUARD = /\Areturn (@\w+) if \1\z/
+    public_constant :BLOCKS, :CONDITIONALS, :LITERALS
+    private_constant :HEREDOC_CAPABLE, :MEMO_GUARD
+
+    module_function
+
+    # Named, not anonymous: Ruby 3.3.0 rejects `&` forwarded from inside a block.
+    def each_node(node, &block)
+      return enum_for(:each_node, node) unless block
+
+      yield(node)
+      node.compact_child_nodes.each { |child| each_node(child, &block) }
+    end
+
+    def using?(node)
+      node.is_a?(Prism::CallNode) && node.name == :using && node.receiver.nil?
+    end
+
+    def one_of?(node, classes)
+      classes.any? { |klass| node.is_a?(klass) }
+    end
+
+    # The statements of a def body, looking through the begin a rescue adds.
+    def statements_of(body)
+      body = body.statements if body.is_a?(Prism::BeginNode)
+      body.body if body.is_a?(Prism::StatementsNode)
+    end
+
+    def else_less?(node)
+      node.is_a?(Prism::IfNode) ? node.subsequent.nil? : node.else_clause.nil?
+    end
+
+    def constant_receiver(definition)
+      receiver = definition.receiver
+      receiver.slice if receiver.is_a?(Prism::ConstantReadNode)
+    end
+
+    def singleton_receiver?(definition)
+      receiver = definition.receiver
+      receiver.is_a?(Prism::SelfNode) || receiver.is_a?(Prism::ConstantReadNode)
+    end
+
+    def foreign_receiver?(definition)
+      receiver = definition.receiver
+      receiver && !singleton_receiver?(definition)
+    end
+
+    # Lines inside blocks may run later than the method itself (define_method, Thread.new).
+    def block_lines(definition)
+      blocks = each_node(definition).select { |inner| one_of?(inner, BLOCKS) }
+      blocks.flat_map do |block|
+        location = block.location
+        ((location.start_line + 1)..location.end_line).to_a
+      end
+    end
+
+    # `x.size > 0`: a comparison a count can never fail.
+    def count_against_zero?(call)
+      receiver = call.receiver
+      argument = sole_argument(call)
+      receiver.is_a?(Prism::CallNode) && %i[length size count].include?(receiver.name) &&
+        argument.is_a?(Prism::IntegerNode) && argument.value.zero?
+    end
+
+    # `initialize` and setters: their caller never sees the value they return.
+    def value_dropped?(name)
+      name == :initialize || name.to_s.match?(/\A\w+=\z/)
+    end
+
+    # `return @x if @x`: deleting it, or making it never return, only skips a cache.
+    def memo_guard?(statement)
+      statement.slice.match?(MEMO_GUARD)
+    end
+
+    def nil_store?(call)
+      call.name == :[]= && arguments_of(call).last.is_a?(Prism::NilNode)
+    end
+
+    def nil_valued?(element)
+      value = element.is_a?(Prism::AssocNode) ? element.value : element
+      value.is_a?(Prism::NilNode) || value.is_a?(Prism::FalseNode)
+    end
+
+    def single_statement(conditional)
+      return unless conditional.statements&.body in [only]
+
+      only
+    end
+
+    def arguments_of(call)
+      call.arguments&.arguments || []
+    end
+
+    def sole_argument(call)
+      argument, = arguments_of(call)
+      argument
+    end
+
+    # `a + b`, `x < 1`: one receiver, one argument, no parentheses, the name spelled out.
+    def binary_operator?(call)
+      message = call.message_loc
+      call.receiver && message && call.opening_loc.nil? &&
+        arguments_of(call).size == 1 && message.slice == call.name.to_s
+    end
+
+    # A heredoc's body lies below its statement and goes with it; the terminator's newline stays.
+    def extent(node, source)
+      location = node.location
+      start = location.start_offset
+      stop = [location.end_offset, *heredoc_ends(node)].max
+      stop -= 1 if source.getbyte(stop - 1) == "\n".ord
+      [start, stop - start]
+    end
+
+    def heredoc_ends(node)
+      heredocs = each_node(node).select do |inner|
+        one_of?(inner, HEREDOC_CAPABLE) && inner.heredoc?
+      end
+      heredocs.map { |heredoc| heredoc.closing_loc.end_offset }
+    end
+
+    def compact(text)
+      joined = text.gsub(/\s*\\\n\s*/, " ").gsub(/\s+/, " ")
+      joined.sub(/\A(.{57}).{4,}\z/, "\\1...")
+    end
+  end
+end

data/lib/mutato/options.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Mutato
+  Options = Data.define(
+    :help,
+    :version,
+    :spec,
+    :config,
+    :diff,
+    :format,
+    :limit,
+    :sample,
+    :genres,
+    :only,
+    :out,
+    :timeout_min
+  ) do
+    def self.parse(argv)
+      Flags.parse(argv)
+    end
+
+    def spec_args
+      Shellwords.split(spec)
+    end
+
+    def genre?(genre)
+      genres.nil? || genres.include?(genre.to_s)
+    end
+  end
+  public_constant :Options
+end

data/lib/mutato/output.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Mutato
+  class Output
+    OUTCOMES = %w[
+      caught
+      missed
+      timeout
+      unjudged
+      equivalent
+      overwritten
+      unviable
+      crashed
+      uncovered
+      load-time
+      unloaded
+    ].freeze
+    LOG_CAP = 1_000_000
+    private_constant :OUTCOMES, :LOG_CAP
+
+    # Logs hold whatever the application printed; keep the last megabyte.
+    def self.cap(log)
+      size = File.size?(log)
+      return unless size && size > LOG_CAP
+
+      File.binwrite(log, "mutato: log truncated to its last #{LOG_CAP} bytes\n#{tail(log)}")
+    end
+
+    # Only the tail is read: a runaway mutant's log can be gigabytes.
+    def self.tail(log)
+      File.open(log, "rb") do |file|
+        file.seek(-LOG_CAP, IO::SEEK_END)
+        file.read
+      end
+    end
+
+    def self.listed(outcomes, name)
+      chosen = outcomes.select { |outcome| outcome.fetch(:outcome).to_s == name }
+      chosen.map { |outcome| "#{outcome.fetch(:id)}  #{outcome.fetch(:label)}" }
+    end
+
+    # A run starts outcomes.jsonl afresh, as it rewrites the other lists.
+    def initialize(dir)
+      @dir = dir
+      FileUtils.mkdir_p(File.join(dir, "logs"))
+      File.write(File.join(dir, "outcomes.jsonl"), "")
+    end
+
+    def log_path(id)
+      File.join(@dir, "logs", "#{id}.log")
+    end
+
+    def append(outcome)
+      File.write(File.join(@dir, "outcomes.jsonl"), "#{JSON.generate(outcome)}\n", mode: "a")
+    end
+
+    def write(outcomes, flaky)
+      File.write(File.join(@dir, "outcomes.json"), JSON.pretty_generate(outcomes))
+      OUTCOMES.each { |name| write_list("#{name}.txt", Output.listed(outcomes, name)) }
+      write_list("flaky.txt", flaky)
+    end
+
+    private
+
+    def write_list(name, lines)
+      File.write(
+        File.join(@dir, name),
+        lines.map { |line| "#{line}\n" }
+        .join
+      )
+    end
+  end
+end

data/lib/mutato/privates.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Mutato
+  # The private method names of one statement list: `private def x`, `private :x`, and the
+  # defs after a bare `private`, until `public` or `protected`.
+  module Privates
+    VISIBILITY = %i[private public protected].freeze
+    private_constant :VISIBILITY
+
+    module_function
+
+    def names(statements)
+      hidden = false
+      statements.body.each_with_object([]) do |statement, names|
+        hidden = section(statement, hidden)
+        names.concat(listed(statement))
+        names << statement.name if hidden && statement.is_a?(Prism::DefNode)
+      end
+    end
+
+    def section(statement, hidden)
+      return hidden unless visibility?(statement) && Nodes.arguments_of(statement).empty?
+
+      statement.name == :private
+    end
+
+    def listed(statement)
+      return [] unless visibility?(statement) && statement.name == :private
+
+      Nodes.arguments_of(statement).filter_map { |argument| Privates.name_of(argument) }
+    end
+
+    def name_of(argument)
+      return argument.name if argument.is_a?(Prism::DefNode)
+
+      argument.unescaped.to_sym if Nodes.one_of?(argument, [Prism::SymbolNode, Prism::StringNode])
+    end
+
+    def visibility?(statement)
+      statement.is_a?(Prism::CallNode) && statement.receiver.nil? &&
+        VISIBILITY.include?(statement.name)
+    end
+  end
+end