simplecov 0.22.0 → 1.3.0

data/lib/simplecov/result_merger.rb

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
 
-require "json"
+require_relative "result_merger/legacy_format_adapter"
+require_relative "result_merger/resultset_file"
+require_relative "result_merger/resultset_run_identity"
+require_relative "result_merger/resultset_store"
+require_relative "result_merger/contexts"
+require_relative "result_merger/unloaded_files"
 
 module SimpleCov
   #
-  # Singleton that is responsible for caching, loading and merging
-  # SimpleCov::Results into a single result for coverage analysis based
-  # upon multiple test suites.
+  # Caching, loading and merging `SimpleCov::Result`s into a single result for
+  # coverage analysis based upon multiple test suites.
   #
   module ResultMerger
+    extend ResultsetRunIdentity
+
     class << self
-      # The path to the .resultset.json cache file
       def resultset_path
-        File.join(SimpleCov.coverage_path, ".resultset.json")
-      end
-
-      def resultset_writelock
-        File.join(SimpleCov.coverage_path, ".resultset.json.lock")
+        ResultsetStore.resultset_path
       end
 
       def merge_and_store(*file_paths, ignore_timeout: false)
@@ -26,168 +27,163 @@ module SimpleCov
       end
 
       def merge_results(*file_paths, ignore_timeout: false)
-        # It is intentional here that files are only read in and parsed one at a time.
-        #
-        # In big CI setups you might deal with 100s of CI jobs and each one producing Megabytes
-        # of data. Reading them all in easily produces Gigabytes of memory consumption which
-        # we want to avoid.
-        #
-        # For similar reasons a SimpleCov::Result is only created in the end as that'd create
-        # even more data especially when it also reads in all source files.
-        initial_memo = valid_results(file_paths.shift, ignore_timeout: ignore_timeout)
-
-        command_names, coverage = file_paths.reduce(initial_memo) do |memo, file_path|
-          merge_coverage(memo, valid_results(file_path, ignore_timeout: ignore_timeout))
-        end
-
-        create_result(command_names, coverage)
-      end
-
-      def valid_results(file_path, ignore_timeout: false)
-        results = parse_file(file_path)
-        merge_valid_results(results, ignore_timeout: ignore_timeout)
+        # Tracked paths and test maps are collected as each resultset is parsed,
+        # so files are still read and discarded one at a time (#1250).
+        tracked_files = Set.new
+        context_maps = ContextMap::Union.new
+        command_names, coverage = absorb_results(file_paths, ignore_timeout: ignore_timeout,
+          &entry_collector(tracked_files, context_maps))
+        create_result(command_names, coverage, tracked_files: tracked_files, contexts: context_maps.map)
       end
 
-      def parse_file(path)
-        data = read_file(path)
-        parse_json(data)
+      # One block over the entries each resultset contributes to the merge,
+      # feeding every merge-side accumulator in a single pass: the tracked
+      # paths and the per-test map union (#1250).
+      def entry_collector(tracked_files, context_maps)
+        collectors = [UnloadedFiles.collector(tracked_files), context_maps.collector]
+        ->(surviving) { collectors.each { |collector| collector.call(surviving) } }
       end
 
-      def read_file(path)
-        return unless File.exist?(path)
-
-        data = File.read(path)
-        return if data.nil? || data.length < 2
-
-        data
+      #
+      # Reads every resultset and folds it into one merged coverage, stopping
+      # short of building a `SimpleCov::Result`.
+      #
+      # Files are only read in and parsed one at a time on purpose. In big CI
+      # setups you might deal with 100s of jobs each producing megabytes of
+      # data, and reading them all in easily produces gigabytes of memory
+      # consumption. For the same reason a `Result` is only created at the end.
+      #
+      # One accumulator absorbs the whole run, rather than folding each file
+      # into the merged-so-far pairwise: the pairwise form rebuilt every file's
+      # coverage once per resultset, which is what made merging a large
+      # parallel run's results the dominant cost of `collate`.
+      #
+      # `file_paths` is only ever iterated, so a caller that wants to observe
+      # the merge as it goes can hand in any Enumerable. `benchmarks/collate`
+      # passes an Enumerator that reports progress.
+      #
+      def absorb_results(file_paths, ignore_timeout: false, &on_parse)
+        Combine::CoverageAccumulator.fold(
+          file_paths.lazy.map { |file_path| valid_results(file_path, ignore_timeout: ignore_timeout, &on_parse) }
+        )
       end
 
