mutant 0.16.3 → 0.17.1

data/lib/mutant/context_map/loader.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Mutant
+  class ContextMap
+    # Reads simplecov's `coverage.json` into a ContextMap
+    #
+    # Every way the read can fail ends in an explanation of how to produce the
+    # recording, because the recording is the whole reason the strategy was
+    # asked for.
+    #
+    # rubocop:disable Metrics/ClassLength
+    class Loader
+      include Anima.new(:artifact, :world)
+
+      MISSING_ARTIFACT = <<~'MESSAGE'
+        Test selection strategy `context_map` needs a per test coverage recording,
+        but none exists at:
+
+          %<path>s
+
+        Record one with simplecov 1.2.0 or newer:
+
+          # spec/spec_helper.rb, or test/test_helper.rb
+          require 'simplecov'
+          SimpleCov.start do
+            track_tests
+          end
+
+        Run the test suite once to write the recording, then re-run mutant. The
+        default HTML formatter writes `coverage.json` beside its report, as does
+        `SimpleCov::Formatter::JSONFormatter`.
+
+        Pass `--selection-path DIRECTORY` if the recording is not under ./coverage.
+      MESSAGE
+
+      UNREADABLE_ARTIFACT = <<~'MESSAGE'
+        Unable to read the coverage recording at:
+
+          %<path>s
+
+        %<error>s
+      MESSAGE
+
+      INVALID_ARTIFACT = <<~'MESSAGE'
+        The coverage recording at:
+
+          %<path>s
+
+        is not a simplecov report mutant can read:
+
+          %<error>s
+
+        Delete it and record it again with simplecov 1.2.0 or newer.
+      MESSAGE
+
+      UNKNOWN_SCHEMA = <<~'MESSAGE'
+        The coverage recording at:
+
+          %<path>s
+
+        uses report schema version %<schema>s, which mutant does not understand.
+        Upgrade mutant, or record again with a simplecov that writes schema
+        version 1.
+      MESSAGE
+
+      NO_CONTEXTS = <<~'MESSAGE'
+        The coverage recording at:
+
+          %<path>s
+
+        has no per test data, so mutant cannot tell which tests cover a subject.
+
+        Enable tracking with simplecov 1.2.0 or newer:
+
+          SimpleCov.start do
+            track_tests
+          end
+
+        Run the test suite once with tracking enabled, then re-run mutant.
+      MESSAGE
+
+      UNKNOWN_CONTEXT = '%<file>s refers to a context the recording does not list'
+      NOT_DIGITS      = 'Expected: digits in base %<base>d but got: %<actual>s'
+
+      # An integer written as digits in a base, and nothing else
+      #
+      # Kernel#Integer would also take a sign, a prefix, whitespace or
+      # underscores, none of which the format allows.
+      def self.parse_digits(string, base:, pattern:)
+        if string.match?(pattern)
+          Either::Right.new(Integer(string, base))
+        else
+          Either::Left.new(NOT_DIGITS % { actual: string.inspect, base: })
+        end
+      end
+      private_class_method :parse_digits
+
+      CONTEXT_INDEX = Transform::Sequence.new(
+        steps: [
+          Transform::STRING,
+          Transform::Block.capture(:decimal) { |string| parse_digits(string, base: 10, pattern: /\A\d+\z/) }
+        ]
+      )
+
+      LINE_BITMAP = Transform::Sequence.new(
+        steps: [
+          Transform::STRING,
+          Transform::Block.capture(:hexadecimal) { |string| parse_digits(string, base: 16, pattern: /\A\h+\z/) }
+        ]
+      )
+
+      # Per source file: the index of each test that executed it, and a bitmap
+      # of the lines it executed
+      TABLE = Transform::Hash::Map.new(key: CONTEXT_INDEX, value: LINE_BITMAP)
+
+      # The report carries far more than mutant reads, and gains keys between
+      # minor schema versions. Each hash below is sliced to the keys mutant
+      # names before the strict transform sees it.
+      #
+      # A file with no `contexts` section is one no recorded test executed, and
+      # contributes nothing rather than making the recording unreadable.
+      FILE = Transform::Sequence.new(
+        steps: [
+          Transform::Hash::Slice.new(keys: %w[contexts]),
+          Transform::Hash.new(
+            optional: [Transform::Hash::Key.new(value: 'contexts', transform: TABLE)],
+            required: []
+          )
+        ]
+      )
+
+      META = Transform::Sequence.new(
+        steps: [
+          Transform::Hash::Slice.new(keys: %w[root schema_version]),
+          Transform::Hash.new(
+            optional: [],
+            required: [
+              Transform::Hash::Key.new(value: 'root',           transform: Transform::STRING),
+              Transform::Hash::Key.new(value: 'schema_version', transform: Transform::STRING)
+            ]
+          )
+        ]
+      )
+
+      COVERAGE = Transform::Hash::Map.new(key: Transform::STRING, value: FILE)
+
+      DOCUMENT = Transform::Sequence.new(
+        steps: [
+          Transform::Hash::Slice.new(keys: %w[contexts coverage meta]),
+          Transform::Hash.new(
+            optional: [Transform::Hash::Key.new(value: 'contexts', transform: Transform::STRING_ARRAY)],
+            required: [
+              Transform::Hash::Key.new(value: 'coverage', transform: COVERAGE),
+              Transform::Hash::Key.new(value: 'meta',     transform: META)
+            ]
+          )
+        ]
+      )
+
+      private_constant(*constants(false))
+
+      # Load the recording under path
+      #
+      # @return [Either<String, ContextMap>]
+      def self.call(path:, world:)
+        artifact = path.file? ? path : path.join(ARTIFACT_BASENAME)
+
+        new(artifact:, world:).call
+      end
+
+      # Load the recording
+      #
+      # @return [Either<String, ContextMap>]
+      def call
+        return error(MISSING_ARTIFACT) unless artifact.file?
+
+        read
+          .bind(&method(:parse))
+          .bind(&method(:decode))
+          .bind(&method(:from_document))
+      end
+
+    private
+
+      def read
+        Either
+          .wrap_error(SystemCallError) { artifact.read }
+          .lmap { |exception| unreadable(exception) }
+      end
+
+      def parse(contents)
+        world.parse_json(contents).lmap { |exception| unreadable(exception) }
+      end
+
+      def decode(data)
+        DOCUMENT.call(data).lmap { |error| INVALID_ARTIFACT % { error: error.compact_message, path: artifact } }
+      end
+
+      def unreadable(exception)
+        UNREADABLE_ARTIFACT % { error: exception, path: artifact }
+      end
+
+      def error(message, **arguments)
+        Either::Left.new(message % { path: artifact, **arguments })
+      end
+
+      def from_document(document)
+        meta   = document.fetch('meta')
+        schema = meta.fetch('schema_version')
+
+        return error(UNKNOWN_SCHEMA, schema: schema.inspect) unless schema.match?(SUPPORTED_SCHEMA)
+
+        contexts = document.fetch('contexts', nil) or return error(NO_CONTEXTS)
+
+        load_tables(contexts:, coverage: document.fetch('coverage'), root: meta.fetch('root'))
+      end
+
+      def load_tables(contexts:, coverage:, root:)
+        ids = contexts.map { |context| ContextMap.normalize(context, root) }
+
+        tables = coverage.each_with_object({}) do |(file, entry), tables|
+          table = entry.fetch('contexts', nil) or next
+
+          resolved = resolve(ids:, table:) or return error(INVALID_ARTIFACT, error: UNKNOWN_CONTEXT % { file: })
+
+          tables[File.expand_path(file.delete_prefix('/'), root)] = resolved
+        end
+
+        Either::Right.new(ContextMap.new(root:, tables:))
+      end
+
+      # nil on an index outside the recording's list. A half read recording
+      # would answer coverage questions with silent gaps, and a silent gap is
+      # a mutation reported alive that no test was ever given the chance to
+      # kill.
+      def resolve(ids:, table:)
+        table.each_with_object({}) do |(index, bitmap), resolved|
+          id = ids.at(index) or return nil
+
+          resolved[id] = resolved.fetch(id, 0) | bitmap
+        end
+      end
+    end # Loader
+    # rubocop:enable Metrics/ClassLength
+  end # ContextMap
+end # Mutant

