simplecov 0.22.0 → 1.3.0

data/exe/simplecov

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "simplecov/cli"
+exit SimpleCov::CLI.run(ARGV)

data/lib/minitest/simplecov_plugin.rb

@@ -1,15 +1,26 @@
 # frozen_string_literal: true
 
-# How minitest plugins. See https://github.com/simplecov-ruby/simplecov/pull/756 for why we need this.
-# https://github.com/seattlerb/minitest#writing-extensions
 module Minitest
+  # Handles the SimpleCov-first / Minitest-second ordering: `SimpleCov.start`
+  # runs before `require "minitest/autorun"`, so its start-time detection can't
+  # see Minitest yet, but by the time this plugin fires Minitest is loaded and
+  # the same switch can be flipped. The opposite ordering is handled in
+  # `SimpleCov.install_at_exit_hook` (#756).
+  #
+  # The respond_to? guards cover a process where only simplecov's version file
+  # was loaded (#877), which defines the SimpleCov constant without any of its
+  # configuration.
   def self.plugin_simplecov_init(_options)
-    if defined?(SimpleCov)
-      SimpleCov.external_at_exit = true
+    return unless defined?(SimpleCov)
 
-      Minitest.after_run do
-        SimpleCov.at_exit_behavior
-      end
+    SimpleCov::TestTracker.install_minitest_hook if SimpleCov.respond_to?(:track_tests?) && SimpleCov.track_tests?
+
+    return if SimpleCov.external_at_exit?
+
+    SimpleCov.external_at_exit = true
+
+    Minitest.after_run do
+      SimpleCov.at_exit_behavior
     end
   end
 end

data/lib/simplecov/atomic_file.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+module SimpleCov
+  # Replaces an artifact through a collision-safe temporary file in the
+  # destination directory, so readers see either the old or the complete new
+  # file.
+  module AtomicFile
+    DEFAULT_MODE = 0o666
+    private_constant :DEFAULT_MODE
+
+    def self.write(path, content, binary: false)
+      directory = File.dirname(path)
+      FileUtils.mkdir_p(directory)
+      mode = destination_mode(path)
+
+      Tempfile.create([".simplecov-", ".tmp"], directory) do |temp|
+        replace(temp, path, content, mode, binary: binary)
+      end
+
+      nil
+    end
+
+    # Closing flushes the last buffered bytes, so the rename publishes a complete
+    # file rather than whatever happened to reach disk. No cleanup of its own:
+    # `Tempfile.create` closes and removes the file when its block ends, however
+    # it ends.
+    def self.replace(temp, path, content, mode, binary:)
+      temp.binmode if binary
+      temp.write(content)
+      temp.close
+      File.chmod(mode, temp)
+      rename_over(temp, path)
+    end
+    private_class_method :replace
+
+    # On POSIX systems rename replaces the destination atomically. On Windows it
+    # fails with EACCES when the destination is open in a reader or
+    # mid-replacement by a concurrent writer, so retry briefly there.
+    def self.rename_over(temp, path)
+      remaining = 10
+      begin
+        File.rename(temp, path)
+      rescue Errno::EACCES
+        raise unless Gem.win_platform?
+
+        remaining -= 1
+        raise if remaining.zero?
+
+        sleep(0.01)
+        retry
+      end
+    end
+    private_class_method :rename_over
+
+    def self.destination_mode(path)
+      return DEFAULT_MODE & ~File.umask if File.symlink?(path)
+
+      File.stat(path).mode & 0o777
+    rescue Errno::ENOENT
+      DEFAULT_MODE & ~File.umask
+    end
+    private_class_method :destination_mode
+  end
+end

data/lib/simplecov/autostart.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Loaded via `RUBYOPT="-rsimplecov/autostart"` from `simplecov run`. The require
+# below also auto-loads `~/.simplecov` and the project's `.simplecov`, which may
+# already call `SimpleCov.start`. That call is idempotent, so making it
+# unconditionally is the safe way to ensure the report is formatted at exit.
+
+require "simplecov"
+SimpleCov.start

