simplecov 0.22.0 → 1.1.1

data/exe/simplecov

@@ -0,0 +1,11 @@
+#!/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)
+
+require "simplecov/cli"
+exit SimpleCov::CLI.run(ARGV)

data/lib/minitest/simplecov_plugin.rb

@@ -2,14 +2,22 @@
 
 # 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
   def self.plugin_simplecov_init(_options)
-    if defined?(SimpleCov)
-      SimpleCov.external_at_exit = true
+    return unless defined?(SimpleCov)
+    return if SimpleCov.external_at_exit?
 
-      Minitest.after_run do
-        SimpleCov.at_exit_behavior
-      end
+    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,70 @@
+# 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 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
+
+    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)
+    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
+      begin
+        File.rename(temp_path, 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
+
+        sleep(0.01)
+        retry
+        # simplecov:enable
+      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,11 @@
+# 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.
+require "simplecov"
+SimpleCov.start

data/lib/simplecov/cli/clean.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov clean [--dry-run]` — remove the coverage report
+    # directory (or whatever `SimpleCov.coverage_dir` resolves to). The
+    # `--dry-run` flag prints what would be deleted without touching
+    # disk, for when you're not sure what's in there.
+    module Clean
+      extend CommandHelpers
+
+    module_function
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args)
+        dir = SimpleCov::CLI.coverage_dir
+        return error(stderr, "refusing to remove unsafe coverage directory #{dir.inspect}") unless safe_to_remove?(dir)
+        return announce(stdout, opts, "#{dir} doesn't exist; nothing to do") || 0 unless File.directory?(dir)
+
+        sweep(dir, opts, stdout)
+        0
+      end
+
+      def sweep(dir, opts, stdout)
+        if opts[:dry_run]
+          announce(stdout, opts, "would remove #{dir} (#{entry_count(dir)} entries)")
+        else
+          require "fileutils"
+          FileUtils.rm_rf(dir)
+          announce(stdout, opts, "removed #{dir}")
+        end
+      end
+
+      # FNM_DOTMATCH so the dotfiles rm_rf will actually delete
+      # (.resultset.json, .last_run.json) count too; the glob still
+      # yields the directory's own "." entry, which rm_rf does not
+      # remove separately.
+      def entry_count(dir)
+        Dir.glob("#{dir}/**/*", File::FNM_DOTMATCH).count { |path| !path.end_with?("/.") }
+      end
+
+      def announce(stdout, opts, message)
+        stdout.puts("simplecov #{command_name}: #{message}") unless opts[:quiet]
+      end
+
+      def safe_to_remove?(dir)
+        target = canonical_path(dir)
+        # A filesystem root is its own dirname ("/" everywhere, drive
+        # roots like "D:/" on Windows). The descendant check below only
+        # protects roots that happen to contain the cwd or project root,
+        # which misses other drives, so refuse roots outright.
+        return false if File.dirname(target) == target
+
+        protected_paths.none? { |path| path == target || descendant_of?(path, target) }
+      end
+
+      def protected_paths
+        project_root = SimpleCov::CLI::Dotfile.find
+        [Dir.pwd, (File.dirname(project_root) if project_root)].compact.map { |path| canonical_path(path) }.uniq
+      end
+
+      # Canonical paths only carry a trailing separator on a filesystem
+      # root, and roots are refused before this check runs.
+      def descendant_of?(path, possible_ancestor)
+        path.start_with?("#{possible_ancestor}#{File::SEPARATOR}")
+      end
+
+      def canonical_path(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      def parse(args)
+        opts = {dry_run: false, quiet: false}
+        OptionParser.new do |o|
+          o.on("--dry-run") { opts[:dry_run] = true }
+          o.on("-q", "--quiet") { opts[:quiet] = true }
+        end.parse(args)
+        opts
+      end
+    end
+  end
+end

data/lib/simplecov/cli/command_helpers.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module SimpleCov
+  module CLI
+    # Plumbing the subcommands repeat, which their modules `extend`: the
+    # standard option trio the read-only commands share, the parse
+    # scaffold around it, the one-line error helper (prefixed with the
+    # command's own name), and the human-readable stats row `coverage`
+    # and `report` both print.
+    module CommandHelpers
+      STATS_ROW_FORMAT = "  %<label>-7s %<pct>s (%<covered>d / %<total>d)"
+
+      # "simplecov merge: ..." — derived from the extending module's
+      # name. The self cast collapses the mixin's view of `self` to the
+      # Module that extends it, which is what carries `name`.
+      def command_name
+        (_ = self).name.split("::").last.downcase
+      end
+
+      def error(stderr, message)
+        stderr.puts("simplecov #{command_name}: #{message}")
+        1
+      end
+
+      # The --input / --json / --no-color trio every read-only
+      # subcommand accepts.
+      def common_options(parser, opts)
+        parser.on("--input PATH") { |v| opts[:input] = v }
+        parser.on("--json")       { opts[:json] = true }
+        parser.on("--no-color")   { opts[:no_color] = true }
+      end
+
+      # The parse scaffold every read-only subcommand repeats: seed the
+      # shared defaults (plus the command's own), wire up the common
+      # option trio, yield the parser for command-specific flags, and
+      # return the parsed opts alongside the positional arguments.
+      def parse_common(args, defaults = {})
+        opts = {input: SimpleCov::CLI.default_input, json: false, no_color: false} #: Hash[Symbol, untyped]
+        opts.merge!(defaults)
+        rest =
+          OptionParser.new do |parser|
+            common_options(parser, opts)
+            yield parser, opts if block_given?
+          end.parse(args)
+        [opts, rest]
+      end
+
+      def stats_row(label, percent_text, covered, total)
+        format(STATS_ROW_FORMAT, label: "#{label}:", pct: percent_text, covered: covered.to_i, total: total.to_i)
+      end
+    end
+  end
+end

data/lib/simplecov/cli/coverage.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov coverage <path>` — print per-criterion stats for one
+    # file from a JSONFormatter coverage.json.
+    module Coverage
+      extend CommandHelpers
+
+    module_function
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args, stderr: stderr)
+        return 1 unless opts
+
+        match = locate_match(opts, stderr)
+        return 1 unless match
+
+        emit(match, opts, stdout)
+        0
+      end
+
+      def parse(args, stderr:)
+        opts, rest = parse_common(args)
+        return stderr.puts("simplecov coverage: missing file argument") && nil if rest.empty?
+
+        opts[:path] = rest.first
+        opts
+      end
+
+      def locate_match(opts, stderr)
+        coverage = CoverageFile.load_coverage(opts[:input], command: "coverage", stderr: stderr)
+        return unless coverage
+
+        match = lookup(coverage, opts[:path])
+        if match.nil?
+          stderr.puts("simplecov coverage: no entry for #{opts[:path]} in #{opts[:input]}")
+          return nil
+        end
+        # A wrong-typed entry used to escape here and crash print_human.
+        return match if match.last.is_a?(Hash)
+
+        CoverageFile.report_invalid(stderr, "coverage", opts[:input], "entry for #{opts[:path]} must be an object")
+      end
+
+      # Match either the absolute path, the literal string passed, or
+      # any coverage entry whose absolute filename ends with "/<path>".
+      # That covers the three natural ways a user types a path: relative
+      # to project root ("app/foo.rb"), absolute, or basename-only.
+      def lookup(coverage_hash, path)
+        absolute = File.expand_path(path)
+        suffix   = "/#{path}"
+        coverage_hash.find { |fname, _| fname == absolute || fname == path || fname.end_with?(suffix) }
+      end
+
+      def emit(match, opts, stdout)
+        filename, payload = match
+        if opts[:json]
+          entry = {filename => payload} #: Hash[untyped, untyped]
+          stdout.puts(JSON.pretty_generate(entry))
+        else
+          print_human(filename, payload, stdout, SimpleCov::CLI.color_enabled?(opts, stdout))
+        end
+      end
+
+      def print_human(filename, payload, stdout, color)
+        stdout.puts(filename)
+        CoverageFile::CRITERIA.each_value { |c| emit_criterion(stdout, payload, c, color) }
+      end
+
+      def emit_criterion(stdout, payload, criterion, color)
+        return unless payload.key?(criterion[:percent])
+
+        pct = payload[criterion[:percent]].to_f
+        stdout.puts(stats_row(criterion[:label],
+                              SimpleCov::Color.colorize_percent(pct, enabled: color),
+                              payload[criterion[:covered]],
+                              payload[criterion[:total]]))
+      end
+    end
+  end
+end