data/lib/mutant/context_map.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Mutant
+  # Per test coverage, read from the artifact a coverage tool wrote.
+  #
+  # Mutant does not depend on the tool that produces the recording. It reads
+  # the `contexts` sections of simplecov's `coverage.json`, which appear once
+  # `track_tests` is enabled: an interned list of test ids, and per source file
+  # a bitmap of the lines each of those tests executed.
+  #
+  # The recording answers the question the expression selector can only guess
+  # at, which tests actually executed the lines a subject is made of.
+  class ContextMap
+    include Adamantium, Anima.new(:root, :tables)
+
+    # Basename simplecov writes its report under
+    ARTIFACT_BASENAME = 'coverage.json'
+
+    # Report schema versions this reader understands
+    SUPPORTED_SCHEMA = /\A1\./
+
+    # Absolute `path:line` form of a location
+    #
+    # Test ids are recorded relative to the project root, while the
+    # integrations report locations the way their framework spells them. Both
+    # sides pass through here so that they compare as strings.
+    #
+    # @param [String] location
+    # @param [String] root
+    #
+    # @return [String]
+    def self.normalize(location, root)
+      path, separator, line = location.rpartition(':')
+
+      return location if separator.empty?
+
+      "#{File.expand_path(path, root)}:#{line}"
+    end
+
+    # Absolute `path:line` form of a location, against this recording's root
+    #
+    # @param [String] location
+    #
+    # @return [String]
+    def normalize(location) = self.class.normalize(location, root)
+
+    # How many of `lines` in `path` each test executed, for the tests that
+    # executed any of them
+    #
+    # The count is what ranks the tests: one that ran the whole method body is
+    # likelier to reach a mutated expression than one that grazed a guard.
+    #
+    # @param [Pathname] path
+    # @param [Range<Integer>] lines
+    #
+    # @return [Hash{String => Integer}]
+    def reach(path:, lines:)
+      table = tables.fetch(File.expand_path(path), nil)
+
+      return EMPTY_HASH unless table
+
+      # Bit N is line N+1, so the subject's lines are the bits from
+      # `lines.begin - 1` up to and including `lines.end - 1`.
+      mask = (1 << lines.end) - (1 << (lines.begin - 1))
+
+      table.each_with_object({}) do |(context, bitmap), reached|
+        covered = self.class.popcount(bitmap & mask)
+
+        reached[context] = covered unless covered.zero?
+      end
+    end
+
+    # Lines a test executed across the whole project
+    #
+    # The share of that footprint falling inside a subject is how focused the
+    # test is on it. A unit test spends most of its lines there, while a
+    # feature spec touching thousands of lines spends almost none.
+    #
+    # @param [String] context
+    #
+    # @return [Integer]
+    def footprint(context) = footprints.fetch(context, 0)
+
+    # Number of set bits
+    #
+    # Ruby has no population count on Integer, and a binary string is both the
+    # idiom and fast enough at the sizes a line bitmap reaches.
+    #
+    # @param [Integer] value
+    #
+    # @return [Integer]
+    def self.popcount(value) = value.to_s(2).count('1')
+
+    # Every test id the recording knows about
+    #
+    # @return [Set<String>]
+    def context_ids = tables.each_value.flat_map(&:keys).to_set
+    memoize :context_ids
+
+  private
+
+    def footprints
+      tables.each_value.with_object(Hash.new(0)) do |table, totals|
+        table.each { |context, bitmap| totals[context] += self.class.popcount(bitmap) }
+      end
+    end
+    memoize :footprints
+  end # ContextMap
+end # Mutant

