mutant 0.16.3 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f7a495dc61f610e15c0b43ee64726016fa2feb694ce948e9554478f15c60c03
-  data.tar.gz: 11c45dd1db15519c9647ac2b13a8c794ddacb3a4a396e90ea2c6accfb6e71dd0
+  metadata.gz: 752a1938022756ae4d788946052f227269843741bafc857cb9be24bd94b5a272
+  data.tar.gz: b7f0ec5bc7a221c9503c923d20781a061826826acb3caf605a4601e77a808bb5
 SHA512:
-  metadata.gz: 8c52e9fa61e9b8ad827cd02f37469654201115c06251330a7eb695a9909b79d355fa9c9d555002d96650589c36d71046436462736754e7a33438f2b03c11bf37
-  data.tar.gz: 7a1a190d3e17f1bfc3bee1584023b6f7756b97d2b79ffa6f42a93ce2b70c0d323e29b0bd7bd4010204d3bbac3a26a82deaa04163c4fc83044d1cb799ecd5d4a8
+  metadata.gz: ae4b675e810a9b94f340e9888722eb1a72b78f8bcb008dd0dec44919a3f5d4ef3d440f117c4c159db59528a6362b3b53ea6e0ec808833798d7f9f4ca1c0ab633
+  data.tar.gz: a95c6b2b83be6d672284bc6139cd8f37fb29a1a02e5babc3a5c304b6a6eeba143b37d68b6dee39c5de6355c93800435443e9abdf68e4ffd301cdb60b334d9dd5

data/VERSION

@@ -1 +1 @@
-0.16.3
+0.17.0

data/lib/mutant/bootstrap.rb

@@ -12,6 +12,15 @@ module Mutant
   module Bootstrap
     include Adamantium, Anima.new(:config, :parser, :world)
 
+    UNMATCHED_CONTEXT_MAP = <<~'MESSAGE'
+      The coverage recording names no test that this suite runs, so it cannot
+      say which tests cover a subject.
+
+      Record it again from the project root, with the suite mutant runs. A suite
+      that starts simplecov unconditionally rewrites the recording every time
+      mutant runs it, so start simplecov only when measuring coverage.
+    MESSAGE
+
     SEMANTICS_MESSAGE_FORMAT =
       "%<message>s. Fix your lib to follow normal ruby semantics!\n" \
       '{Module,Class}#name should return resolvable constant name as String or nil'
@@ -77,18 +86,58 @@ module Mutant
       env.record(__method__) do
         hooks = env.hooks
         hooks.run(:setup_integration_pre)
-        Integration.setup(env).fmap do |integration|
-          env.with(
-            integration:,
-            mutations:,
-            selector:    Selector::Expression.new(integration:),
-            subjects:    selected_subjects
-          ).tap { hooks.run(:setup_integration_post) }
+        Integration.setup(env).bind do |integration|
+          setup_selector(env:, integration:).fmap do |selector|
+            env.with(
+              integration:,
+              mutations:,
+              selector:,
+              subjects:    selected_subjects
+            ).tap { hooks.run(:setup_integration_post) }
+          end
         end
       end
     end
     private_class_method :setup_integration
 
+    # The selector the configured strategy asks for
+    #
+    # The default is to use the coverage recording whenever there is a usable
+    # one and the expressions otherwise, so a project that records per test
+    # coverage gets the better selection without asking for it. Naming
+    # `context_map` explicitly turns every reason the recording cannot be used
+    # into a failed run, rather than a silent downgrade to a selection the user
+    # did not ask for.
+    #
+    # @return [Either<String, Selector>]
+    def self.setup_selector(env:, integration:)
+      selection = env.config.selection
+      fallback  = Selector::Expression.new(integration:)
+
+      return Either::Right.new(fallback) if selection.expression?
+
+      result = env.record(__method__) do
+        ContextMap::Loader
+          .call(path: env.world.pathname.new(selection.effective_path), world: env.world)
+          .bind { |context_map| context_map_selector(context_map:, fallback:, integration:) }
+      end
+
+      selection.context_map? ? result : Either::Right.new(result.from_right { fallback })
+    end
+    private_class_method :setup_selector
+
+    # A recording that names no test of this suite was taken somewhere else, and
+    # answering selection from it would report every mutation alive without ever
+    # running a test that could have killed it.
+    #
+    # @return [Either<String, Selector>]
+    def self.context_map_selector(context_map:, fallback:, integration:)
+      selector = Selector::ContextMap.new(context_map:, fallback:, integration:)
+
+      selector.unmatched? ? Either::Left.new(UNMATCHED_CONTEXT_MAP) : Either::Right.new(selector)
+    end
+    private_class_method :context_map_selector
+
     # rubocop:enable Metrics/MethodLength
     def self.load_hooks(env)
       env.record(__method__) do

