simplecov 0.22.0 → 1.0.2

data/lib/simplecov/parallel_adapters/parallel_tests.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SimpleCov
+  module ParallelAdapters
+    # Adapter for [grosser/parallel_tests](https://github.com/grosser/parallel_tests).
+    # This is the historical default — SimpleCov has special-cased
+    # parallel_tests since 0.18 — and remains the most precise option for
+    # projects on it. Detection requires the full native coordination
+    # contract: the `ParallelTests` constant has been loaded,
+    # `TEST_ENV_NUMBER` is set, and `PARALLEL_PID_FILE` is set. The pid-file
+    # path is required because the native wait API reads it with `ENV.fetch`.
+    # When a runner only provides the env-var convention, GenericAdapter is
+    # the correct coordination path.
+    class ParallelTestsAdapter < Base
+      class << self
+        def active?
+          return false if SimpleCov.parallel_tests == false
+
+          ensure_loaded
+          # !! to coerce `defined?` (returns nil or "constant") to a proper bool.
+          !!(defined?(::ParallelTests) && native_parallel_tests_environment?)
+        end
+
+        # Pick the *first* started process to do the final-result work,
+        # not the last. The parallel_tests README recommends
+        # `first_process?` for "do something once after every worker
+        # finishes" hooks, so user code that has its own
+        # `wait_for_other_processes_to_finish` in an `RSpec.after(:suite)`
+        # overwhelmingly waits in the first process — picking the same
+        # side avoids the cross-process deadlock #922 reported. Also
+        # handles `PARALLEL_TEST_GROUPS=1` naturally (the only worker's
+        # `TEST_ENV_NUMBER` is "" and `first_process?` tests for that
+        # empty string).
+        def first_worker?
+          ::ParallelTests.first_process?
+        end
+
+        def wait_for_siblings
+          return unless native_parallel_tests_environment?
+
+          ::ParallelTests.wait_for_other_processes_to_finish
+        end
+
+        # The native wait blocks until every sibling process exits, but only
+        # when the pid-file contract is present (see `wait_for_siblings`).
+        def native_wait?
+          native_parallel_tests_environment?
+        end
+
+        def expected_worker_count
+          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+        end
+
+        # Auto-require `parallel_tests` when it's installed AND the env
+        # vars it sets are present, so callers can rely on
+        # `defined?(::ParallelTests)` downstream. parallel_tests is an
+        # optional dependency (see https://github.com/grosser/parallel_tests/issues/772),
+        # and `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` are commonly set
+        # for other reasons (custom subprocess coordination, CI sharding,
+        # the parallel_rspec gem which intentionally mirrors the env-var
+        # convention), so a missing gem is treated as "user isn't using
+        # parallel_tests" — silently skip and let GenericAdapter handle
+        # it. Users who want to override the auto-detect can set
+        # `SimpleCov.parallel_tests true` (force on) or `false` (force
+        # off). See #1018.
+        def ensure_loaded
+          return if defined?(::ParallelTests) # simplecov:disable — only true after a previous load
+          return if SimpleCov.parallel_tests == false # simplecov:disable — only fires when user opts out
+          # simplecov:disable — env-var-only path
+          return unless SimpleCov.parallel_tests || env_suggests_parallel_tests?
+
+          # simplecov:disable — only fires under a real parallel_tests setup
+          require "parallel_tests"
+        rescue LoadError
+          # Gem isn't installed; stay quiet — warning here regressed
+          # users who use those env vars for their own subprocess
+          # coordination.
+          # simplecov:enable
+        end
+
+        def env_suggests_parallel_tests?
+          ENV.key?("TEST_ENV_NUMBER") && ENV.key?("PARALLEL_TEST_GROUPS")
+        end
+
+        def native_parallel_tests_environment?
+          ENV.key?("TEST_ENV_NUMBER") && ENV.key?("PARALLEL_PID_FILE")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/parallel_adapters.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "parallel_adapters/base"
+require_relative "parallel_adapters/parallel_tests"
+require_relative "parallel_adapters/generic"
+
+module SimpleCov
+  # Registry + selection for parallel-test-runner adapters. An adapter
+  # answers a small fixed set of questions on SimpleCov's behalf:
+  #
+  #   - `active?` — are WE the runner in charge for this process?
+  #   - `first_worker?` — should this process do the final-result work?
+  #   - `wait_for_siblings` — block until siblings finish (optional)
+  #   - `expected_worker_count` — how many workers total
+  #
+  # `SimpleCov::ParallelAdapters::Base` provides safe no-op defaults; two
+  # adapters ship out of the box:
+  #
+  #   - `ParallelTestsAdapter` — wraps the grosser/parallel_tests gem
+  #     (precise sync + first-process detection via the gem's own API).
+  #   - `GenericAdapter` — env-var-only detection for runners that follow
+  #     the parallel_tests `TEST_ENV_NUMBER` convention but don't ship a
+  #     Ruby API (parallel_rspec, custom CI sharding, knapsack-style
+  #     splitters). See https://github.com/simplecov-ruby/simplecov/issues/1065.
+  #
+  # Users can plug in additional adapters:
+  #
+  #   SimpleCov::ParallelAdapters.register MyRunnerAdapter
+  #
+  # An adapter just needs to be a class responding to the four methods
+  # above. Subclass `SimpleCov::ParallelAdapters::Base` to inherit the
+  # no-op defaults and override only what you need (the contract methods
+  # are defined as class methods, so plain inheritance is what carries
+  # them through; `extend Base` won't pick them up).
+  module ParallelAdapters
+  module_function
+
+    # Adapters in selection order. ParallelTestsAdapter first (most
+    # specific — uses the gem's own API when the gem is loaded); then
+    # GenericAdapter as the env-var fallback. User-registered adapters
+    # are prepended (#register puts new entries at the front) so
+    # downstream code can override the built-ins by registering a more
+    # specific match.
+    def adapters
+      @adapters ||= [ParallelTestsAdapter, GenericAdapter]
+    end
+
+    # Register a custom adapter. Newly registered adapters are inserted
+    # at the front of the selection list so a custom adapter for a
+    # specific runner takes precedence over the built-in ParallelTests
+    # and Generic adapters.
+    #
+    #   class MyRunnerAdapter < SimpleCov::ParallelAdapters::Base
+    #     def self.active?       = ENV["MY_RUNNER_PID"]
+    #     def self.first_worker? = ENV["MY_RUNNER_PID"].to_i == 1
+    #     def self.expected_worker_count = ENV["MY_RUNNER_WORKERS"].to_i
+    #   end
+    #
+    #   SimpleCov::ParallelAdapters.register MyRunnerAdapter
+    def register(adapter)
+      reset_current!
+      adapters.unshift(adapter) unless adapters.include?(adapter)
+      adapter
+    end
+
+    # The adapter SimpleCov should consult for this process — the first
+    # registered adapter whose `active?` returns true. Returns nil when
+    # no adapter is active (i.e., we're not running under any recognized
+    # parallel test runner), in which case the caller should treat the
+    # process as single-worker.
+    def current
+      return @current if defined?(@current)
+
+      @current = adapters.find(&:active?)
+    end
+
+    # Clear the memoized `current` selection. Primarily for tests that
+    # mutate env vars between examples; production runs are single-shot.
+    def reset_current!
+      remove_instance_variable(:@current) if defined?(@current)
+    end
+  end
+end