data/lib/mutant/integration.rb

@@ -95,7 +95,7 @@ module Mutant
 
     def self.attempt_const_get(env)
       integration_name = env.config.integration.name
-      constant_name    = integration_name.capitalize
+      constant_name    = integration_name.split(/[-_]/).map(&:capitalize).join
 
       Either.wrap_error(NameError) { const_get(constant_name) }.lmap do |exception|
         CONST_MESSAGE % {

data/lib/mutant/matcher/method/instance.rb

@@ -18,6 +18,8 @@ module Mutant
           evaluator =
             if memoized_method?(scope, target_method.name)
               Evaluator::Memoized
+            elsif module_function?(scope, target_method)
+              Evaluator::ModuleFunction
             else
               Evaluator
             end
@@ -39,6 +41,25 @@ module Mutant
         end
         private_class_method :memoized_method?
 
+        # Test if method was exposed via module_function
+        #
+        # module_function makes the instance method private and copies it
+        # onto the singleton class, where it keeps the source location.
+        #
+        # @param [Scope] scope
+        # @param [UnboundMethod] target_method
+        #
+        # @return [Boolean]
+        def self.module_function?(scope, target_method)
+          raw         = scope.raw
+          method_name = target_method.name
+
+          raw.private_method_defined?(method_name) &&
+            raw.singleton_class.public_method_defined?(method_name) &&
+            raw.singleton_class.instance_method(method_name).source_location.eql?(target_method.source_location)
+        end
+        private_class_method :module_function?
+
         # Instance method specific evaluator
         class Evaluator < Evaluator
           MATCH_NODE_TYPE = :def
@@ -75,6 +96,11 @@ module Mutant
             end
 
           end # Memoized
+
+          # Evaluator specialized for module_function instance methods
+          class ModuleFunction < self
+            SUBJECT_CLASS = Subject::Method::Instance::ModuleFunction
+          end # ModuleFunction
         end # Evaluator
 
         private_constant(*constants(false))

data/lib/mutant/meta.rb

@@ -25,7 +25,7 @@ module Mutant
         )
       end
 