data/lib/simplecov/cli/coverage_file.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../coverage_json"
+
+module SimpleCov
+  module CLI
+    # Shared input boundary for commands that consume JSONFormatter's
+    # coverage.json. It validates only the stable outer shape so older schema
+    # versions remain readable.
+    module CoverageFile
+      # The coverage.json fields backing each criterion, keyed by the
+      # criterion's singular name. The one table the coverage, uncovered,
+      # and diff subcommands all read from, so a schema change lands in
+      # exactly one place.
+      CRITERIA = {
+        line: {label: "Line", percent: "lines_covered_percent",
+               covered: "covered_lines", total: "total_lines"},
+        branch: {label: "Branch", percent: "branches_covered_percent",
+                 covered: "covered_branches", total: "total_branches"},
+        method: {label: "Method", percent: "methods_covered_percent",
+                 covered: "covered_methods", total: "total_methods"}
+      }.freeze
+
+    module_function
+
+      def load_document(path, command:, stderr:)
+        SimpleCov::CoverageJSON.load(path)
+      rescue Errno::ENOENT
+        report_missing(stderr, command, path)
+      rescue SimpleCov::CoverageJSON::Error => e
+        report_invalid(stderr, command, path, e.message)
+      rescue SystemCallError => e
+        report_unreadable(stderr, command, path, e.message)
+      end
+
+      def load_coverage(path, command:, stderr:)
+        document = load_document(path, command: command, stderr: stderr)
+        return unless document
+
+        none = {} #: Hash[String, untyped]
+        coverage = document.fetch("coverage", none)
+        return coverage if coverage.is_a?(Hash)
+
+        report_invalid(stderr, command, path, '"coverage" must be an object')
+      end
+
+      def report_invalid(stderr, command, path, reason)
+        detail = reason.lines.first.to_s.strip
+        stderr.puts("simplecov #{command}: input file #{path.inspect} isn't valid JSON (#{detail})")
+        nil
+      end
+
+      def report_missing(stderr, command, path)
+        stderr.puts("simplecov #{command}: #{path} not found")
+        nil
+      end
+
+      def report_unreadable(stderr, command, path, reason)
+        detail = reason.lines.first.to_s.strip
+        stderr.puts("simplecov #{command}: cannot read #{path.inspect} (#{detail})")
+        nil
+      end
+    end
+  end
+end