data/lib/simplecov/parallel_coordination.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# simplecov:disable
+# Methods below only fire under a parallel test runner; not reachable
+# from a single-process rspec run. Cucumber's test_projects exercise
+# the parallel_tests integration end-to-end in subprocesses, but
+# those subprocesses don't merge their Coverage data back into the
+# parent this dogfood report measures.
+module SimpleCov
+  class << self
+    # @api private
+    def final_result_process?
+      adapter = SimpleCov::ParallelAdapters.current
+      # No recognized parallel-test adapter. A subprocess forked while
+      # coverage was running is never the final reporter — the process that
+      # spawned it merges every slice and produces the report. Without this,
+      # fork-based runners that don't set TEST_ENV_NUMBER (e.g. Minitest's
+      # `parallelize`) have every worker produce the final report and its
+      # warnings. See issue #1171.
+      return !forked_subprocess? unless adapter
+
+      adapter.first_worker?
+    end
+
+    # @api private
+    def wait_for_other_processes
+      adapter = SimpleCov::ParallelAdapters.current
+      return unless adapter && final_result_process?
+
+      # Native synchronization first (adapters that wrap a runner with a
+      # real "wait" primitive — parallel_tests'
+      # `wait_for_other_processes_to_finish` — implement this; adapters
+      # without a native API no-op and rely on the polling fallback below).
+      adapter.wait_for_siblings
+
+      # The native wait can return before sibling at_exit handlers finish
+      # writing resultsets, and adapters without a native wait have
+      # nothing else. Either way, poll the resultset cache until all
+      # expected workers have reported or a timeout is reached. Capture
+      # the outcome so `ready_to_process_results?` can suppress min/max
+      # threshold checks against a partial total.
+      @parallel_results_complete =
+        wait_for_parallel_results(adapter.expected_worker_count, native_wait: adapter.native_wait?)
+    end
+
+    # @api private — true when every sibling reported its resultset
+    # before the wait deadline. Defaults to true outside a parallel
+    # run (when `wait_for_other_processes` is a no-op).
+    def parallel_results_complete?
+      defined?(@parallel_results_complete) ? @parallel_results_complete : true
+    end
+
+    # @api private — seconds the resultset count must hold steady, after a
+    # native wait, before we accept fewer than `expected` workers as final.
+    PARALLEL_RESULTS_SETTLE = 0.5
+    private_constant :PARALLEL_RESULTS_SETTLE
+
+    # @api private — returns true when the reporting worker has every
+    # resultset it's going to get, false on timeout. Single-process runs
+    # (expected <= 1) short-circuit to true with no waiting.
+    #
+    # Normally we poll until `expected` (= PARALLEL_TEST_GROUPS) workers have
+    # reported or `SimpleCov.parallel_wait_timeout` elapses; raise that setting
+    # when a slow worker routinely finishes well after the others.
+    #
+    # When a native wait already confirmed every sibling PROCESS exited
+    # (`native_wait`), no further resultset will appear, so a count below
+    # `expected` just means some workers produced none — e.g. parallel_test
+    # groups that got no spec file on a machine with more cores than files.
+    # Once the count then holds steady for `PARALLEL_RESULTS_SETTLE` we accept
+    # it as final rather than blocking for the whole timeout. Without a native
+    # wait (GenericAdapter) we can't tell an idle worker from a slow one, so we
+    # keep waiting the full timeout.
+    def wait_for_parallel_results(expected, native_wait: false)
+      return true unless expected > 1 # simplecov:disable branch — only false in real parallel runs
+
+      deadline = monotonic_time + parallel_wait_timeout
+      tracker = {count: 0, since: monotonic_time}
+      loop do
+        seen = SimpleCov::ResultMerger.read_resultset.size
+        return true if seen >= expected
+        return true if native_wait && resultset_count_settled?(tracker, seen)
+        return false if parallel_wait_timed_out?(deadline, expected, seen)
+
+        sleep 0.1
+      end
+    end
+
+    # Track whether the resultset count has held steady (and positive) for
+    # `PARALLEL_RESULTS_SETTLE` seconds. `tracker` carries the last count and
+    # the time it last changed across poll iterations.
+    def resultset_count_settled?(tracker, count)
+      if count > tracker[:count]
+        tracker[:count] = count
+        tracker[:since] = monotonic_time
+        return false
+      end
+
+      count.positive? && (monotonic_time - tracker[:since]) >= PARALLEL_RESULTS_SETTLE
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # @api private — true once the wait deadline has passed; warns on
+    # the first timeout so the user knows the merged total is partial.
+    def parallel_wait_timed_out?(deadline, expected, seen)
+      return false unless monotonic_time > deadline
+
+      warn_about_incomplete_parallel_results(expected, seen)
+      true
+    end
+
+    # @api private
+    def warn_about_incomplete_parallel_results(expected, seen)
+      return unless print_errors
+
+      warn SimpleCov::Color.colorize(
+        "Only #{seen} of #{expected} parallel-test workers reported within " \
+        "#{parallel_wait_timeout}s, so coverage totals are partial and minimum / " \
+        "maximum coverage checks are skipped for this run. Increase " \
+        "SimpleCov.parallel_wait_timeout if a worker routinely needs longer.",
+        :yellow
+      )
+    end
+  end
+end
+# simplecov:enable