data/lib/mutant/cli/command/environment.rb

@@ -5,8 +5,9 @@ module Mutant
     class Command
       # rubocop:disable Metrics/ClassLength
       class Environment < self
-        NAME              = 'environment'
-        SHORT_DESCRIPTION = 'Environment subcommands'
+        NAME                  = 'environment'
+        SHORT_DESCRIPTION     = 'Environment subcommands'
+        SELECTION_DESCRIPTION = 'Select tests via STRATEGY: auto|expression|context_map'
 
         OPTIONS =
           %i[
@@ -14,6 +15,7 @@ module Mutant
             add_runner_options
             add_integration_options
             add_matcher_options
+            add_selection_options
             add_reporter_options
             add_usage_options
           ].freeze
@@ -116,6 +118,22 @@ module Mutant
           end
         end
 
+        def add_selection_options(parser)
+          parser.separator('Selection:')
+
+          parser.on('--selection STRATEGY', Config::Selection::STRATEGIES, SELECTION_DESCRIPTION) do |strategy|
+            selection(strategy:)
+          end
+
+          parser.on('--selection-path PATH', 'Read the coverage report from PATH') do |path|
+            selection(path:)
+          end
+        end
+
+        def selection(**attributes)
+          set(selection: @config.selection.with(attributes))
+        end
+
         def add_runner_options(parser)
           parser.separator('Runner:')
 

data/lib/mutant/config/selection.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Mutant
+  class Config
+    # Configuration of how tests get selected for a subject
+    class Selection
+      include Adamantium, Anima.new(:path, :strategy)
+
+      # Use the coverage recording when there is one, and the expressions
+      # otherwise. Mutant's default.
+      AUTO = 'auto'
+
+      # Select tests whose expressions match the subject's
+      EXPRESSION = 'expression'
+
+      # Select tests a coverage recording says executed the subject's lines
+      CONTEXT_MAP = 'context_map'
+
+      STRATEGIES = [AUTO, EXPRESSION, CONTEXT_MAP].freeze
+
+      # Directory coverage tools write their report into
+      DEFAULT_PATH = 'coverage'
+
+      UNKNOWN_STRATEGY = 'Unknown test selection strategy %s, expected one of: %s'
+
+      private_constant(:UNKNOWN_STRATEGY)
+
+      # Both attributes stay nil until set, so a value from mutant.yml is not
+      # overwritten by a default coming from the CLI end of the merge.
+      DEFAULT = new(path: nil, strategy: nil)
+
+      TRANSFORM =
+        Transform::Sequence.new(
+          steps: [
+            Transform::Hash.new(
+              optional: [
+                Transform::Hash::Key.new(
+                  transform: Transform::STRING,
+                  value:     'path'
+                ),
+                Transform::Hash::Key.new(
+                  transform: Transform::STRING,
+                  value:     'strategy'
+                )
+              ],
+              required: []
+            ),
+            Transform::Hash::Symbolize.new,
+            Transform::Block.capture(:selection) { |value| new(**DEFAULT.to_h, **value).validate }
+          ]
+        )
+
+      # Whether the recording is the only acceptable source of tests
+      #
+      # @return [Boolean]
+      def context_map? = strategy.eql?(CONTEXT_MAP)
+
+      # Whether the expressions are the only acceptable source of tests
+      #
+      # @return [Boolean]
+      def expression? = strategy.eql?(EXPRESSION)
+
+      # The configured recording location, or the conventional one
+      #
+      # @return [String]
+      def effective_path = path || DEFAULT_PATH
+
+      # Reject a strategy mutant does not implement
+      #
+      # @return [Either<String, Selection>]
+      def validate
+        return Either::Right.new(self) if strategy.nil? || STRATEGIES.include?(strategy)
+
+        Either::Left.new(UNKNOWN_STRATEGY % [strategy.inspect, STRATEGIES.join(', ')])
+      end
+
+      # Merge with other selection config
+      #
+      # Values from the other instance have precedence.
+      #
+      # @param [Selection] other
+      #
+      # @return [Selection]
+      def merge(other)
+        self.class.new(
+          path:     other.path || path,
+          strategy: other.strategy || strategy
+        )
+      end
+    end # Selection
+  end # Config
+end # Mutant

data/lib/mutant/config.rb

@@ -22,6 +22,7 @@ module Mutant
       :mutation,
       :reporter,
       :requires,
+      :selection,
       :usage
     )
 
@@ -89,6 +90,7 @@ module Mutant
         matcher:               matcher.merge(other.matcher),
         mutation:              mutation.merge(other.mutation),
         requires:              requires + other.requires,
+        selection:             selection.merge(other.selection),
         usage:                 other.usage.merge(usage)
       )
     end