data/lib/simplecov/baseline/parser.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class Baseline
+    # Turns the YAML document of a baseline file into the
+    # `{path => {criterion => Floor}}` entries `Baseline` holds. The canonical
+    # shape is the criteria Hash `to_yaml` writes, but the lenient shapes stay
+    # readable: a bare number is a line-percent floor, and a criterion may carry
+    # a bare percent instead of the percent/missed pair. Anything else raises
+    # ConfigurationError, naming the file and the offending entry: a malformed
+    # policy must fail loudly rather than silently un-enforce every floor.
+    module Parser
+      extend self
+
+      def call(data, path)
+        raise ConfigurationError, "baseline file #{path} must map file paths to floors" unless data.is_a?(Hash)
+
+        data.to_h { |file, entry| [file.to_s, parse_entry(file, entry, path)] }
+      end
+
+      def parse_entry(file, entry, path)
+        return {line: Floor.new(percent: entry, missed: nil)} if entry.is_a?(Numeric)
+
+        unless entry.is_a?(Hash)
+          raise ConfigurationError, "baseline file #{path}: entry for #{file} must be a number or a criteria Hash"
+        end
+
+        entry.to_h do |criterion_key, floor|
+          [parse_criterion(file, criterion_key, path), parse_floor(file, floor, path)]
+        end
+      end
+
+      def parse_criterion(file, criterion_key, path)
+        CRITERIA[criterion_key.to_s] || raise(
+          ConfigurationError,
+          "baseline file #{path}: unknown criterion #{criterion_key.inspect} for #{file} " \
+          "(expected lines, branches, or methods)"
+        )
+      end
+
+      def parse_floor(file, floor, path)
+        return Floor.new(percent: floor, missed: nil) if floor.is_a?(Numeric)
+
+        percent = floor["percent"] if floor.is_a?(Hash)
+        unless percent.is_a?(Numeric)
+          raise ConfigurationError, "baseline file #{path}: floor for #{file} needs a numeric percent"
+        end
+
+        missed = floor["missed"]
+        unless missed.nil? || missed.instance_of?(Integer)
+          raise ConfigurationError, "baseline file #{path}: missed count for #{file} must be an integer"
+        end
+
+        Floor.new(percent: percent, missed: missed)
+      end
+    end
+  end
+end