data/lib/simplecov/process.rb

@@ -1,19 +1,59 @@
 # frozen_string_literal: true
 
-module Process
+# Hooks `Process._fork` (Ruby 3.1+) so child processes inherit SimpleCov's
+# coverage tracking when `SimpleCov.enable_for_subprocesses?` is set.
+#
+# `Process._fork` is the official extension point: `Kernel#fork`,
+# `Process.fork`, `IO.popen("-")`, and similar all funnel through it.
+# Hooking `_fork` (instead of redefining `Process.fork`) composes
+# correctly with other libraries doing the same — they each prepend
+# their own module and chain via `super`.
+
+# Reopened here for the fork-related at_exit plumbing that only matters
+# when subprocess support is loaded.
+module SimpleCov
   class << self
-    def fork_with_simplecov(&block)
-      if defined?(SimpleCov) && SimpleCov.running
-        fork_without_simplecov do
-          SimpleCov.at_fork.call(Process.pid)
-          block.call if block_given?
-        end
-      else
-        fork_without_simplecov(&block)
-      end
+    # Forked children inherit at_exit state that is wrong for them:
+    # @at_exit_hook_installed may describe a hook the parent already
+    # consumed before forking (Minitest autorun runs the suite inside the
+    # parent's at_exit, after SimpleCov's own hook has fired), and
+    # external_at_exit may point at a Minitest.after_run deferral that is
+    # pid-pinned to the parent. Reset both so the at_fork proc's
+    # SimpleCov.start installs a fresh hook that actually fires at child
+    # exit. See issue #1227.
+    def reset_inherited_at_exit_state!
+      @at_exit_hook_installed = false
+      self.external_at_exit = false
     end