-      def parse_json(content)
-        return {} unless content
-
-        JSON.parse(content) || {}
-      rescue StandardError
-        warn "[SimpleCov]: Warning! Parsing JSON content of resultset file failed"
-        {}
+      # Yields the surviving entries before they are reduced.
+      def valid_results(file_path, ignore_timeout: false, &on_parse)
+        merge_valid_results(ResultsetFile.parse(file_path), ignore_timeout: ignore_timeout, &on_parse)
       end
 
+      # Yields the entries that survived the merge timeout, so a caller that
+      # wants to observe what a resultset carried sees only what is being
+      # merged. An expired entry contributes nothing, tracked paths included.
       def merge_valid_results(results, ignore_timeout: false)
-        results = results.select { |_command_name, data| within_merge_timeout?(data) } unless ignore_timeout
+        results = drop_expired_results(results) unless ignore_timeout
+        yield results if block_given?
 
         command_plus_coverage = results.map do |command_name, data|
-          [[command_name], adapt_result(data.fetch("coverage"))]
+          [[command_name], LegacyFormatAdapter.call(data.fetch("coverage"))]
         end
 
-        # one file itself _might_ include multiple test runs
         merge_coverage(*command_plus_coverage)
       end
 
+      def drop_expired_results(results)
+        fresh, expired = results.partition { |_command_name, data| within_merge_timeout?(data) }
+        return results if expired.empty?
+
+        warn_about_expired_results(expired.map(&:first))
+        fresh.to_h
+      end
+
       def within_merge_timeout?(data)
-        time_since_result_creation(data) < SimpleCov.merge_timeout
+        (Time.now - Time.at(data.fetch("timestamp"))) < SimpleCov.merge_timeout
       end
 
-      def time_since_result_creation(data)
-        Time.now - Time.at(data.fetch("timestamp"))
+      def warn_about_expired_results(expired_command_names)
+        # Ordinary parallel workers only store their own slice; the selected
+        # final process performs this merge.
+        return unless SimpleCov.print_errors
+
+        warn "[SimpleCov]: Excluded #{expired_command_names.size} result(s) older than " \
+             "merge_timeout (#{SimpleCov.merge_timeout}s) from the merged report: " \
+             "#{expired_command_names.sort.join(", ")}. " \
+             "Increase SimpleCov.merge_timeout to include them."
       end
 
-      def create_result(command_names, coverage)
+      # `tracked_files:` has no default: only the caller knows what the
+      # contributing processes were told to track, and quietly reading an
+      # omission as "nothing was tracked" would drop every never-loaded
+      # file from the merged report.
+      def create_result(command_names, coverage, tracked_files:, contexts: nil)
         return nil unless coverage
 
-        command_name = command_names.reject(&:empty?).sort.join(", ")
-        SimpleCov::Result.new(coverage, command_name: command_name)
+        # Deduped: a CI matrix collates one resultset per worker, and joining
+        # every run's name verbatim rendered "RSpec" a hundred times over in the
+        # report footer (#1284).
+        distinct_names = command_names.reject(&:empty?).uniq.sort
+        coverage, injected = UnloadedFiles.inject(coverage, tracked_files)
+        # The merged result is the authoritative one users actually see, so it's
+        # the one that warns about source files dropped because they no longer
+        # exist on disk (#980). The per-process slices stay quiet to avoid one
+        # warning per worker.
+        Result.new(
+          coverage,
+          command_name: distinct_names.join(", "), contexts: contexts, report: true,
+          not_loaded_files: UnloadedFiles.never_executed(coverage) | injected,
+          tracked_files: tracked_files
+        ).tap { |result| result.command_names = distinct_names }
       end
 
       def merge_coverage(*results)
         return [[""], nil] if results.empty?
-        return results.first if results.size == 1
-
-        results.reduce do |(memo_command, memo_coverage), (command, coverage)|
-          # timestamp is dropped here, which is intentional (we merge it, it gets a new time stamp as of now)
-          merged_coverage = Combine.combine(Combine::ResultsCombiner, memo_coverage, coverage)
-          merged_command = memo_command + command
 
-          [merged_command, merged_coverage]
-        end
+        # Destructured rather than counted: the single-result fast path then
+        # hands back the very result it checked for, not a second lookup.
+        only, *rest = results
+        rest.empty? ? only : Combine::CoverageAccumulator.fold(results)
       end
 
-      #
-      # Gets all SimpleCov::Results stored in resultset, merges them and produces a new
-      # SimpleCov::Result with merged coverage data and the command_name
-      # for the result consisting of a join on all source result's names
       def merged_result
