simplecov 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9446e795d35024cc5d47004e88956620c65c6f666fe387323f4192947e942125
-  data.tar.gz: 85596147a4854e414574ab09b7329ffd1e949aa6a1f108308e1364712f19b491
+  metadata.gz: 774f2590be4fc8efd720e8c61b8e0678b50794dbc8c881c5872c51ac7b318c08
+  data.tar.gz: a67efdab2414345fa195aea9015d5cfc5128c452be20888edc1814c05fff98e0
 SHA512:
-  metadata.gz: 12e270b345de7dd7f2abaaafe9ab9d3034b4c6489e9c465a7bfb0d71de1f66382053e0c43621ac57a49f4194503bbcc692107f1770e3775986ac023dbb06a23c
-  data.tar.gz: 50a81cb51a4186ac664ca01003c4d7ae3ed8b1e0dff7abdf83ce359c490e016fb6f8d4f0fa5e69433934978b8be1f08e8cd530900538d377f4d508771e055323
+  metadata.gz: 32062ccc9c83227f868788d5f2a0fa43eda93e8f714ed4ffe068fea3ac05ee7dd21f26d4234903da7679a6c72325955282000055892deaabf4a0703f924f06ca
+  data.tar.gz: c4a9a68bfbed7bc9c38de07afd89bedfefd3ea1ff1ee2b5294701c588c6cca7a10ae571313e0d836478045c07fcee81e4a1dc20c258d92e13a46f1e044c4d6d5

data/README.md