-      Pathname.glob(Pathname.new(__dir__).parent.parent.join('meta', '*.rb'))
+      Pathname.glob(Pathname.new(__dir__).parent.parent.join('meta', '**', '*.rb'))
         .sort
         .each(&method(:require))
 

data/lib/mutant/mutation/runner/sink.rb

@@ -8,12 +8,16 @@ module Mutant
 
         include Anima.new(:env)
 
+        # Minimum seconds between two session flushes
+        FLUSH_INTERVAL = 1.0
+
         # Initialize object
         #
         # @return [undefined]
         def initialize(*)
           super
           @start           = env.world.timer.now
+          @last_flush_at   = @start - FLUSH_INTERVAL
           @subject_results = {}
         end
 
@@ -48,10 +52,11 @@ module Mutant
           mutation        = env.mutations.fetch(response.result.mutation_index)
           subject         = mutation.subject
           mutation_result = mutation_result(mutation, response.result)
+          coverage        = coverage_result(mutation_result)
 
           @subject_results[subject] = Result::Subject.new(
             amount_mutations:  subject.mutations.length,
-            coverage_results:  previous_coverage_results(subject).dup << coverage_result(mutation_result),
+            coverage_results:  previous_coverage_results(subject).dup << coverage,
             expression_syntax: subject.expression.syntax,
             identification:    subject.identification,
             node:              subject.node,
@@ -60,6 +65,8 @@ module Mutant
             tests:             env.selections.fetch(subject)
           )
 
+          flush_session unless coverage.success?
+
           self
         end
       # rubocop:enable Metrics/AbcSize
@@ -67,6 +74,25 @@ module Mutant
 
       private
 