-        # conceptually this is just doing `merge_results(resultset_path)`
-        # it's more involved to make syre `synchronize_resultset` is only used around reading
-        resultset_hash = read_resultset
-        command_names, coverage = merge_valid_results(resultset_hash)
-
-        create_result(command_names, coverage)
+        tracked_files = Set.new
+        context_maps = ContextMap::Union.new
+        command_names, coverage = merge_valid_results(read_resultset, &entry_collector(tracked_files, context_maps))
+        create_result(command_names, coverage, tracked_files: tracked_files, contexts: context_maps.map)
       end
 
       def read_resultset
-        resultset_content =
-          synchronize_resultset do
-            read_file(resultset_path)
-          end
-
-        parse_json(resultset_content)
+        content = synchronize_resultset { ResultsetFile.read(resultset_path) }
+        ResultsetFile.decode(content)
       end
 
-      # Saves the given SimpleCov::Result in the resultset cache
       def store_result(result)
         synchronize_resultset do
-          # Ensure we have the latest, in case it was already cached
           new_resultset = read_resultset
 
-          # A single result only ever has one command_name, see `SimpleCov::Result#to_hash`
+          # A single result only ever has one command_name, see `Result#to_hash`.
           command_name, data = result.to_hash.first
-          new_resultset[command_name] = data
-          File.open(resultset_path, "w+") do |f_|
-            f_.puts JSON.pretty_generate(new_resultset)
-          end
-        end
-        true
-      end
-
-      # Ensure only one process is reading or writing the resultset at any
-      # given time
-      def synchronize_resultset
-        # make it reentrant
-        return yield if defined?(@resultset_locked) && @resultset_locked
-
-        begin
-          @resultset_locked = true
-          File.open(resultset_writelock, "w+") do |f|
-            f.flock(File::LOCK_EX)
-            yield
-          end
-        ensure
-          @resultset_locked = false
-        end
-      end
+          new_resultset[command_name] = merged_entry(new_resultset[command_name], data)
 
-      # We changed the format of the raw result data in simplecov, as people are likely
-      # to have "old" resultsets lying around (but not too old so that they're still
-      # considered we can adapt them).
-      # See https://github.com/simplecov-ruby/simplecov/pull/824#issuecomment-576049747
-      def adapt_result(result)
-        if pre_simplecov_0_18_result?(result)
-          adapt_pre_simplecov_0_18_result(result)
-        else
-          result
+          ResultsetStore.write(new_resultset)
         end
+        true
       end
 
-      # pre 0.18 coverage data pointed from file directly to an array of line coverage
-      def pre_simplecov_0_18_result?(result)
-        _key, data = result.first
+      # If an entry with the same command_name was written AFTER our process
+      # started, a sibling test runner wrote it. Combine coverage data rather
+      # than overwriting, so an empty parent-process result doesn't clobber the
+      # subprocess's real data (#581).
+      def merged_entry(existing, incoming)
+        return incoming unless concurrent_runner_entry?(existing, incoming)
 
-        data.is_a?(Array)
+        merged = incoming.merge(
+          "coverage" => Combine::ResultsCombiner.combine(existing.fetch("coverage"), incoming.fetch("coverage"))
+        )
+        merged = Contexts.carry(merged, existing, incoming)
+        UnloadedFiles.carry_tracked(merged, existing, incoming)
       end
 
-      def adapt_pre_simplecov_0_18_result(result)
-        result.transform_values do |line_coverage_data|
-          {"lines" => line_coverage_data}
-        end
+      def synchronize_resultset(&)
+        ResultsetStore.synchronize(&)
       end
     end
   end