@@ -1,4 +1,4 @@
-SimpleCov [![Gem Version](https://badge.fury.io/rb/simplecov.svg)](https://badge.fury.io/rb/simplecov) [![Build Status](https://github.com/simplecov-ruby/simplecov/actions/workflows/stable.yml/badge.svg?branch=main)][ci] [![Lint](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml) [![Typecheck](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/c071d197d61953a7e482/maintainability)](https://codeclimate.com/github/simplecov-ruby/simplecov/maintainability)
+SimpleCov [![Gem Version](https://badge.fury.io/rb/simplecov.svg)](https://badge.fury.io/rb/simplecov) [![Build Status](https://github.com/simplecov-ruby/simplecov/actions/workflows/stable.yml/badge.svg?branch=main)][ci] [![Lint](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml) [![Typecheck](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml) [![Mutation](https://github.com/simplecov-ruby/simplecov/actions/workflows/mutation.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/mutation.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/c071d197d61953a7e482/maintainability)](https://codeclimate.com/github/simplecov-ruby/simplecov/maintainability)
 =========
 
 **Code coverage for Ruby**
@@ -108,8 +108,10 @@ SimpleCov.start 'rails'
 ## Configuration at a glance
 
 Configuration goes in your start block, or in a `.simplecov` file at the
-project root when several test suites share it. Some of the most common
-settings:
+project root when several test suites share it. The API is built around a
+small set of consistent verbs: formatters are picked by name, thresholds
+live in a per-criterion `coverage` block where scope is a uniform `per:`
+argument, and misses can be capped as absolute counts rather than ratios:
 
 ```ruby
 SimpleCov.start do
@@ -121,9 +123,150 @@ SimpleCov.start do
   coverage :line do
     minimum      90                  # fail the suite below 90% line coverage
     maximum_drop 1                   # ...or when coverage drops more than 1%
+    maximum_missed 5, per: :file     # no file may carry more than 5 uncovered lines
   end
+
+  coverage :branch, minimum: 80, ignore: :implicit_else
+end
+```
+
+Everything you're using today keeps working. Legacy spellings warn and name
+their replacement, and once you've migrated, `deprecations :raise` turns any
+old spelling that creeps back in into an error. The
+[migration map](docs/Configuration.md#migrating-from-the-legacy-configuration-api)
+has the full before and after, and every option is documented in
+[docs/Configuration.md](docs/Configuration.md), including criteria, filters,
+groups, profiles, and thresholds.
+
+## Tracking which test covers each line
+
+Coverage normally tells you whether a line ran, not what ran it. `track_tests`
+records the other half of the story:
+
+```ruby
+SimpleCov.start do
+  track_tests
 end
 ```
 
-Every option is documented in [docs/Configuration.md](docs/Configuration.md),
-including criteria, filters, groups, profiles, and thresholds.
+RSpec examples and Minitest tests are wrapped automatically. In the HTML
+report, covered lines that no test executed (they only ran at load time, or in
+suite setup) drain to a distinct tint, so coverage that merely *loads* code
+stops passing for coverage that *tests* it, and clicking a line's badge lists
+the tests that cover it. The same recording answers from the terminal:
+
+```sh
+$ simplecov tests lib/simplecov/result.rb:42
+spec/result_spec.rb:42
+```
+
+The output is one test id per line and nothing else, so it pipes straight into
+a runner. `simplecov tests --redundant` inverts the question, listing the
+tests whose covered lines other tests also cover, which is where a
+[test-pruning session](docs/Redundant_Tests.md) starts. Recording has a real
+cost, which is why it's opt-in and comes with levers to control it. See
+[the configuration docs](docs/Configuration.md#tracking-which-test-covers-each-line).
+
+## Finding dead code in production
+
+SimpleCov can also measure production code usage, the surest way to find
+dead code. The old trick was to plant a log line in a suspect method and
+watch production for a while. Oneshot coverage runs that experiment for
+every line at once: a line reports its first execution and nothing after,
+so a live process records what real traffic uses with the least possible
+impact on performance. `simplecov dead-code` then crosses the recording
+with the test report and turns it into insight you can act on. Code
+neither tests nor traffic touch is safe to delete, and code production
+runs but tests skip is the most valuable test you haven't written. The
+HTML report and `coverage.json` include the same production data. See
+[docs/Production.md](docs/Production.md) for more details on why and how
+to set it up.
+
+## Coverage of just your change
+
+An overall number moves slowly on a mature codebase, but "is the code in this
+change tested?" has a crisp answer the day you ask it. `simplecov patch` reads
+the git diff against a base ref and scores only the lines you touched:
+
+```sh
+$ simplecov patch --base main --minimum 100
+   88.00% (22/25) lines  lib/simplecov/cli/patch.rb  missing 41-43
+  100.00% (4/4) lines    lib/simplecov/result.rb
+  Patch coverage:  89.66% (26/29) lines
+```
+
+`--minimum` turns it into a gate, so a project that can't lift its overall
+number in one pull request can still require that everything it adds is
+covered. The flip side is `simplecov affected`, which uses a `track_tests`
+recording to select the tests that touch your changed code and hand them to
+the runner, falling back (loudly) to the full suite whenever the map can't be
+trusted:
+
+```sh
+$ simplecov affected --base main --run bundle exec rspec
+```
+
+Both commands are documented in [the CLI docs](docs/CLI.md).
+
+## Covering views
+
+View templates execute real logic, and now they can be part of the report.
+`cover_views` brings ERB, Haml, and Slim templates in, measured through eval
+coverage (CRuby 3.2+):
+
+```ruby
+SimpleCov.start 'rails' do
+  cover_views
+end
+```
+
+Templates are ordinary files in the report, highlighted in their own language
+and grouped under Views by the `rails` profile, and a template no test renders
+shows up at 0% instead of being quietly missing. Expect your overall number to
+drop the first time you turn this on. That's the point. See
+[view coverage](docs/Configuration.md#view-coverage).
+
+## Per-file ratchets and coverage history
+
+On a legacy codebase, one per-file minimum does nothing useful: set it to what
+the worst file scores and every other file is allowed to sink to that level.
+`simplecov ratchet` writes a checked-in baseline instead, giving each file its
+own floor at the coverage it has already reached:
+
+```sh
+$ simplecov ratchet
+simplecov ratchet: wrote .simplecov_baseline.yml (3 tightened, 1 pruned, 148 unchanged)
+```
+
+Floors only ever tighten, so touching a legacy file drags its coverage upward
+and it can never slide back. Think `.rubocop_todo.yml`, applied to coverage.
+To ratchet automatically at the end of every run, add the baseline formatter
+with `formats :html, :baseline`.
+
+Alongside the floors, every successful run now appends to
+`coverage/.history.json`, so you have a recorded trend rather than just the
+last number. `simplecov history` draws it as sparklines in the terminal, and
+`drop_baseline :median` judges coverage drops against the recorded median
+instead of whatever the previous run happened to score. See
+[the baseline](docs/Configuration.md#per-file-baseline-ratchet) and
+[run history](docs/Configuration.md#run-history) docs.
+
+## More from the command line
+
+The `simplecov` CLI has grown from a report opener into a toolbelt. A few
+favorites:
+
+```sh
+$ simplecov watch bundle exec rspec   # re-run on save, live-reload the served report
+$ simplecov show lib/foo.rb           # annotated source in the terminal
+$ simplecov status                    # is this report fresh, and for which commit?
+$ simplecov uncovered --missing       # worst files, with the exact line ranges to test
+$ simplecov badge --output badge.svg  # a shields.io-style SVG, no badge service needed
+```
+
+`watch` deserves the highlight: with a `track_tests` recording in the report,
+a save re-runs only the tests that touch the files you changed, which turns
+the report into something you keep open while writing the test. There is also
+shell tab completion (`simplecov completions fish|bash|zsh`), a man page, and
+a real `--help` on every command. The full tour is in
+[docs/CLI.md](docs/CLI.md).

data/exe/simplecov

@@ -1,9 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Make `./exe/simplecov` work from a fresh checkout, not only via
-# `bundle exec`. RubyGems and Bundler already inject lib/ for an
-# installed gem; this is a no-op in that case.
 lib = File.expand_path("../lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 

data/lib/minitest/simplecov_plugin.rb

@@ -1,17 +1,20 @@
 # 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
-#
-# Handles the SimpleCov-first / Minitest-second ordering: SimpleCov.start
-# runs before `require "minitest/autorun"`, so the SimpleCov.start-time
-# detection in `install_at_exit_hook` can't see Minitest yet. By the time
-# this plugin fires (inside `Minitest.run`), Minitest is loaded and we
-# can flip the same switch. The opposite ordering (Minitest first) is
-# handled in `SimpleCov.install_at_exit_hook` — see `#minitest_autorun_pending?`.
 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)
     return unless defined?(SimpleCov)
+
+    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

data/lib/simplecov/atomic_file.rb

@@ -5,7 +5,8 @@ require "tempfile"
 
 module SimpleCov
   # Replaces an artifact through a collision-safe temporary file in the
-  # destination directory, so readers see either the old or complete new file.
+  # destination directory, so readers see either the old or the complete new
+  # file.
   module AtomicFile
     DEFAULT_MODE = 0o666
     private_constant :DEFAULT_MODE
@@ -22,38 +23,34 @@ module SimpleCov
       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.path)
-      rename_over(temp.path, path)
-    ensure
-      temp.close unless temp.closed?
-      FileUtils.rm_f(temp.path)
+      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 before giving up.
-    def self.rename_over(temp_path, path)
-      attempts = 0
+    # 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, path)
+        File.rename(temp, path)
       rescue Errno::EACCES
-        # simplecov:disable branch — which arm runs is fixed by the platform
         raise unless Gem.win_platform?
 
-        # simplecov:enable branch
-        # simplecov:disable — Windows-only; unreachable where dogfood runs
-        attempts += 1
-        raise if attempts >= 10
+        remaining -= 1
+        raise if remaining.zero?
 
         sleep(0.01)
         retry
-        # simplecov:enable
       end
     end
     private_class_method :rename_over

data/lib/simplecov/autostart.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
-# Loaded via `RUBYOPT="-rsimplecov/autostart"` from `simplecov run`. The
-# `require "simplecov"` here also auto-loads `~/.simplecov` and the
-# project's `.simplecov` (per simplecov/defaults.rb), which may already
-# call `SimpleCov.start`. `SimpleCov.start` is idempotent — it won't
-# restart Coverage if it's already running, and `install_at_exit_hook`
-# guards against double-installing — so calling it unconditionally is
-# the safe way to ensure the report is formatted at exit.
+# 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