+  end
 
-    alias fork_without_simplecov fork
-    alias fork fork_with_simplecov
+  # Prepended onto Process's singleton class so every fork — direct or
+  # via Kernel#fork / IO.popen — re-runs SimpleCov's at_fork callback in
+  # the child.
+  module ProcessForkHook
+    def _fork
+      active = defined?(SimpleCov) && Coverage.running?
+      # Assign the next serial in the PARENT, before the fork, so the child
+      # inherits its own stable ordinal via copy-on-write. The default
+      # at_fork uses it (instead of the child pid) to name the subprocess's
+      # result, keeping that name identical across runs. See issue #1171.
+      SimpleCov.next_subprocess_serial! if active
+      pid = super
+      if pid.zero? && active
+        # Mark the child here, independent of whatever custom at_fork block
+        # the user installed, so `final_result_process?` can keep forked
+        # workers from each producing the final report. See issue #1171.
+        SimpleCov.mark_forked_subprocess!
+        # Without this, a child forked under Minitest autorun measures
+        # coverage and then silently discards it: every inherited exit
+        # route is dead in the child (see the method's comment). A custom
+        # at_fork runs afterwards and can still override. See issue #1227.
+        SimpleCov.reset_inherited_at_exit_state!
+        SimpleCov.at_fork.call(::Process.pid)
+      end
+      pid
+    end
   end
 end
+
+Process.singleton_class.prepend(SimpleCov::ProcessForkHook)

data/lib/simplecov/profiles/bundler_filter.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 SimpleCov.profiles.define "bundler_filter" do
-  add_filter "/vendor/bundle/"
+  skip "/vendor/bundle/"
 end

data/lib/simplecov/profiles/hidden_filter.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 SimpleCov.profiles.define "hidden_filter" do
-  add_filter %r{^/\..*}
+  skip(/\A\..*/)
 end

data/lib/simplecov/profiles/rails.rb

@@ -3,16 +3,30 @@
 SimpleCov.profiles.define "rails" do
   load_profile "test_frameworks"
 
-  add_filter %r{^/config/}
-  add_filter %r{^/db/}
+  skip %r{\Aconfig/}
+  skip %r{\Adb/}
 
-  add_group "Controllers", "app/controllers"
-  add_group "Channels", "app/channels"
-  add_group "Models", "app/models"
-  add_group "Mailers", "app/mailers"
-  add_group "Helpers", "app/helpers"
-  add_group "Jobs", %w[app/jobs app/workers]
-  add_group "Libraries", "lib/"
+  group "Controllers", "app/controllers"
+  group "Channels", "app/channels"
+  group "Models", "app/models"
+  group "Mailers", "app/mailers"
+  group "Helpers", "app/helpers"
+  group "Jobs", %w[app/jobs app/workers]
+  group "Libraries", "lib/"
 