data/lib/simplecov/result_processing.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class << self
+    # By default `collate` ignores the merge_timeout so all results in all
+    # files specified will be merged. Pass `ignore_timeout: false` to honor it.
+    #
+    # `processes:` above 1 fans the merge out across that many forked workers.
+    # The report is identical either way, not merely equivalent. The count is
+    # deliberately not clamped to the machine's core count nor gated on a
+    # minimum number of resultsets: what a collate job can afford is the
+    # caller's call. Anything below 1 is taken as 1, so an unset
+    # `SIMPLECOV_CONCURRENCY` needs no default of its own.
+    def collate(result_filenames, profile = nil, processes: ENV["SIMPLECOV_CONCURRENCY"].to_i,
+      ignore_timeout: true, &)
+      raise ArgumentError, "There are no reports to be merged" if result_filenames.empty?
+
+      initial_setup(profile, &)
+
+      current_run.result = ParallelResultMerger.merge_and_store(*result_filenames, processes: [1, processes].max,
+        ignore_timeout: ignore_timeout)
+
+      current_run.collating_result = true
+      run_exit_tasks!
+    ensure
+      current_run.collating_result = false
+    end
+
+    def result
+      return current_run.result if result?
+
+      merge = merging
+      collect_own_coverage(standalone: !merge)
+      merge_own_slice if merge
+      current_run.result
+    end
+
+    def merge_own_slice
+      ResultMerger.store_result(result) if result?
+      return unless merge_finalization_owner?
+
+      wait_for_other_processes
+      current_run.result = ResultMerger.merged_result
+    end
+
+    # `standalone` is true when no merge step follows, which makes this the
+    # final result: the one that reports dropped source files and injects
+    # unloaded files. When a merge does follow, both jobs belong to the merge.
+    def collect_own_coverage(standalone:)
+      return unless defined?(Coverage) && Coverage.running?
+
+      process_coverage_result(report: standalone, inject_unloaded: standalone)
+    end
+
+    def filtered(files)
+      result = files.to_a
+      filters.each do |filter|
+        result = result.reject { |source_file| filter.matches?(source_file) }
+      end
+      FileList.new result
+    end
+
+    # Files matched by no group fall into the implicit "Ungrouped" bucket. Any
+    # group left empty, Ungrouped included, is dropped so a profile's unused
+    # groups (#1293) don't pad the report as 100% covered.
+    def grouped(files, groups: default_groups)
+      return {} if GroupNames.validate!(groups.keys).empty?
+
+      grouped = groups.transform_values do |filter|
+        FileList.new(files.select { |source_file| filter.matches?(source_file) })
+      end
+
+      in_group = grouped_file_set(grouped)
+      grouped[GroupNames::UNGROUPED] = FileList.new(files.reject { |source_file| in_group.include?(source_file) })
+
+      grouped.reject { |_name, group_files| group_files.empty? }
+    end
+
+    def load_profile(name)
+      profiles.load(name)
+    end
+
+    def clear_result
+      current_run.result = nil
+    end
+
+    # @api private -- floored (#679) so the next run can compute drift.
+    def write_last_run(result)
+      LastRun.write(
+        result: result.coverage_statistics.transform_values { |stats| round_coverage(stats.percent) }
+      )
+    end
+
+    # @api private -- floored, to be extra strict.
+    def round_coverage(coverage)
+      coverage.floor(2)
+    end
+
+    # @api private -- the seam `SimpleCov::ResultMerger` injects through. Public
+    # only because the merge runs in another object, on behalf of processes
+    # whose configuration it may not share, so it supplies the paths itself.
+    def inject_unloaded_files(result, candidate_paths, synthesize: nil, lines: nil)
+      return [result, Set.new] if candidate_paths.empty?
+
+      # Synthesizing branch and method tuples means parsing every tracked file
+      # that wasn't loaded, about half the cost of simulating one, and nothing
+      # reads those tuples when neither criterion is enabled. The same goes for
+      # line data, which a branch-only or method-only run neither reports nor
+      # receives from `Coverage` for the files it loaded (#1250).
+      UnloadedFileInjector.call(
+        result, candidate_paths,
+        synthesize: synthesize.nil? ? branch_coverage? || method_coverage? : synthesize,
+        lines: lines.nil? ? line_coverage? : lines
+      )
+    end
+
+    private
+
+    def initial_setup(profile, &block)
+      load_profile(profile) if profile
+      configure(&block) if block
+    end
+
+    def grouped_file_set(grouped)
+      grouped.values.each_with_object(Set.new) { |file_list, set| set.merge(file_list) }
+    end
+
+    # Every path this process was told to track, whether or not it loaded them.
+    # Recorded on the result so a merge in another process can inject the ones
+    # nobody loaded without needing this process's `cover` / `track_files`
+    # configuration. A standalone `collate` never ran `SimpleCov.start` (#1250).
+    def tracked_file_paths
+      paths = UnloadedFileInjector.discover(
+        unloaded_file_discovery_globs, root: root, reject: filters.select(&:path_only?)
+      )
+      templates = paths.select { |path| Directive::Template.template?(path) }
+      return paths if templates.empty?
+
+      warn_templates_tracked(templates)
+      paths - templates
+    end
+
+    # Simulating a template means classifying its lines as Ruby and parsing it
+    # for branches, both of which produce a wrong shape, whereas `cover_views`
+    # compiles it and measures the real thing.
+    def warn_templates_tracked(templates)
+      names = templates.map { |path| path.delete_prefix(root).sub(%r{\A[/\\]}, "") }
+      warn "[SimpleCov]: `cover` matched templates it cannot simulate (#{names.join(", ")}). " \
+           "Add `cover_views` to measure templates."
+    end
+
+    # The legacy `track_files` glob (additive only) plus every string glob
+    # declared via `cover` (also restrictive, but the restriction lives in
+    # `Result#apply_cover_filters!`).
+    def unloaded_file_discovery_globs
+      [tracked_files, *cover_globs].compact
+    end
+
+    # `report:` and `inject_unloaded:` are false when a merge step follows.
+    # Only the union of every process's loaded files says what was really never
+    # loaded, and the merged result is the one that reports dropped source
+    # files, so a per-process slice would warn once per worker and simulate
+    # nearly the whole project only to have it merged away (#1250).
+    def process_coverage_result(report:, inject_unloaded: true)
+      # Templates nobody rendered are compiled into the running Coverage so they
+      # arrive at 0% below rather than being absent. Needs a live Coverage and
+      # ActionView, which rules out the merge point that does the same job for
+      # unloaded `.rb` files.
+      ViewCoverage.compile_unrendered
+      raw = UselessResultsRemover.call(Coverage.result)
+      adapted = ResultAdapter.call(raw)
+      # `Result#to_hash` serializes coverage after filtering, so a file this
+      # process loaded and then filtered out would otherwise be recorded as
+      # tracked while absent from the stored coverage, and the merge would
+      # simulate it back in as never-loaded (#1250).
+      tracked = tracked_file_paths - adapted.keys
+      result, not_loaded = inject_unloaded ? inject_unloaded_files(adapted, tracked) : [adapted, Set.new]
+      current_run.result = build_result(raw, result, not_loaded: not_loaded, tracked: tracked, report: report)
+    end
+
+    def build_result(raw, coverage, not_loaded:, tracked:, report:)
+      Result.new(
+        coverage, not_loaded_files: not_loaded, tracked_files: tracked, run_id: run_id,
+        worker_id: worker_id, contexts: test_tracker&.recorded_map(closing: raw), report: report
+      )
+    end
+  end
+end