@@ -269,6 +271,10 @@ module Mutant
             transform: Transform::STRING_ARRAY,
             value:     'requires'
           ),
+          Transform::Hash::Key.new(
+            transform: ->(value) { Selection::TRANSFORM.call(value) },
+            value:     'selection'
+          ),
           Transform::Hash::Key.new(
             transform: Usage::TRANSFORM,
             value:     'usage'

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/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/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

@@ -10,13 +10,19 @@ module Mutant
 
       # Write result JSON file
       #
+      # 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.mkpath
 
         path = dir.join("#{SESSION_ID}.json")
-        path.write(json)
+        tmp_path = dir.join("#{SESSION_ID}.json.tmp")
+        tmp_path.write(json)
+        tmp_path.rename(path)
 
         path
       end

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(

data/lib/mutant/selector/context_map.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Mutant
+  class Selector
+    # Test selector backed by a per test coverage recording
+    #
+    # Selects the tests that executed the subject's own source lines, which
+    # finds the tests that cover a subject regardless of where they live or how
+    # they are named. Subjects the recording says nothing about fall back to the
+    # expression selector: code that only runs while the suite loads (a constant
+    # body, a class level DSL call) executes under no test, and reporting its
+    # mutations alive without running a single test would be a lie.
+    class ContextMap < self
+      include Anima.new(:context_map, :fallback, :integration)
+
+      # Name of the strategy this selector implements
+      #
+      # @return [String]
+      def name = 'context_map'
+
+      # Tests for subject, likeliest killer first
+      #
+      # @param [Subject] subject
+      #
+      # @return [Enumerable<Test>]
+      def call(subject)
+        reach = context_map.reach(path: subject.source_path, lines: subject.source_lines)
+
+        covering = reach.flat_map do |location, lines|
+          index.fetch(location, EMPTY_ARRAY).map { |test| [test, lines, context_map.footprint(location)] }
+        end
+
+        return fallback.call(subject) if covering.empty?
+
+        order(covering, subject)
+      end
+
+      # Whether the recording names no test this suite runs
+      #
+      # A recording taken from another project root, or from a suite that has
+      # since been renamed away, covers everything and matches nothing. Left
+      # unsaid it looks exactly like a suite in which no test covers anything.
+      #
+      # @return [Boolean]
+      def unmatched?
+        index.each_key.none? { |location| context_map.context_ids.include?(location) }
+      end
+
+    private
+
+      # A run against a mutation stops at the first failing test, so this order
+      # is the difference between running one test and running all of them.
+      #
+      # A test the expressions would also have picked is the subject's own unit
+      # test, and no measurement beats that prior, so those go first as a block.
+      # Within each block comes the test spending the largest share of its own
+      # footprint inside this subject, since a test that exists for this code
+      # asserts on it where a feature spec passing through may swallow the
+      # difference. Reach breaks the remaining ties, because a test that ran
+      # more of the subject's lines is likelier to have run the mutated one.
+      def order(covering, subject)
+        named, rest = covering.partition { |test, _lines, _footprint| expression_match?(subject, test) }
+
+        (by_focus(named) + by_focus(rest)).map(&:first)
+      end
+
+      # The test id breaks a full tie, so the order depends on the recording's
+      # content rather than on the order a coverage tool happened to write it.
+      def by_focus(covering)
+        covering.sort_by { |test, lines, footprint| [-Rational(lines, footprint), -lines, test.id] }
+      end
+
+      # The question the expression selector asks of one test, rather than the
+      # set it builds by asking it of every test in the suite.
+      def expression_match?(subject, test)
+        subject.match_expressions.any? do |match_expression|
+          test.expressions.any? { |test_expression| match_expression.prefix?(test_expression) }
+        end
+      end
+
+      # Tests by the location the recording would name them under. A location
+      # holds more than one test whenever a framework generates examples from
+      # one line, so the value is a list.
+      def index
+        integration.available_tests.each_with_object({}) do |test, index|
+          location = test.location or next
+
+          (index[context_map.normalize(location)] ||= []) << test
+        end
+      end
+      memoize :index
+    end # ContextMap
+  end # Selector
+end # Mutant

data/lib/mutant/selector/expression.rb

@@ -6,6 +6,11 @@ module Mutant
     class Expression < self
       include Anima.new(:integration)
 
+      # Name of the strategy this selector implements
+      #
+      # @return [String]
+      def name = 'expression'
+
       # Tests for subject
       #
       # @param [Subject] subject

data/lib/mutant/selector/null.rb

@@ -6,6 +6,11 @@ module Mutant
     class Null < self
       include Equalizer.new
 
+      # Name of the strategy this selector implements
+      #
+      # @return [String]
+      def name = 'null'
+
       # Tests for subject
       #
       # @param [Subject] subject

data/lib/mutant/selector.rb

@@ -12,5 +12,10 @@ module Mutant
     # @return [Enumerable<Test>]
     abstract_method :call
 
+    # Name of the strategy this selector implements
+    #
+    # @return [String]
+    abstract_method :name
+
   end # Selector
 end # Mutant

data/lib/mutant/test.rb

@@ -5,7 +5,8 @@ module Mutant
   class Test
     include Anima.new(
       :expressions,
-      :id
+      :id,
+      :location
     )
 
     # Identification string

data/lib/mutant/transform.rb

@@ -295,6 +295,75 @@ module Mutant
         end
       end # Key
 
+      # Transform reducing a hash to the keys it names
+      #
+      # A document another tool writes carries keys mutant has no use for,
+      # and gains more between versions. Slicing ahead of a Hash transform
+      # lets that transform stay strict about the keys it does know.
+      class Slice < Transform
+        include Anima.new(:keys)
+
+        # Apply transformation to input
+        #
+        # @param [Object] input
+        #
+        # @return [Either<Error, Hash>]
+        def call(input)
+          PRIMITIVE
+            .call(input)
+            .lmap(&method(:lift_error))
+            .fmap { |hash| hash.slice(*keys) }
+        end
+      end # Slice
+
+      # Transform a hash keyed by data via mapping its pairs over key and
+      # value transforms
+      #
+      # Where Hash names the keys it accepts, this accepts every key the key
+      # transform does.
+      class Map < Transform
+        include Anima.new(:key, :value)
+
+        DUPLICATE_MESSAGE = 'Key transform maps distinct keys onto one'
+
+        private_constant(*constants(false))
+
+        # Apply transformation to input
+        #
+        # @param [Object] input
+        #
+        # @return [Either<Error, Hash>]
+        def call(input)
+          PRIMITIVE
+            .call(input)
+            .lmap(&method(:lift_error))
+            .bind(&method(:run))
+        end
+
+      private
+
+        # rubocop:disable Metrics/MethodLength
+        def run(input)
+          output = input.to_h do |key_input, value_input|
+            [
+              coerce(key, key_input, key_input).from_right { |error| return failure(error(cause: error, input:)) },
+              coerce(value, key_input, value_input).from_right { |error| return failure(error(cause: error, input:)) }
+            ]
+          end
+
+          if output.size.equal?(input.size)
+            success(output)
+          else
+            failure(error(input:, message: DUPLICATE_MESSAGE))
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def coerce(transform, key, input)
+          Key.new(value: key, transform:).call(input)
+        end
+      end # Map
+
       # Apply transformation to input
       #
       # @param [Object] input

data/lib/mutant.rb

@@ -225,13 +225,17 @@ module Mutant
     require 'mutant/timer'
     require 'mutant/integration'
     require 'mutant/integration/null'
+    require 'mutant/context_map'
+    require 'mutant/context_map/loader'
     require 'mutant/selector'
+    require 'mutant/selector/context_map'
     require 'mutant/selector/expression'
     require 'mutant/selector/null'
     require 'mutant/world'
     require 'mutant/hooks'
     require 'mutant/config'
     require 'mutant/config/coverage_criteria'
+    require 'mutant/config/selection'
     require 'mutant/cli'
     require 'mutant/cli/command'
     require 'mutant/cli/command/environment'
@@ -378,6 +382,7 @@ module Mutant
       mutation:              Mutation::Config::EMPTY,
       reporter:              Reporter::CLI.build(WORLD.stdout),
       requires:              EMPTY_ARRAY,
+      selection:             Config::Selection::DEFAULT,
       usage:                 Usage::Unknown.new
     )
   end # Config

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutant
 version: !ruby/object:Gem::Version
-  version: 0.16.3
+  version: 0.17.0
 platform: ruby
 authors:
 - Markus Schirp
@@ -235,7 +235,10 @@ files:
 - lib/mutant/cli/command/util.rb
 - lib/mutant/config.rb
 - lib/mutant/config/coverage_criteria.rb
+- lib/mutant/config/selection.rb
 - lib/mutant/context.rb
+- lib/mutant/context_map.rb
+- lib/mutant/context_map/loader.rb
 - lib/mutant/env.rb
 - lib/mutant/expression.rb
 - lib/mutant/expression/descendants.rb
@@ -391,6 +394,7 @@ files:
 - lib/mutant/segment.rb
 - lib/mutant/segment/recorder.rb
 - lib/mutant/selector.rb
+- lib/mutant/selector/context_map.rb
 - lib/mutant/selector/expression.rb
 - lib/mutant/selector/null.rb
 - lib/mutant/subject.rb