+        # Persist the session on alive mutations, so survivors are
+        # inspectable while a long run is still going, rather than only
+        # after its final write.
+        #
+        # Alive mutations can arrive far faster than once per second, and
+        # each flush serializes the whole result tree on the main process,
+        # so flushes are rate limited against the monotonic timer. A
+        # survivor that lands inside the suppressed window is picked up by
+        # the next flush, or by the final write in the runner.
+        def flush_session
+          now = env.world.timer.now
+
+          return if (now - @last_flush_at) < FLUSH_INTERVAL
+
+          @last_flush_at = now
+
+          Result::JSONWriter.new(env:, result: status).call
+        end
+
         def coverage_result(mutation_result)
           Result::Coverage.new(
             mutation_result:,

data/lib/mutant/mutation/runner.rb

@@ -19,6 +19,7 @@ module Mutant
           .record(:analysis) { run_driver(reporter, async_driver(env)) }
           .tap { |result| env.record(:report) { reporter.report(result) } }
           .tap { |result| Result::JSONWriter.new(env:, result:).call }
+          .tap { Result::SessionFiles.new(world: env.world).prune(Result::SessionFiles::KEEP) }
       end
       private_class_method :run_mutation_analysis
 

data/lib/mutant/mutator/node/itblock.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mutant
+  class Mutator
+    class Node
+      class Itblock < self
+
+        handle(:itblock)
+
+        children :receiver, :parameter, :body
+
+      private
+
+        def dispatch
+          emit_nil
+          emit_receiver_mutations(&method(:n_send?))
+          emit_body_mutations(&method(:references_it?))
+        end
+
+        def references_it?(node)
+          return true if node.eql?(s(:lvar, :it))
+
+          children = owns_it?(node) ? [node.children.first] : node.children
+
+          children.any? do |child|
+            child.instance_of?(::Parser::AST::Node) && references_it?(child)
+          end
+        end
+
+        def owns_it?(node)
+          n_block?(node) || n_itblock?(node) || n_def?(node) || n_defs?(node)
+        end
+      end # Itblock
+    end # Node
+  end # Mutator
+end # Mutant

data/lib/mutant/reporter/cli/printer/env.rb

@@ -13,10 +13,12 @@ module Mutant
             :amount_subjects,
             :amount_all_tests,
             :config,
+            :selector,
             :test_subject_ratio
           )
 
           FORMATS = [
+            [:info,   'Selection:       %s',        :selection_name        ],
             [:info,   'Subjects:        %s',        :amount_subjects       ],
             [:info,   'All-Tests:       %s',        :amount_all_tests      ],
             [:info,   'Available-Tests: %s',        :amount_available_tests],
@@ -35,6 +37,10 @@ module Mutant
               __send__(report, format, __send__(value))
             end
           end
+
+        private
+
+          def selection_name = selector.name
         end # Env
       end # Printer
     end # CLI

data/lib/mutant/result/json_writer.rb

@@ -2,21 +2,31 @@
 
 module Mutant
   module Result
-    # Write result JSON to .mutant/results/
+    # Write result JSON to .mutant/results/, gzip compressed
     class JSONWriter
       include Anima.new(:env, :result)
 
-      RESULTS_DIR = '.mutant/results'
+      # Log stored in place of the log of a covered mutation
+      EMPTY_LOG = LogCapture::String.new(content: '')
 
       # Write result JSON file
       #
+      # The JSON repeats the source, diff, and tests of each mutation,
+      # and compresses about twentyfold.
+      #
+      # Written to a temporary file first and renamed into place, so a
+      # concurrent reader of the session file never observes a partial
+      # document. This matters once the file is rewritten during a run.
+      #
       # @return [Pathname]
       def call
-        dir = env.world.pathname.new(RESULTS_DIR)
+        dir = env.world.pathname.new(SessionFiles::DIRECTORY)
         dir.mkpath
 
-        path = dir.join("#{SESSION_ID}.json")
-        path.write(json)
+        path = dir.join("#{SESSION_ID}.json.gz")
+        tmp_path = dir.join("#{SESSION_ID}.json.gz.tmp")
+        tmp_path.binwrite(Zlib.gzip(json))
+        tmp_path.rename(path)
 
         path
       end
@@ -35,7 +45,29 @@ module Mutant
           ruby_version:    RUBY_VERSION,
           runtime:         result.runtime,
           session_id:      SESSION_ID,
-          subject_results: result.subject_results
+          subject_results: result.subject_results.map(&method(:without_covered_logs))
+        )
+      end
+
+      def without_covered_logs(subject_result)
+        subject_result.with(
+          coverage_results: subject_result.coverage_results.map(&method(:without_log))
+        )
+      end
+
+      # The log of a covered mutation is the output of the tests that
+      # killed it. The session subcommands only report alive mutations,
+      # so nothing reads it back, and on a suite whose failures print
+      # large values it is most of the session file.
+      def without_log(coverage_result)
+        return coverage_result unless coverage_result.success?
+
+        mutation_result = coverage_result.mutation_result
+
+        coverage_result.with(
+          mutation_result: mutation_result.with(
+            isolation_result: mutation_result.isolation_result.with(log: EMPTY_LOG)
+          )
         )
       end
     end # JSONWriter

data/lib/mutant/result/session_files.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mutant
+  module Result
+    # The session files of past runs in .mutant/results/
+    class SessionFiles
+      include Anima.new(:world)
+
+      DIRECTORY = '.mutant/results'
+
+      # Sessions this version writes gzip compressed, and those earlier
+      # versions wrote as plain JSON. The plain ones are listed first,
+      # each kind oldest first, as the earlier versions wrote them before
+      # this one wrote any.
+      PATTERN = '*.json{,.gz}'
+
+      # Sessions a run keeps, and `mutant session gc` keeps by default
+      KEEP = 100
+
+      # The session files, oldest first
+      #
+      # @return [Array<Pathname>]
+      def paths
+        dir = world.pathname.new(DIRECTORY)
+
+        return EMPTY_ARRAY unless dir.directory?
+
+        dir.glob(PATTERN)
+      end
+
+      # Delete all but the most recent sessions
+      #
+      # A session written alongside this one by a concurrent run may
+      # have been deleted by that run already.
+      #
+      # @param [Integer] keep
+      #
+      # @return [Array<Pathname>]
+      #   the deleted session files
+      def prune(keep)
+        excess = paths.reverse.drop(keep)
+
+        excess.each do |path|
+          path.delete
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end # SessionFiles
+  end # Result
+end # Mutant

data/lib/mutant/result.rb

@@ -375,7 +375,7 @@ module Mutant
       end
 
       load_test = Transform::Success.new(
-        block: ->(id) { Mutant::Test.new(expressions: EMPTY_ARRAY, id:) }
+        block: ->(id) { Mutant::Test.new(expressions: EMPTY_ARRAY, id:, location: nil) }
       )
 
       derive_node = Transform::Success.new(