data/lib/simplecov/run_identity.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SimpleCov
+  # Identifies one test invocation and each top-level parallel worker within it.
+  # Forked subprocesses inherit both values from their parent worker.
+  module RunIdentity
+    extend self
+
+    # Answers the run id together with its provenance: true when the id alone
+    # proves same-run membership (explicitly configured, derived from
+    # parallel_tests' per-invocation pid file, or freshly random), false when it
+    # was inferred from the parent pid, which consecutive runs launched by the
+    # same long-lived parent process share.
+    def generate
+      explicit = ENV.fetch("SIMPLECOV_RUN_ID", nil)
+      return [explicit, true] if explicit && !explicit.empty?
+
+      pid_file = ENV.fetch("PARALLEL_PID_FILE", nil)
+      return ["parallel-tests:#{File.basename(pid_file)}", true] if pid_file && !pid_file.empty?
+
+      return ["parallel-parent:#{Process.ppid}", false] if ParallelAdapters.current
+
+      [SecureRandom.uuid, true]
+    end
+
+    def worker_id
+      explicit = ENV.fetch("SIMPLECOV_WORKER_ID", nil)
+      return explicit if explicit && !explicit.empty?
+
+      number = ENV.fetch("TEST_ENV_NUMBER", nil)
+      return number.empty? ? "1" : number if number
+
+      Process.pid.to_s
+    end
+
+    # Decided where the id is generated, never re-inferred from the id's shape,
+    # so an explicit SIMPLECOV_RUN_ID that happens to look like an inferred one
+    # is still trusted.
+    def authoritative?
+      materialize_current
+      @authoritative
+    end
+
+    def current
+      materialize_current
+      @current
+    end
+
+    def materialize_current
+      @current, @authoritative = generate unless instance_variable_defined?(:@current)
+    end
+
+    def current_worker_id
+      @current_worker_id ||= worker_id
+    end
+
+    def prepare
+      ParallelAdapters.current
+      SimpleCov.run_id
+      SimpleCov.worker_id
+    end
+
+    module Accessors
+      def run_id
+        RunIdentity.current
+      end
+
+      def worker_id
+        RunIdentity.current_worker_id
+      end
+    end
+  end
+end