data/lib/simplecov/baseline.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module SimpleCov
+  # The checked-in per-file coverage floor behind `simplecov ratchet` (#1268):
+  # `.rubocop_todo.yml` applied to coverage. Each entry records, per criterion,
+  # the percent a file has already reached and the number of misses it had when
+  # that percent was recorded.
+  #
+  # A floor carries both numbers because each covers for the other's blind
+  # spot. The percent is the policy, but a percent moves when a file is edited
+  # without any coverage change at all, so the missed count acts as the
+  # dampener. A violation therefore requires both a lower percent and more
+  # misses, which is the honest reading of "this file got worse".
+  class Baseline
+    DEFAULT_FILENAME = ".simplecov_baseline.yml"
+
+    HEADER = <<~HEADER
+      # Per-file coverage floors. A file that drops below its floor fails the run,
+      # and files with no entry fall through to the global per-file minimum.
+      # Regenerate with `simplecov ratchet`. Floors only ever tighten.
+    HEADER
+    private_constant :HEADER
+
+    # The YAML file speaks the report's vocabulary; internally floors are keyed
+    # by criterion the way the threshold configuration is.
+    CRITERIA = {"lines" => :line, "branches" => :branch, "methods" => :method}.freeze
+    private_constant :CRITERIA
+
+    # `missed` is nil for a hand-written percent-only entry, meaning the
+    # dampener is absent and the percent alone decides.
+    Floor = Data.define(:percent, :missed)
+
+    # The tightened baseline plus the path lists the CLI summarizes (each path
+    # appears in exactly one).
+    Outcome = Data.define(:baseline, :tightened, :pruned, :regressed, :unchanged)
+
+    # A file that exists but cannot be read as a baseline raises
+    # ConfigurationError: a malformed policy must fail loudly rather than
+    # silently un-enforce every floor it carried.
+    def self.read_if_exists(path)
+      return nil unless File.exist?(path)
+
+      new(Parser.call(YAML.safe_load_file(path), path))
+    rescue Psych::Exception => e
+      # Interpolating the exception renders the message Psych objected with.
+      raise ConfigurationError, "baseline file #{path} is not valid YAML: #{e}"
+    end
+
+    # `current` is a `{project_filename => {criterion => {percent:, missed:}}}`
+    # Hash of the measured state. Everything the report carries gets a floor at
+    # its current coverage.
+    def self.read(path)
+      Deprecation.warn("`SimpleCov::Baseline.read` is deprecated. Replace with `read_if_exists`.")
+      read_if_exists(path)
+    end
+
+    def self.generate(current)
+      new(current.transform_values do |criteria|
+        criteria.transform_values { |floor| Floor.new(percent: floor.fetch(:percent), missed: floor.fetch(:missed)) }
+      end)
+    end
+
+    attr_reader :entries
+
+    def initialize(entries)
+      @entries = entries
+    end
+
+    def entry_for(project_filename)
+      entries[project_filename]
+    end
+
+    def floor_for(project_filename, criterion)
+      entries.dig(project_filename, criterion)
+    end
+
+    # Which is also what exempts the pair from the per-file thresholds.
+    def covers?(project_filename, criterion)
+      !floor_for(project_filename, criterion).nil?
+    end
+
+    # Floors only move in the tightening direction, each axis independently:
+    # the percent keeps its best, the missed count its lowest. Entries for
+    # files `current` does not carry are pruned; files `current` carries
+    # without an entry stay uncovered, so new code answers to the global
+    # standard rather than to a floor cut at whatever it launched with. A
+    # criterion the current run did not measure keeps its floor, and a newly
+    # measured criterion joins the entry, so a later `enable_coverage :branch`
+    # grandfathers the legacy files' branch state.
+    def ratchet(current)
+      buckets = {tightened: [], pruned: [], regressed: [], unchanged: []} #: Hash[Symbol, Array[String]]
+      ratcheted = entries.filter_map do |file, entry|
+        step = ratchet_entry(entry, current[file])
+        buckets.fetch(step.fetch(:bucket)) << file
+        merged = step[:entry]
+        [file, merged] if merged
+      end.to_h
+
+      Outcome.new(baseline: Baseline.new(ratcheted), tightened: buckets.fetch(:tightened),
+        pruned: buckets.fetch(:pruned), regressed: buckets.fetch(:regressed),
+        unchanged: buckets.fetch(:unchanged))
+    end
+
+    # Sorted by path so a ratchet rewrite diffs as the set of floors that
+    # actually moved.
+    def to_yaml
+      document = entries.sort.to_h do |file, entry|
+        [file, entry.to_h { |criterion, floor| [CRITERIA.key(criterion), dump_floor(floor)] }]
+      end
+      HEADER + YAML.dump(document).delete_prefix("---\n")
+    end
+
+    private
+
+    # A nil current prunes the entry, which carries no replacement and so
+    # answers with the bucket alone. Otherwise every measured criterion
+    # tightens, keeping the ones this run did not measure.
+    def ratchet_entry(entry, current_entry)
+      return {bucket: :pruned} unless current_entry
+
+      merged = (entry.keys | current_entry.keys).to_h do |criterion|
+        [criterion, tighten(entry[criterion], current_entry[criterion])]
+      end
+      {bucket: bucket_for(entry, merged, current_entry), entry: merged}
+    end
+
+    # The regressed bucket mirrors the violation rule exactly, so "below its
+    # floor" in the ratchet summary always means the exit check fails the file,
+    # never a percent drift the dampener tolerates.
+    def bucket_for(entry, merged, current_entry)
+      # Exact equality rather than numeric: tightening keeps the entry's own
+      # floor on a tie, so an entry that did not move is the very values it
+      # came in with.
+      return :tightened unless merged.eql?(entry)
+
+      regressed = entry.any? do |criterion, floor|
+        current = current_entry[criterion]
+        current && current.fetch(:percent) < floor.percent &&
+          (floor.missed.nil? || current.fetch(:missed) > floor.missed)
+      end
+      regressed ? :regressed : :unchanged
+    end
+
+    # Either side may be absent: a floor with no current measurement stays, a
+    # measurement with no floor becomes one.
+    def tighten(floor, current)
+      # The keys union in ratchet_entry guarantees at least one side is present,
+      # which the cast restates for the type checker.
+      return (_ = floor) unless current
+
+      current_floor = Floor.new(percent: current.fetch(:percent), missed: current.fetch(:missed))
+      return current_floor unless floor
+
+      Floor.new(
+        percent: [floor.percent, current_floor.percent].max,
+        missed: [floor.missed, current_floor.missed].compact.min
+      )
+    end
+
+    def dump_floor(floor)
+      dumped = {"percent" => floor.percent} #: Hash[String, untyped]
+      dumped["missed"] = floor.missed unless floor.missed.nil?
+      dumped
+    end
+  end
+end
+
+require_relative "baseline/parser"

