simplecov 0.22.0 → 1.1.1

data/lib/simplecov/result_merger/unloaded_files.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ResultMerger
+    # The merge step's half of unloaded-file handling: the policy of when
+    # to inject and which criteria simulated files carry. The mechanism —
+    # expanding globs and simulating each file — is
+    # `SimpleCov::UnloadedFileInjector`, an easy name to confuse with this
+    # one.
+    #
+    # Injection moved here from the individual processes because only the union
+    # of what they all loaded says what was really never loaded. Doing it per
+    # process meant N workers simulated the same file up to N times and the
+    # merge threw all but one away. See #1250.
+    module UnloadedFiles
+    module_function
+
+      # The union of what every contributing process was told to track. Absent
+      # from resultsets written before this was recorded, in which case those
+      # processes injected their own unloaded files and the data is already in
+      # the coverage hash.
+      # A collector for the merge to hand `merge_valid_results`, gathering the
+      # tracked paths of every resultset that survives the merge timeout.
+      def collector(into)
+        ->(surviving) { into.merge(tracked_in(surviving)) }
+      end
+
+      def tracked_in(resultset)
+        resultset.each_with_object(Set.new) do |(_command_name, data), set|
+          set.merge(Array(data["tracked_files"]))
+        end
+      end
+
+      # Concurrent workers sharing a command name may have been told to track
+      # different sets, so keep both rather than letting the later write win.
+      def carry_tracked(entry, existing, incoming)
+        tracked = Array(existing["tracked_files"]) | Array(incoming["tracked_files"])
+        tracked.empty? ? entry : entry.merge("tracked_files" => tracked)
+      end
+
+      # Simulate each tracked file the merged coverage doesn't already carry.
+      # The paths come from the resultsets rather than this process's own
+      # configuration, which a standalone `collate` would not have: it never ran
+      # `SimpleCov.start`, so it has no `cover` glob to expand. Idempotent, so
+      # resultsets from an older SimpleCov (or from a `merging false` process)
+      # that already carry their unloaded files pass through untouched.
+      def inject(coverage, tracked_files)
+        SimpleCov.inject_unloaded_files(
+          coverage, tracked_files.to_a,
+          synthesize: carries?(coverage, "branches") || carries?(coverage, "methods"),
+          lines: carries?(coverage, "lines")
+        )
+      end
+
+      # A simulated file should have the same shape as the files it is being
+      # merged alongside, so the criteria come from the merged data rather than
+      # from this process's configuration, which is not necessarily the
+      # configuration any contributing process measured under: `simplecov merge`
+      # never ran `SimpleCov.start` at all. Giving injected files fewer tables
+      # than their neighbours is what inflates the percentage #1059 fixed.
+      #
+      # Falls back to the configuration when there is nothing to be consistent
+      # with, which is a merge of resultsets that carried no files.
+      def carries?(coverage, criterion)
+        return SimpleCov.public_send(CRITERION_PREDICATES.fetch(criterion)) if coverage.empty?
+
+        coverage.any? { |_filename, file_coverage| file_coverage[criterion] }
+      end
+
+      CRITERION_PREDICATES = {
+        "lines" => :line_coverage?,
+        "branches" => :branch_coverage?,
+        "methods" => :method_coverage?
+      }.freeze
+      private_constant :CRITERION_PREDICATES
+
+      # Which files no contributing process ever loaded. Injection reports the
+      # ones it added, but a file can also arrive already simulated from a
+      # resultset this merge didn't inject into, so the merged line counts are
+      # still consulted, using the same signal
+      # `Combine::CoverageAccumulator` reconciles synthesized tuples on.
+      #
+      # A file is judged only when it has a relevant line. A branch-only or
+      # method-only run reports no line data at all for the files it loaded,
+      # and a loaded file with no executable lines (a comment-only constants
+      # stub, say) reports every line as `nil` — either would otherwise read
+      # as "never executed" and mark a genuinely loaded file not loaded,
+      # turning its branch and method coverage into #902's 0%.
+      # `SimulateCoverage` omits lines under those criteria too and gives a
+      # simulated file a `0` on every relevant line, so genuinely unloaded
+      # files still carry judgeable data, and a simulated file with none is
+      # already flagged by injection reporting it.
+      def never_executed(coverage)
+        coverage.each_with_object(Set.new) do |(filename, file_coverage), set|
+          counts = Array(file_coverage["lines"]) #: Array[Integer?]
+          next unless counts.any? { |count| !count.nil? }
+
+          set << filename unless Combine::CoverageAccumulator.executed?(file_coverage["lines"])
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/result_merger.rb

@@ -1,6 +1,10 @@
 # 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/unloaded_files"
 
 module SimpleCov
   #
@@ -9,14 +13,11 @@ module SimpleCov
   # 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,88 +27,114 @@ 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)