data/lib/simplecov/simulate_coverage.rb

@@ -1,29 +1,84 @@
 # frozen_string_literal: true
 
+require "coverage"
+require_relative "static_coverage_extractor"
+
 module SimpleCov
-  #
-  # Responsible for producing file coverage metrics.
-  #
   module SimulateCoverage
-  module_function
+    extend self
 
     #
-    # Simulate normal file coverage report on
-    # ruby 2.5 and return similar hash with lines and branches keys
+    # Simulate a file coverage report for a file that was tracked but never
+    # required, in the same hash shape as `Coverage.result`.
+    #
+    # The line classification comes from `Coverage.line_stub`, the same
+    # classification the runtime would have produced if the file had been
+    # required, overlaid with SimpleCov's `# :nocov:` toggles and
+    # `# simplecov:disable line` directive ranges, which `Coverage` doesn't
+    # know about. This keeps "relevant lines" identical whether a file was
+    # loaded or just tracked (#654).
+    #
+    # Branches and methods are enumerated by static analysis. Earlier behavior
+    # left both as empty hashes, which made unloaded files invisible to the
+    # branch/method denominators while their lines did count, so a glob that
+    # picked up files without specs silently inflated branch% relative to
+    # line% (#1059). When the file can't be parsed, fall back to the old empty
+    # hashes.
     #
-    # Happens when a file wasn't required but still tracked.
+    # Pass `synthesize: false` to skip the static analysis. Callers use it when
+    # neither branch nor method coverage is enabled, since nothing will read
+    # the tuples and the Prism parse is about half the cost of simulating a
+    # file (#1250).
     #
-    # @return [Hash]
+    # Pass `lines: false` to omit the `"lines"` key entirely, mirroring what
+    # `Coverage.result` reports for a file loaded under a branch-only or
+    # method-only run. Emitting zeroed lines there would make a simulated file
+    # indistinguishable from one a sibling process actually loaded.
     #
-    def call(absolute_path)
-      lines = File.foreach(absolute_path)
-
-      {
-        "lines" => LinesClassifier.new.classify(lines),
-        # we don't want to parse branches ourselves...
-        # requiring files can have side effects and we don't want to trigger that
-        "branches" => {}
-      }
+    def call(absolute_path, synthesize: true, lines: true)
+      source_lines = read_lines(absolute_path)
+      simulated = synthesized_tuples(source_lines, synthesize)
+      return simulated unless lines
+
+      classified = coverage_stub(absolute_path, source_lines) ||
+        LinesClassifier.new.classify(source_lines)
+      {"lines" => classified}.merge(simulated)
+    end
+
+    # Empty hashes when the static analysis is skipped (nothing enabled reads
+    # them) or unavailable (no Prism, or the file doesn't parse).
+    def synthesized_tuples(source_lines, synthesize)
+      empty = {"branches" => {}, "methods" => {}} #: Hash[String, Hash[untyped, untyped]]
+      synthesized = (StaticCoverageExtractor.call(source_lines.join) if synthesize) || empty
+
+      {"branches" => synthesized.fetch("branches"), "methods" => synthesized.fetch("methods")}
+    end
+
+    # SystemCallError, not just ENOENT: a `track_files` glob can sweep up an
+    # unreadable file or a directory named like a Ruby file, and simulation must
+    # degrade to "empty file" rather than crash the merge or report step.
+    def read_lines(path)
+      File.readlines(path)
+    rescue SystemCallError
+      []
+    end
+
+    # Combines `Coverage.line_stub` (which gets multi-line statements right)
+    # with `LinesClassifier` (which knows about `# :nocov:` toggles and
+    # `# simplecov:disable line` ranges). Answers nil when `Coverage` can't
+    # read or parse the file, or the runtime doesn't expose `line_stub`.
+    def coverage_stub(path, source_lines)
+      return nil unless Coverage.respond_to?(:line_stub)
+
+      # Paired off rather than indexed: the two lists describe the same file
+      # line for line. A line the classifier has no verdict for keeps the nil
+      # it would have been set to.
+      relevance = LinesClassifier.new.classify(source_lines)
+      Coverage.line_stub(path).zip(relevance).map { |hits, relevant| hits if relevant }
+    rescue SystemCallError, SyntaxError
+      # SystemCallError for the same reason as read_lines: line_stub reads the
+      # file itself, so EACCES/EISDIR surface here too.
+      nil
     end
   end
 end