data/lib/simplecov/cli/affected/changed_files.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../git"
+
+module SimpleCov
+  module CLI
+    module Affected
+      # The change as git sees it, as `{root:, changed:}`: the files that differ
+      # between the merge base of the given ref and the working tree, so commits
+      # that landed on the base after the branch point stay out while uncommitted
+      # work stays in, unioned with untracked files, since a brand-new spec exists
+      # in no diff. Everything runs against the repository toplevel rather than the
+      # cwd, so a subdirectory run selects over the whole change. NUL separation
+      # keeps exotic filenames literal instead of quoted.
+      module ChangedFiles
+        extend self
+
+        def call(base, stderr)
+          return report(stderr, "invalid base ref #{base.inspect}") if Git.option_like_ref?(base)
+
+          root = repository_toplevel(stderr)
+          return nil unless root
+
+          diff = list("diff", ["-C", root, "diff", "--name-only", "-z", "--merge-base", base, "--"], stderr)
+          return nil unless diff
+
+          untracked = list("ls-files", ["-C", root, "ls-files", "--others", "--exclude-standard", "-z"], stderr)
+          untracked && {root: root, changed: (diff + untracked).uniq}
+        end
+
+        # nil stdout from `Git.capture` means git never ran; a run that failed
+        # means the cwd is outside a working tree.
+        def repository_toplevel(stderr)
+          stdout, detail, success = Git.capture("rev-parse", "--show-toplevel")
+          return (_ = stdout).chomp if success
+          return report(stderr, "cannot run git (#{detail})") if stdout.nil?
+
+          report(stderr, "not inside a git working tree")
+        end
+
+        # git's own first stderr line is relayed on failure, so a bad ref or an old
+        # git names itself.
+        def list(command, argv, stderr)
+          stdout, detail, success = Git.capture(*argv)
+          return (_ = stdout).split("\0") if success
+          return report(stderr, "cannot run git (#{detail})") if stdout.nil?
+
+          report(stderr, "`git #{command}` failed: #{detail}")
+        end
+
+        def report(stderr, message)
+          stderr.puts("simplecov affected: #{message}")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/affected/selection.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Affected
+      module Selection
+        TEST_FILE_NAME = /\A(?:test_.*|.*_(?:test|spec))\.rb\z/
+
+        extend self
+
+        def build(changed, document, contexts, opts, stderr, root:)
+          none = {} #: Hash[String, untyped]
+          coverage = document.fetch("coverage", none)
+          unless coverage.instance_of?(Hash)
+            return CoverageFile.report_invalid(stderr, "affected", opts.fetch(:input), '"coverage" must be an object')
+          end
+
+          state = initial_state(changed, contexts, coverage, opts, stderr, root: root)
+          return nil unless changed.all? { |path| classify(path, state) }
+
+          {tests: state.fetch(:tests).uniq.sort, triggers: state.fetch(:triggers)}
+        end
+
+        def initial_state(changed, contexts, coverage, opts, stderr, root:)
+          {
+            tests: [], triggers: [], changed: changed, contexts: contexts,
+            known: contexts.each_with_object(Set.new) { |id, set| set << test_file_of(id) },
+            index: CoverageFile.exact_index(coverage), root: root, opts: opts, stderr: stderr
+          } #: Hash[Symbol, untyped]
+        end
+
+        # A recorded test file selects itself, a file the report covers selects the
+        # files of the tests touching it, a test-looking file the map has never seen
+        # always runs, and anything else is a trigger. Changed paths are exact
+        # root-relative names, so they resolve against the report exactly: a
+        # lookalike entry elsewhere must not stand in for a file it doesn't carry.
+        def classify(path, state)
+          entry = entry_for(path, state)
+          if state.fetch(:known).include?(path)
+            select_test_file(path, state)
+          elsif entry
+            select_covering(path, entry, state)
+          elsif TEST_FILE_NAME.match?(File.basename(path))
+            select_test_file(path, state, note_deleted: false)
+          else
+            note_untracked(path, state)
+          end
+        end
+
+        def note_untracked(path, state)
+          state.fetch(:triggers) << "#{path} changed but #{state.fetch(:opts).fetch(:input)} has no data for it"
+        end
+
+        # A changed test file runs, unless the change is its deletion: its tests are
+        # gone, which removes them from the answer without distrusting the map.
+        def select_test_file(path, state, note_deleted: true)
+          if on_disk?(path, state)
+            state.fetch(:tests) << path
+          elsif note_deleted
+            state.fetch(:stderr).puts("simplecov affected: skipping deleted test file #{path}")
+          end
+          path
+        end
+
+        # Existence judged at the repository root the paths are relative to, not the
+        # cwd, so a subdirectory run answers the same.
+        def on_disk?(path, state)
+          File.exist?(File.expand_path(path, state.fetch(:root)))
+        end
+
+        def entry_for(path, state)
+          state.fetch(:index)[File.expand_path(path, state.fetch(:root))] || state.fetch(:index)[path]
+        end
+
+        def select_covering(path, entry, state)
+          table = covering_table(path, entry, state)
+          table&.each_key { |index| select_context(state.fetch(:contexts).fetch(index), path, state) }
+        end
+
+        def covering_table(path, entry, state)
+          unless entry.instance_of?(Hash)
+            return CoverageFile.report_invalid(state.fetch(:stderr), "affected", state.fetch(:opts).fetch(:input),
+              "entry for #{path} must be an object")
+          end
+
+          raw = entry["contexts"] || {}
+          table = raw.instance_of?(Hash) && Tests.decode_table(raw, state.fetch(:contexts).size)
+          return table if table
+
+          CoverageFile.report_invalid(state.fetch(:stderr), "affected", state.fetch(:opts).fetch(:input),
+            "entry for #{path} carries a malformed \"contexts\" table")
+        end
+
+        # Selected via its file, or a staleness trigger when it has no file to
+        # select: a locationless id, or a file that exists neither on disk nor in
+        # the change.
+        def select_context(id, path, state)
+          file = test_file_of(id)
+          if file.nil?
+            state.fetch(:triggers) << "recorded test #{id} touches #{path} but has no file location"
+          elsif on_disk?(file, state)
+            state.fetch(:tests) << file
+          elsif !state.fetch(:changed).include?(file)
+            state.fetch(:triggers) << "recorded test file #{file} no longer exists"
+          end
+        end
+
+        # "spec/a_spec.rb:12" and the :file granularity's bare "spec/a_spec.rb" both
+        # name a file, while a locationless fallback id names none.
+        def test_file_of(id)
+          base = id.sub(/:\d+\z/, "")
+          base if base.include?("/") || base.end_with?(".rb")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/affected.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+require_relative "tests"
+require_relative "affected/changed_files"
+require_relative "affected/selection"
+
+module SimpleCov
+  module CLI
+    # `simplecov affected`: select the test files whose recorded tests touch the
+    # code changed since a git base ref, from a coverage.json written under
+    # `track_tests`. The change is everything between the merge base of `--base`
+    # and the working tree, plus untracked files.
+    #
+    # The set intersection is the easy half; the hard half is knowing when to
+    # distrust the map, because a test map is stale the moment something changes
+    # that no test mentions by name. Any changed file outside the tracked set
+    # fails open to the full suite, out loud: each trigger is named on stderr and
+    # stdout stays empty, which a bare runner reads as "run everything". Test
+    # files always select themselves, recorded or not.
+    module Affected
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        issue = precheck(opts)
+        return error(stderr, issue) if issue
+
+        document = CoverageFile.load_document(opts.fetch(:input), command: "affected", stderr: stderr)
+        return 1 unless document
+
+        contexts = recorded_contexts(document, opts, stderr)
+        return 1 unless contexts
+
+        diffed = ChangedFiles.call(opts[:base] ||= Git.default_base, stderr)
+        return 1 unless diffed
+
+        respond(diffed, document, contexts, opts, stdout: stdout, stderr: stderr)
+      end
+
+      def parse(args)
+        head, runner = split_runner(args)
+        opts, rest = parse_common(head, base: nil, run: runner) do |parser, into|
+          parser.on("--base REF") { |v| into[:base] = v }
+        end
+        opts[:rest] = rest
+        opts
+      end
+
+      # Everything after `--run` is the runner command, verbatim, so the command's
+      # own flags never collide with ours.
+      def split_runner(args)
+        index = args.index("--run")
+        return [args, nil] unless index
+
+        [args.take(index), args.drop(index + 1)]
+      end
+
+      # A stray positional looks exactly like a forgotten `--base` ref, and
+      # silently dropping it would select tests for the wrong change.
+      def precheck(opts)
+        stray = opts.fetch(:rest).first
+        return "unexpected argument #{stray.inspect} (did you mean `--base #{stray}`?)" if stray
+        return "missing command after --run" if opts.fetch(:run) && opts.fetch(:run).empty?
+
+        "--run and --json cannot be combined" if opts.fetch(:run) && opts.fetch(:json)
+      end
+
+      def respond(diffed, document, contexts, opts, stdout:, stderr:)
+        opts[:root] = diffed.fetch(:root)
+        return no_changes(opts, stdout, stderr) if diffed.fetch(:changed).empty?
+
+        selection = Selection.build(diffed.fetch(:changed), document, contexts, opts, stderr, root: diffed.fetch(:root))
+        return 1 unless selection
+
+        deliver(selection, opts, stdout, stderr)
+      end
+
+      def no_changes(opts, stdout, stderr)
+        stderr.puts("simplecov affected: no changes against #{opts.fetch(:base)}")
+        empty = {tests: [], triggers: []} #: Hash[Symbol, Array[String]]
+        emit_json(empty, false, stdout) if opts.fetch(:json)
+        0
+      end
+
+      def deliver(selection, opts, stdout, stderr)
+        full = !selection.fetch(:triggers).empty?
+        selection.fetch(:triggers).each { |trigger| stderr.puts("simplecov affected: #{trigger}") }
+        stderr.puts("simplecov affected: falling back to the full suite") if full
+        return emit_json(selection, full, stdout) if opts.fetch(:json)
+        return execute(selection, full, opts, stderr) if opts.fetch(:run)
+
+        emit_text(selection, full, stdout, stderr)
+      end
+
+      def emit_json(selection, full, stdout)
+        none = [] #: Array[String]
+        stdout.puts(JSON.pretty_generate("full_suite" => full, "triggers" => selection.fetch(:triggers),
+          "tests" => full ? none : selection.fetch(:tests)))
+        0
+      end
+
+      # Stdout carries the selected files and nothing else, so the list can feed a
+      # runner directly, and a full-suite fallback prints nothing, which
+      # `rspec $(simplecov affected)` reads as "run everything".
+      def emit_text(selection, full, stdout, stderr)
+        return 0 if full
+
+        tests = selection.fetch(:tests)
+        if tests.empty?
+          note_untouched(stderr)
+        else
+          tests.each { |file| stdout.puts(file) }
+          0
+        end
+      end
+
+      def note_untouched(stderr)
+        stderr.puts("simplecov affected: no recorded test touches the changed code")
+        0
+      end
+
+      def execute(selection, full, opts, stderr)
+        return run_command(opts.fetch(:run), opts.fetch(:root), stderr) if full
+        return note_untouched(stderr) if selection.fetch(:tests).empty?
+
+        count = selection.fetch(:tests).size
+        stderr.puts("simplecov affected: running #{count} test file#{"s" unless count.eql?(1)}")
+        run_command(opts.fetch(:run) + selection.fetch(:tests), opts.fetch(:root), stderr)
+      end
+
+      # The selection's paths are relative to the repository root, so the runner
+      # starts there. The command is named explicitly in the failure because not
+      # every engine's exception message carries it.
+      def run_command(command, root, stderr)
+        _, status = Process.wait2(spawn(*command, chdir: root))
+        status.exitstatus || 1
+      rescue SystemCallError => e
+        stderr.puts("simplecov affected: cannot run #{command.first.inspect} (#{e})")
+        127
+      end
+    end
+  end
+end