-  track_files "{app,lib}/**/*.rb"
+  # Preserve the legacy `track_files` semantics (additive disk-discovery
+  # without restricting the report's universe): write the ivar directly
+  # so loading the profile doesn't emit the public-API deprecation. Users
+  # migrating their own configs should prefer `cover "{app,lib}/**/*.rb"`,
+  # which both injects unloaded files and scopes the report to the match
+  # set — usually the intended behavior for a Rails project.
+  @tracked_files = "{app,lib}/**/*.rb"
+
+  # `parallelize(workers: ...)` forks worker processes that each run a
+  # slice of the suite. Without subprocess support, the workers' coverage
+  # is dropped on the floor and the parent records 0% for everything they
+  # touched. Hooking `Process._fork` makes each worker re-call
+  # `SimpleCov.start` with a unique command_name so the resultsets merge
+  # correctly.
+  merge_subprocesses true
 end

data/lib/simplecov/profiles/root_filter.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 SimpleCov.profiles.define "root_filter" do
-  # Exclude all files outside of simplecov root
-  root_filter = nil
-  add_filter do |src|
-    root_filter ||= /\A#{Regexp.escape(SimpleCov.root + File::SEPARATOR)}/io
-    src.filename !~ root_filter
+  # Exclude all files outside of simplecov root. Shares the regex with
+  # SimpleCov::UselessResultsRemover so the root-prefix logic lives in one
+  # place; this profile is the user-facing entry point that tools like
+  # `SimpleCov.filtered` apply.
+  skip do |src|
+    src.filename !~ SimpleCov::UselessResultsRemover.root_regex
   end
 end

data/lib/simplecov/profiles/strict.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# A "no shortfalls allowed" profile: every coverage criterion is
+# enabled and held to 100%. Per
+# https://github.com/simplecov-ruby/simplecov/issues/1061, this lives as
+# an opt-in profile rather than the default — most projects can't
+# realistically start at 100% on day one — so a team that has paid down
+# the debt can flip the strict switch without re-typing the threshold
+# trio every time.
+#
+# JRuby gracefully degrades: `enable_coverage :branch` / `:method` are
+# accepted (they just add to the configured criteria set), but the
+# runtime can't actually measure them, so the corresponding stats never
+# materialize. `CoverageViolations` skips threshold lookups for
+# criteria not in the stats, so the `:branch` / `:method` clauses below
+# silently no-op on JRuby and only `:line` is enforced.
+#
+# `:eval` widens the universe of code held to 100% to include strings
+# passed through `Kernel#eval` (typically ERB templates, when the user
+# sets `ERB#filename=`). Guarded on `coverage_for_eval_supported?` so
+# the profile stays quiet on Ruby < 3.2, where `enable_coverage :eval`
+# would otherwise warn about the missing runtime support every time
+# the profile loads.
+SimpleCov.profiles.define "strict" do
+  enable_coverage :branch
+  enable_coverage :method
+  # simplecov:disable branch — dogfood runs on Ruby >= 3.2 only, so
+  # the else arm (eval coverage not supported) is unreachable from CI.
+  enable_coverage :eval if coverage_for_eval_supported?
+  # simplecov:enable
+  minimum_coverage line: 100, branch: 100, method: 100
+end

data/lib/simplecov/profiles/test_frameworks.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
 SimpleCov.profiles.define "test_frameworks" do
-  add_filter "/test/"
-  add_filter "/features/"
-  add_filter "/spec/"
-  add_filter "/autotest/"
+  skip %r{\A(test|features|spec|autotest)/}
 end

data/lib/simplecov/profiles.rb

@@ -17,7 +17,7 @@ module SimpleCov
     #
     def define(name, &blk)
       name = name.to_sym
-      raise "SimpleCov Profile '#{name}' is already defined" unless self[name].nil?
+      raise SimpleCov::ConfigurationError, "SimpleCov Profile '#{name}' is already defined" unless self[name].nil?
 
       self[name] = blk
     end
@@ -26,10 +26,39 @@ module SimpleCov
     # Applies the profile of given name on SimpleCov.configure
     #
     def load(name)