data/lib/simplecov/cli/diff.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov diff <baseline>` — print per-file coverage deltas between
+    # coverage.json (--input) and a baseline coverage.json
+    # checked in alongside the suite. Only files whose coverage moved
+    # are listed; --fail-on-drop exits non-zero when any file regressed,
+    # so this composes with CI as a "coverage of this PR didn't drop"
+    # gate. Resolves the long-standing "diff coverage" feature request.
+    module Diff
+      extend CommandHelpers
+
+      EPSILON = 0.005 # tolerance below which a delta is considered noise
+
+      STATUS_SUFFIX = {"added" => "(new file)", "removed" => "(removed)"}.freeze
+
+    module_function
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args, stderr)
+        return 1 unless opts
+
+        rows = compute_rows(opts[:current], opts[:baseline], opts[:threshold])
+        rows.sort_by! { |row| row[:line_delta] }
+        if opts[:json]
+          stdout.puts(JSON.pretty_generate(rows))
+        else
+          emit_text(stdout, rows, SimpleCov::CLI.color_enabled?(opts, stdout))
+        end
+        opts[:fail_on_drop] && coverage_drop?(rows) ? 1 : 0
+      end
+
+      def parse(args, stderr)
+        opts = parse_flags(args)
+        return stderr.puts("simplecov diff: missing baseline argument") && nil if opts[:rest].empty?
+
+        opts[:baseline] = load_coverage(opts[:rest].first, stderr) or return nil
+        opts[:current]  = load_coverage(opts[:input], stderr) or return nil
+        opts
+      end
+
+      def parse_flags(args)
+        opts, rest = parse_common(args, fail_on_drop: false, threshold: 0.0) do |o, options|
+          o.on("--fail-on-drop")       { options[:fail_on_drop] = true }
+          o.on("--threshold N", Float) { |v| options[:threshold] = v }
+        end
+        opts.merge(rest: rest)
+      end
+
+      def load_coverage(path, stderr)
+        coverage = CoverageFile.load_coverage(path, command: "diff", stderr: stderr)
+        return unless coverage
+
+        normalize_keys(coverage)
+      end
+
+      # Strip a leading slash so coverage.json files written before the
+      # `project_filename` change (keys like "/lib/foo.rb") still diff
+      # cleanly against newer reports (keys like "lib/foo.rb").
+      def normalize_keys(coverage)
+        coverage.transform_keys { |key| key.delete_prefix("/") }
+      end
+
+      def compute_rows(current, baseline, threshold)
+        files = current.keys | baseline.keys
+        files.filter_map { |fname| compute_row(fname, current[fname], baseline[fname], threshold) }
+      end
+
+      # EPSILON keeps float noise out regardless of threshold; the
+      # threshold itself is inclusive, so a file that moved exactly N%
+      # is listed under `--threshold N`, matching the "at least N%" the
+      # usage text promises.
+      def compute_row(fname, current_payload, baseline_payload, threshold)
+        deltas = compute_deltas(current_payload, baseline_payload)
+        floor = threshold.abs
+        return nil unless deltas.values.any? { |delta| delta.abs > EPSILON && delta.abs >= floor }
+
+        {file: fname, status: status_for(current_payload, baseline_payload),
+         line_delta: deltas[:line], branch_delta: deltas[:branch], method_delta: deltas[:method]}
+      end
+
+      def compute_deltas(current_payload, baseline_payload)
+        CoverageFile::CRITERIA.transform_values do |fields|
+          pct_for(fields, current_payload) - pct_for(fields, baseline_payload)
+        end
+      end
+
+      def status_for(current_payload, baseline_payload)
+        return "added"   if baseline_payload.nil?
+        return "removed" if current_payload.nil?
+
+        "changed"
+      end
+
+      def pct_for(fields, payload)
+        return 0.0 unless payload.is_a?(Hash) && payload[fields[:total]].to_i.positive?
+
+        payload[fields[:percent]].to_f
+      end
+
+      def emit_text(stdout, rows, color)
+        return stdout.puts("simplecov diff: no per-file coverage changes") if rows.empty?
+
+        rows.each { |row| stdout.puts(format_row(row, color)) }
+      end
+
+      def format_row(row, color)
+        line = "  #{delta_parts(row, color).join('  ')}  #{row[:file]}"
+        suffix = STATUS_SUFFIX[row[:status]]
+        suffix ? "#{line}  #{suffix}" : line
+      end
+
+      def delta_parts(row, color)
+        [
+          format_delta(row[:line_delta], "lines", color),
+          (format_delta(row[:branch_delta], "branches", color) if row[:branch_delta].abs > EPSILON),
+          (format_delta(row[:method_delta], "methods", color)  if row[:method_delta].abs > EPSILON)
+        ].compact
+      end
+
+      # A removed file's deltas are all -baseline%, but deleting a
+      # covered file (dead code cleanup) is not a coverage regression,
+      # so removed rows never trip the --fail-on-drop gate. Drops are
+      # gated on EPSILON like row inclusion and display: a row listed
+      # for a gain in one criterion must not fail the run over float
+      # noise in another, invisible in the printed output.
+      def coverage_drop?(rows)
+        rows.reject { |row| row[:status] == "removed" }
+            .any? { |row| row.values_at(:line_delta, :branch_delta, :method_delta).min < -EPSILON }
+      end
+
+      # Deltas are sign-based, not threshold-based: a +5% bump is good
+      # (green) and a -5% drop is bad (red), regardless of where the
+      # absolute coverage level lands.
+      def format_delta(delta, label, color)
+        sign = delta.positive? ? "+" : ""
+        text = format("%<sign>s%<delta>6.2f%% %<label>s", sign: sign, delta: delta, label: label)
+        SimpleCov::Color.colorize(text, delta.negative? ? :red : :green, enabled: color)
+      end
+    end
+  end
+end

data/lib/simplecov/cli/dotfile.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module SimpleCov
+  module CLI
+    # Loads a project's `.simplecov` config file purely to read
+    # `coverage_dir` from it, with `SimpleCov.start` and the at_exit
+    # hook installer neutered so the load doesn't trigger coverage
+    # tracking. Used by the CLI to default `--input` / `--report`
+    # paths to whatever the project's dotfile declares, without making
+    # every read-only subcommand pay for actually starting Coverage.
+    module Dotfile
+    module_function
+
+      def coverage_dir
+        dotfile = find
+        return "coverage" unless dotfile
+
+        with_simplecov_loaded { read_from(dotfile) }
+      rescue ScriptError, StandardError => e
+        # simplecov:disable — defensive fallback for a bad dotfile; never
+        # fires in the project's own dogfood run. ScriptError covers the
+        # SyntaxError a malformed dotfile raises from `load` (it is not a
+        # StandardError) along with LoadError; StandardError covers the
+        # rest (EACCES, errors raised by the dotfile's own code, etc.).
+        warn "simplecov: failed to read coverage_dir from #{dotfile}: #{e.class}: #{e.message}"
+        "coverage"
+        # simplecov:enable
+      end
+
+      # Load the dotfile, snapshot+restore `SimpleCov.coverage_dir` so we
+      # don't quietly clobber it in a host process that's already
+      # configured (e.g. when the CLI is exercised inline by simplecov's
+      # own spec suite). The snapshot is intentionally narrow: a dotfile
+      # can still mutate other SimpleCov configuration (filters, groups,
+      # formatters, command_name, ...) via `SimpleCov.configure` or
+      # `SimpleCov.start { ... }` blocks. The CLI normally runs as a
+      # top-level process where that's harmless; callers driving it from
+      # inside a Ruby host that cares about isolation should arrange that
+      # themselves.
+      def read_from(dotfile)
+        snapshot = SimpleCov.instance_variable_get(:@coverage_dir) #: String?
+        load_with_start_neutered(dotfile)
+        SimpleCov.coverage_dir
+      ensure
+        # Restore even when the load raises, so a bad dotfile doesn't
+        # leave a host process's configured dir clobbered.
+        # @type var snapshot: String?
+        SimpleCov.instance_variable_set(:@coverage_dir, snapshot)
+      end
+
+      def find
+        dir = Pathname.new(Dir.pwd)
+        loop do
+          candidate = dir.join(".simplecov")
+          return candidate.to_s if candidate.exist?
+          break if dir.root?
+
+          dir = dir.parent
+        end
+        nil
+      end
+
+      def with_simplecov_loaded
+        previous_no_defaults = ENV.fetch("SIMPLECOV_NO_DEFAULTS", nil) #: String?
+        previous_cli         = ENV.fetch("SIMPLECOV_CLI", nil) #: String?
+        ENV["SIMPLECOV_NO_DEFAULTS"] = "1"
+        # SIMPLECOV_CLI lets a project's `.simplecov` opt some config into
+        # CLI-only behavior — e.g. simplecov itself sets `coverage_dir`
+        # to the dogfood path here but skips that for descendants.
+        ENV["SIMPLECOV_CLI"] = "1"
+        require "simplecov"
+        yield
+      ensure
+        # @type var previous_no_defaults: String?
+        # @type var previous_cli: String?
+        ENV["SIMPLECOV_NO_DEFAULTS"] = previous_no_defaults
+        ENV["SIMPLECOV_CLI"]         = previous_cli
+      end
+
+      # Load `path` with `SimpleCov.start` and the at_exit installer
+      # turned into no-ops, so a project whose dotfile calls
+      # `SimpleCov.start` doesn't trigger Coverage just because we asked
+      # for `coverage_dir`. Config inside any `SimpleCov.start { ... }`
+      # block still runs.
+      def load_with_start_neutered(path)
+        klass = SimpleCov.singleton_class
+        names = %i[start_tracking install_at_exit_hook]
+        stash = names.to_h { |name| [name, klass.instance_method(name)] } #: Hash[Symbol, UnboundMethod]
+        # define_method over an existing method emits a "method redefined"
+        # warning under $VERBOSE; the override and restore are intentional.
+        silence_verbose { names.each { |name| klass.define_method(name) { nil } } }
+        load path
+      ensure
+        # @type var stash: Hash[Symbol, UnboundMethod]
+        # @type var klass: Class
+        silence_verbose { stash.each { |name, method| klass.define_method(name, method) } }
+      end
+
+      def silence_verbose
+        previous = $VERBOSE #: bool?
+        $VERBOSE = nil
+        yield
+      ensure
+        # @type var previous: bool?
+        $VERBOSE = previous
+      end
+    end
+  end
+end