-      end
-
-      def parse_file(path)
-        data = read_file(path)
-        parse_json(data)
+        # Tracked paths are collected as each resultset is parsed, so files are
+        # still read and discarded one at a time. See #1250.
+        tracked_files = Set.new
+        command_names, coverage = absorb_results(file_paths, ignore_timeout: ignore_timeout,
+                                                 &UnloadedFiles.collector(tracked_files))
+        create_result(command_names, coverage, tracked_files: tracked_files)
       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`.
+      #
+      # 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.
+      #
+      # 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`.
+      # Absorbing is still one resultset at a time, so the memory ceiling
+      # above is unchanged.
+      #
+      # `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 — rather than reimplement
+      # this loop and risk timing something other than what ships.
+      #
+      # @return [Array] the command names and the merged coverage
+      #
+      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)
+        # Respect quiet configurations and keep this consistent with every
+        # other SimpleCov diagnostic. 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)
+      def create_result(command_names, coverage, tracked_files: Set.new)
         return nil unless coverage
 
         command_name = command_names.reject(&:empty?).sort.join(", ")
-        SimpleCov::Result.new(coverage, command_name: command_name)
+        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 (issue #980). The per-process slices built in
+        # `process_coverage_result` stay quiet to avoid one warning per worker.
+        SimpleCov::Result.new(
+          coverage,
+          command_name: command_name,
+          not_loaded_files: UnloadedFiles.never_executed(coverage) | injected,
+          tracked_files: tracked_files.to_a,
+          report: true
+        )
       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
+        Combine::CoverageAccumulator.fold(results)
       end
 
       #
@@ -115,79 +142,47 @@ module SimpleCov
       # 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
+        command_names, coverage = merge_valid_results(read_resultset, &UnloadedFiles.collector(tracked_files))
+        create_result(command_names, coverage, tracked_files: tracked_files)
       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)