+      SimpleCov.configure(&fetch_proc(name))
+    end
+
+    #
+    # Returns the proc registered for the given profile name, autoloading
+    # bundled or plugin-gem profiles on first lookup. Raises if the profile
+    # cannot be located.
+    #
+    # Lookup order:
+    #   1. already registered via #define
+    #   2. require "simplecov/profiles/<name>"   (bundled profiles)
+    #   3. require "simplecov-profile-<name>"    (third-party plugin gems)
+    #
+    def fetch_proc(name)
       name = name.to_sym
-      raise "Could not find SimpleCov Profile called '#{name}'" unless key?(name)
+      autoload_profile(name) unless key?(name)
+      return self[name] if key?(name)
+
+      raise SimpleCov::ConfigurationError, "Could not find SimpleCov Profile called '#{name}'"
+    end
+
+  private
 
-      SimpleCov.configure(&self[name])
+    def autoload_profile(name)
+      require "simplecov/profiles/#{name}"
+    rescue LoadError
+      begin
+        # simplecov:disable — third-party gem fallback (no such gem in test env)
+        require "simplecov-profile-#{name}"
+        # simplecov:enable
+      rescue LoadError
+        # fall through; #fetch_proc raises the user-facing error
+      end
     end
   end
 end

data/lib/simplecov/result/missing_source_files_reporter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class Result
+    # When a resultset references source files that don't exist on the local
+    # filesystem they're silently dropped — which produces an empty `0 / 0
+    # (100.00%)` report that looks like success but isn't. Emit a single
+    # warning summarizing the drop and, when every entry was lost, point at
+    # the typical cause (`SimpleCov.collate` invoked from a machine or path
+    # different from where the resultsets were generated). See #980.
+    class MissingSourceFilesReporter
+      def initialize(missing_paths, input_size:, every_entry_dropped:)
+        @missing_paths = missing_paths
+        @input_size = input_size
+        @every_entry_dropped = every_entry_dropped
+      end
+
+      def warn!
+        warn SimpleCov::Color.colorize(message, :yellow)
+      end
+
+      def message
+        @every_entry_dropped ? all_missing_warning : partial_missing_warning
+      end
+
+    private
+
+      def all_missing_warning
+        "SimpleCov dropped all #{@missing_paths.size} source file(s) from the result — " \
+          "none of the paths in the resultset exist on this filesystem: " \
+          "#{summary}. If you're running `SimpleCov.collate`, the source " \
+          "files must be available at the same absolute paths as when the individual resultsets " \
+          "were generated."
+      end
+
+      def partial_missing_warning
+        "SimpleCov dropped #{@missing_paths.size} source file(s) from the result because " \
+          "they don't exist on this filesystem: #{summary}. They were " \
+          "tracked in the resultset but have since moved or been removed."
+      end
+
+      def summary
+        sample = @missing_paths.first(5).join(", ")
+        remaining = @missing_paths.size - 5
+        remaining.positive? ? "#{sample} (+#{remaining} more)" : sample
+      end
+    end
+  end
+end

data/lib/simplecov/result/source_file_builder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class Result
+    # Constructs `SimpleCov::SourceFile` instances from a raw coverage
+    # hash, sorts them by filename, and surfaces filenames whose source
+    # is no longer present on disk so the caller can warn about the
+    # silent drop (see #980).
+    class SourceFileBuilder
+      attr_reader :missing_source_files
+
+      def initialize(original_result, not_loaded_files:)
+        @original_result = original_result
+        @not_loaded_files = not_loaded_files
+        @missing_source_files = []
+      end
+
+      def call
+        SimpleCov::FileList.new(
+          @original_result
+            .filter_map { |filename, coverage| build_source_file(filename, coverage) }
+            .sort_by(&:filename)
+        )
+      end
+
+    private
+
+      def build_source_file(filename, coverage)
+        unless File.file?(filename)
+          @missing_source_files << filename
+          return
+        end
+
+        SimpleCov::SourceFile.new(
+          filename,
+          stringify_outer_keys(coverage),
+          loaded: !@not_loaded_files.include?(filename)
+        )
+      end
+
+      # `Coverage.result` returns symbol keys (`:lines`, `:branches`,
+      # `:methods`); resultsets loaded from disk are already string-keyed.
+      # SourceFile reads with strings, and handles both Array and
+      # stringified-Array branch/method keys via `restore_ruby_data_structure`,
+      # so only the outer hash needs normalizing.
+      def stringify_outer_keys(coverage)
+        coverage.transform_keys(&:to_s)
+      end
+    end
+  end
+end