+      def store_result(result) # rubocop:disable Naming/PredicateMethod
         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`
           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
+          new_resultset[command_name] = merged_entry(new_resultset[command_name], data)
 
-      # 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
-
-      # 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 (typically a subprocess our parent
+      # process shelled out to) wrote it. Combine coverage data rather than
+      # overwriting, so an empty parent-process result doesn't clobber the
+      # subprocess's real data. See https://github.com/simplecov-ruby/simplecov/issues/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["coverage"], incoming["coverage"])
+        )
+        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,218 @@
+# frozen_string_literal: true
+
+# Result-building façade: turns the raw `Coverage.result` hash into a
+# `SimpleCov::Result`, applies filters and groups, drives merging
+# across test suites via `SimpleCov::ResultMerger`, and exposes the
+# `collate` entry point for stitching disparate resultsets together.
+module SimpleCov
+  class << self
+    #
+    # Collate a series of SimpleCov result files into a single SimpleCov output.
+    #
+    # See README for usage. 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 worker
+    # processes, for a collate big enough that reading and parsing the
+    # resultsets dominates it. The report is identical either way, not merely
+    # equivalent — the workers visit the resultsets in the order the
+    # single-process merge visits them — and one process never forks at all.
+    # The count is deliberately not clamped to the machine's core count nor
+    # gated on some minimum number of resultsets: how many processes a collate
+    # job can afford is the caller's call, not SimpleCov's. Anything below 1 is
+    # taken as 1, so a count computed from arithmetic that can reach zero needs
+    # no guarding. Defaults to `SIMPLECOV_CONCURRENCY`, or 1 when that is
+    # unset. See `SimpleCov::ParallelResultMerger`.
+    #
+    def collate(result_filenames, profile = nil, processes: ENV.fetch("SIMPLECOV_CONCURRENCY", 1).to_i,
+                ignore_timeout: true, &)
+      raise ArgumentError, "There are no reports to be merged" if result_filenames.empty?
+
+      initial_setup(profile, &)
+
+      # Use the ResultMerger to produce a single, merged result, ready to use.
+      @result = ParallelResultMerger.merge_and_store(*result_filenames, processes: [1, processes].max,
+                                                                        ignore_timeout: ignore_timeout)
+
+      @collating_result = true
+      run_exit_tasks!
+    ensure
+      @collating_result = false
+    end
+
+    #
+    # Returns the result for the current coverage run. With merging enabled,
+    # every process stores its own slice, but only the finalization owner reads
+    # and caches the merged result.
+    #
+    def result
+      return @result if result?
+
+      use_merging = merging
+
+      collect_own_coverage(standalone: !use_merging)
+
+      # If we're using merging of results, store the current result
+      # first (if there is one), then merge the results and return those
+      if use_merging
+        SimpleCov::ResultMerger.store_result(@result) if result?
+        return @result unless merge_finalization_owner?
+
+        wait_for_other_processes
+        @result = SimpleCov::ResultMerger.merged_result
+      end
+
+      @result
+    end
+
+    # Build this process's slice of the coverage result. `standalone` is true
+    # when no merge step follows, which makes this the final result: it is the
+    # one that reports dropped source files, and the one that injects unloaded
+    # files. When a merge does follow, both jobs belong to the merged result.
+    def collect_own_coverage(standalone:)
+      return unless defined?(Coverage) && Coverage.running?
+
+      process_coverage_result(report: standalone, inject_unloaded: standalone)
+    end
+
+    # Returns nil if the result has not been computed, otherwise the result.
+    def result?
+      defined?(@result) && @result
+    end
+
+    # @api private — true while `SimpleCov.collate` is running its finalizer.
+    def collating_result?
+      defined?(@collating_result) && @collating_result
+    end
+
+    # Applies the configured filters to the given array of SimpleCov::SourceFile items
+    def filtered(files)
+      result = files.to_a.dup
+      filters.each do |filter|
+        result = result.reject { |source_file| filter.matches?(source_file) }
+      end
+      SimpleCov::FileList.new result
+    end
+
+    # Bin the given source files by group filter. `groups:` defaults to
+    # `SimpleCov.groups`; pass a Hash explicitly to bin against a
+    # different group config (e.g., the snapshot a Result captured at
+    # construction). Files matched by no group fall into the implicit
+    # "Ungrouped" bucket.
+    def grouped(files, groups: SimpleCov.groups)
+      return {} if GroupNames.validate!(groups.keys).empty?
+
+      grouped = groups.transform_values do |filter|
+        SimpleCov::FileList.new(files.select { |source_file| filter.matches?(source_file) })
+      end
+
+      in_group  = grouped_file_set(grouped)
+      ungrouped = files.reject { |source_file| in_group.include?(source_file) }
+      grouped[GroupNames::UNGROUPED] = SimpleCov::FileList.new(ungrouped) if ungrouped.any?
+
+      grouped
+    end
+
+    # Applies the profile of given name on SimpleCov configuration
+    def load_profile(name)
+      profiles.load(name)
+    end
+
+    # Clear out the previously cached .result. Primarily useful in testing.
+    def clear_result
+      @result = nil
+    end
+
+    # @api private — persist the per-criterion coverage percentages
+    # rounded down (see #679) so the next run can compute drift.
+    def write_last_run(result)
+      SimpleCov::LastRun.write(
+        result: result.coverage_statistics.transform_values { |stats| round_coverage(stats.percent) }
+      )
+    end
+
+    # @api private — round down to two decimals to be extra strict.
+    def round_coverage(coverage)
+      coverage.floor(2)
+    end
+
+    # Add simulated coverage for each of `candidate_paths` the result doesn't
+    # already carry, and return it with the set of paths added.
+    #
+    # @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, which is about half the cost of simulating one.
+      # Nothing reads those tuples when neither criterion is enabled —
+      # `Combine::CoverageAccumulator` only combines them per criterion, and the
+      # statistics drop them the same way — so skip the parse. 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. See #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 (and from there into the resultset) so that 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` and so has none of its own. See #1250.
+    def tracked_file_paths
+      UnloadedFileInjector.discover(
+        unloaded_file_discovery_globs, root: root, reject: filters.select(&:path_only?)
+      )
+    end
+
+    # Globs to expand on disk when injecting unloaded files into the
+    # result. Combines the legacy `track_files` glob (additive only)
+    # with 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
+
+    # Run all the steps that handle processing the raw coverage result.
+    # `report:` is true only when this slice is the final result (merging
+    # off); with merging on the merged result reports dropped source files,
+    # so the per-process slice stays quiet to avoid one warning per worker.
+    #
+    # `inject_unloaded:` is likewise false when a merge step follows. Only the
+    # union of every process's loaded files says what was really never loaded,
+    # so injecting here means each worker simulates nearly the whole project
+    # and all but one of those passes is merged away. See #1250.
+    def process_coverage_result(report:, inject_unloaded: true)
+      raw = SimpleCov::UselessResultsRemover.call(Coverage.result)
+      adapted = SimpleCov::ResultAdapter.call(raw)
+      # What this process was told to track and did not load. Subtracting what
+      # it loaded matters because `Result#to_hash` serializes coverage after
+      # filtering: 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. See #1250.
+      tracked = tracked_file_paths - adapted.keys
+      result, not_loaded = inject_unloaded ? inject_unloaded_files(adapted, tracked) : [adapted, Set.new]
+      @result = SimpleCov::Result.new(
+        result, not_loaded_files: not_loaded, tracked_files: tracked,
+                run_id: SimpleCov.run_id, worker_id: SimpleCov.worker_id, report: report
+      )
+    end
+  end
+end