simplecov 0.22.0 → 1.3.0

data/lib/simplecov/result_adapter.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
+require "coverage"
+
 module SimpleCov
-  #
-  # Responsible for adapting the format of the coverage result whether it's default or with statistics
-  #
   class ResultAdapter
     attr_reader :result
 
@@ -11,20 +10,140 @@ module SimpleCov
       @result = result
     end
 
-    def self.call(*args)
-      new(*args).adapt
+    def self.call(*)
+      new(*).adapt
     end
 
     def adapt
       return unless result
 
-      result.each_with_object({}) do |(file_name, cover_statistic), adapted_result|
-        if cover_statistic.is_a?(Array)
-          adapted_result.merge!(file_name => {"lines" => cover_statistic})
-        else
-          adapted_result.merge!(file_name => cover_statistic)
-        end
+      result.to_h do |file_name, cover_statistic|
+        [file_name, adapt_one(file_name, cover_statistic)]
+      end
+    end
+
+    private
+
+    # Pre-0.18 resultsets pointed each filename straight at a line-coverage
+    # array; everything since uses the `{lines:, branches:, methods:}` shape.
+    def adapt_one(file_name, cover_statistic)
+      return {"lines" => cover_statistic} if cover_statistic.instance_of?(Array)
+
+      adapt_oneshot_lines_if_needed(file_name, cover_statistic)
+      normalize_method_keys(cover_statistic)
+      aggregate_duplicated_branches(cover_statistic)
+      cover_statistic
+    end
+
+    # Normalizes memory addresses in method coverage keys so results from
+    # different processes can be merged: anonymous class names like
+    # "#<Class:0x00007ff19ab24790>" get inconsistent addresses across runs, and
+    # address widths vary by runtime.
+    ADDRESS_PATTERN = /0x\h+/
+    private_constant :ADDRESS_PATTERN
+
+    ADDRESS_PLACEHOLDER = "0x0"
+    private_constant :ADDRESS_PLACEHOLDER
+
+    # Strips the `#<Class:Foo>` wrapper Ruby's Coverage adds to singleton-class
+    # method keys. `module_function` and class methods get recorded both as
+    # singleton and instance/module entries pointing at the same source
+    # location, and only one of the two is ever reachable at runtime. Only
+    # named constants: anonymous-class addresses are left to ADDRESS_PATTERN.
+    SINGLETON_WRAPPER_PATTERN = /\A#<Class:([A-Z_][\w:]*)>\z/
+    private_constant :SINGLETON_WRAPPER_PATTERN
+
+    # Ruby's method coverage records one entry per defined method, not per
+    # source location: a block handed to `define_method` from a shared code
+    # path yields a separate `[receiver, name, location]` entry for every class
+    # it's defined on and every name it's defined under, all pointing at the
+    # same source. A file-based report can only express "was the method at this
+    # location ever executed", so entries are aggregated by location alone,
+    # summing hits. Otherwise each generated copy that never ran shows as a
+    # phantom uncovered method on a line whose line coverage is 100% (#1234).
+    # The first entry's normalized key is kept for display.
+    def normalize_method_keys(cover_statistic)
+      methods = cover_statistic[:methods]
+      return unless methods
+
+      aggregated = {} #: Hash[untyped, [untyped, Integer]]
+      methods.each_with_object(aggregated) do |(key, count), memo|
+        location = key[2..] #: Array[untyped]
+        retained_key, existing = memo[location] || [normalize_method_key(key), 0]
+        memo[location] = [retained_key, existing + count]
       end
+      cover_statistic[:methods] = aggregated.values.to_h
+    end
+
+    def normalize_method_key(key)
+      receiver, *rest = key
+      normalized_receiver = class_display_name(receiver)
+        .gsub(ADDRESS_PATTERN, ADDRESS_PLACEHOLDER)
+        .sub(SINGLETON_WRAPPER_PATTERN, '\1')
+      [normalized_receiver, *rest]
+    end
+
+    # Rendering a class name can execute user code: a singleton class's `to_s`
+    # renders its attached object via `#inspect`, which a module can shadow
+    # with an incompatible signature (Liquid::Utils defines
+    # `inspect(value, max_depth = 2)` as a module_function, so rendering
+    # `#<Class:Liquid::Utils>` raises ArgumentError). A coverage report must
+    # never crash the host suite over that (#1236).
+    def class_display_name(klass)
+      klass.to_s
+    rescue
+      singleton_wrapper_name(klass) || Object.instance_method(:to_s).bind_call(klass)
+    end
+
+    # `singleton_class?` is a Module method, so a receiver that is neither a
+    # class nor a module has to be turned away first. Anything that then
+    # answers `singleton_class?` truthily is a Class, so `attached_object`
+    # applies, reached through a bound method so shadowing cannot divert it.
+    def singleton_wrapper_name(klass)
+      return nil unless klass.is_a?(Module) && klass.singleton_class?
+
+      attached = Class.instance_method(:attached_object).bind_call(klass)
+      name = Module.instance_method(:name).bind_call(attached) if attached.is_a?(Module)
+      name && "#<Class:#{name}>"
+    end
+
+    # Ruby's eval coverage records a fresh set of branch entries for every
+    # compile of an eval'd string: a template rendered through multiple view
+    # classes yields several `[:if, id, location]` conditions at identical
+    # coordinates, each counting only the renders that flowed through that
+    # compile. Reported as-is they inflate the branch denominator and turn a
+    # side covered under a different compile into a phantom miss (#1235).
+    # Absorbing into an empty table dedups, since BranchesCombiner keys arms on
+    # location identity. Regular source can never produce two conditions at the
+    # same location, so this is a no-op outside eval.
+    def aggregate_duplicated_branches(cover_statistic)
+      branches = cover_statistic[:branches]
+      return unless branches
+
+      combiner = Combine::BranchesCombiner
+      cover_statistic[:branches] = combiner.materialize(combiner.absorb({}, branches))
+    end
+
+    def adapt_oneshot_lines_if_needed(file_name, cover_statistic)
+      return unless cover_statistic.key?(:oneshot_lines)
+
+      oneshot_lines = cover_statistic.delete(:oneshot_lines)
+      line_stub = build_line_stub(file_name)
+      oneshot_lines.each { |covered_line| line_stub[covered_line - 1] = 1 }
+      cover_statistic[:lines] = line_stub
+    end
+
+    # A file that has vanished or no longer parses has no stub to build from,
+    # and neither does a runtime without `Coverage.line_stub` (TruffleRuby), so
+    # start from nothing: the assignments in `adapt_oneshot_lines_if_needed`
+    # grow the array to the highest covered line, which is as far as the
+    # oneshot data reaches anyway.
+    def build_line_stub(file_name)
+      return [] unless Coverage.respond_to?(:line_stub)
+
+      Coverage.line_stub(file_name)
+    rescue Errno::ENOENT, SyntaxError
+      []
     end
   end
 end

data/lib/simplecov/result_merger/contexts.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ResultMerger
+    module Contexts
+      extend self
+
+      # The same union-or-drop rule the cross-suite merge applies: the union when
+      # both sides recorded a map, no map at all when either did not, since a
+      # partial map would present one runner's tests as the pair's. `entry` starts
+      # as a copy of `incoming`, so the drop has to remove the key rather than
+      # merely decline to add it.
+      def carry(entry, existing, incoming)
+        ours = ContextMap.from_hash(existing["contexts"])
+        theirs = ContextMap.from_hash(incoming["contexts"])
+        return entry.except("contexts") unless ours && theirs
+
+        entry.merge("contexts" => ours.absorb(theirs).to_h)
+      end
+    end
+  end
+end

data/lib/simplecov/result_merger/legacy_format_adapter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ResultMerger
+    module LegacyFormatAdapter
+      extend self
+
+      def call(result)
+        pre_0_18?(result) ? upgrade(result) : result
+      end
+
+      # Pre-0.18 coverage data pointed from file directly to an array of line
+      # coverage rather than a `{"lines" => [...]}` hash.
+      def pre_0_18?(result)
+        _key, data = result.first
+        data.instance_of?(Array)
+      end
+
+      def upgrade(result)
+        result.transform_values { |line_coverage_data| {"lines" => line_coverage_data} }
+      end
+    end
+  end
+end

data/lib/simplecov/result_merger/resultset_file.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SimpleCov
+  module ResultMerger
+    # Read and parse a `.resultset.json` with the same tolerance the historical
+    # `ResultMerger` had: a missing or empty file quietly returns `{}`, an
+    # unparseable one warns and returns `{}`, and malformed entries inside a
+    # valid file are warned about and dropped.
+    module ResultsetFile
+      extend self
+
+      def parse(path)
+        data = read(path)
+        decode(data)
+      end
+
+      # A missing or blank file quietly means "no results yet"; anything else, a
+      # 1-byte truncation included, flows through decode so corruption warns
+      # instead of silently vanishing. Read first and rescue rather than check
+      # exist?, which is racy against a concurrent clean.
+      def read(path)
+        data = File.read(path)
+        return if data.match?(/\A\s*\z/)
+
+        data
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # Valid JSON need not be an object, but everything downstream iterates
+      # command => data pairs, so anything else gets the same tolerance as a parse
+      # failure. A "null" file has long meant an empty resultset.
+      def decode(content)
+        return {} unless content
+
+        parsed = JSON.parse(content)
+        return {} if parsed.nil?
+
+        parsed.instance_of?(Hash) ? drop_malformed_entries(parsed) : invalid_resultset
+      rescue
+        invalid_resultset
+      end
+
+      def drop_malformed_entries(resultset)
+        malformed, valid = resultset.partition { |_command_name, data| !well_formed_entry?(data) }
+        return resultset if malformed.empty?
+
+        warn "[SimpleCov]: Warning! Ignoring malformed resultset entries: #{malformed.map(&:first).sort.join(", ")}"
+        valid.to_h
+      end
+
+      # Every consumer relies on a Hash carrying a Numeric "timestamp" and a Hash
+      # "coverage". A truncated or hand-edited entry would otherwise crash out of
+      # the middle of an at_exit merge.
+      def well_formed_entry?(data)
+        data.instance_of?(Hash) && data["timestamp"].is_a?(Numeric) && data["coverage"].instance_of?(Hash)
+      end
+
+      def invalid_resultset
+        warn "[SimpleCov]: Warning! Parsing JSON content of resultset file failed"
+        {}
+      end
+    end
+  end
+end

data/lib/simplecov/result_merger/resultset_run_identity.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module ResultMerger
+    # Run and worker metadata queries used by resultset storage and parallel
+    # coordination.
+    module ResultsetRunIdentity
+      # One namespaced identity per distinct worker that wrote to the current run:
+      # `[:worker, id]` for entries carrying a worker id, `[:legacy, command_name]`
+      # for fresh entries written without one. Pairs rather than mangled strings,
+      # so a resultset mixing both kinds can never alias a real worker id to a
+      # synthesized legacy identity.
+      def worker_identities_for_run(results, run_id, started_at)
+        results.filter_map do |command_name, data|
+          next unless current_run_entry?(data, run_id, started_at)
+
+          worker_id = data["worker_id"]
+          worker_id.to_s.empty? ? [:legacy, command_name] : [:worker, worker_id.to_s]
+        end.uniq
+      end
+
+      # `eql?` rather than `==`: run ids are strings, and value equality already
+      # answers false for the nil run id a caller with no identity of its own
+      # passes.
+      def current_run_entry?(entry, run_id, started_at)
+        return false unless entry.instance_of?(Hash)
+
+        entry_run_id = entry["run_id"]
+        return fresh_entry?(entry, started_at) unless entry_run_id
+        return false unless entry_run_id.eql?(run_id)
+        return true if RunIdentity.authoritative?
+
+        fresh_entry?(entry, started_at)
+      end
+
+      def fresh_entry?(entry, started_at)
+        timestamp = entry["timestamp"]
+        timestamp.is_a?(Numeric) && started_at && timestamp >= started_at.to_f
+      end
+
+      # Either the entry shares our run id, or it was written strictly after our
+      # process started. A mismatched run id must not defeat the timestamp check: a
+      # subprocess we shelled out to generates its own random run id, and its
+      # freshly written entry is exactly the data #581 protects from being
+      # clobbered. Strict id matching is reserved for worker counting, where
+      # admitting a stale entry would end a sibling wait early.
+      def concurrent_runner_entry?(entry, incoming = nil)
+        return false unless entry.instance_of?(Hash)
+
+        incoming_run_id = incoming["run_id"] if incoming.instance_of?(Hash)
+        started_at = SimpleCov.process_start_time
+        return true if current_run_entry?(entry, incoming_run_id, started_at)
+
+        written_after_start?(entry, started_at)
+      end
+
+      # Strictly after, unlike `fresh_entry?`: an entry stamped at the exact
+      # instant we started is treated as leftover from a previous run.
+      def written_after_start?(entry, started_at)
+        timestamp = entry["timestamp"]
+        timestamp.is_a?(Numeric) && started_at && timestamp > started_at.to_f
+      end
+    end
+  end
+end

data/lib/simplecov/result_merger/resultset_store.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "monitor"
+require_relative "../atomic_file"
+
+module SimpleCov
+  module ResultMerger
+    module ResultsetStore
+      LOCK_MONITOR = Monitor.new
+      private_constant :LOCK_MONITOR
+
+      extend self
+
+      def resultset_path
+        File.join(SimpleCov.coverage_path, ".resultset.json")
+      end
+
+      def writelock_path
+        File.join(SimpleCov.coverage_path, ".resultset.json.lock")
+      end
+
+      # Compact JSON, not pretty-printed: this is a machine-read cache that every
+      # parallel worker rewrites wholesale, and on a large project pretty printing
+      # nearly doubles the bytes written, read back, and parsed on each of those
+      # store-merge round trips.
+      def write(resultset)
+        AtomicFile.write(resultset_path, "#{JSON.generate(resultset)}\n")
+      end
+
+      # Threads are serialized before the process-wide file lock is taken. Nested
+      # calls by the owning thread bypass flock so they cannot deadlock on a second
+      # descriptor for the same lock file.
+      def synchronize(&)
+        return yield if LOCK_MONITOR.mon_owned?
+
+        LOCK_MONITOR.synchronize { with_flock(&) }
+      end
+
+      def with_flock(&)
+        FileUtils.mkdir_p(SimpleCov.coverage_path)
+        holding_writelock(&)
+      end
+
+      def holding_writelock
+        open_file(writelock_path, "w+") do |file|
+          file.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      # mutant:disable — Ruby 4.0 removed Kernel#open's leading-pipe
+      # command mode, so no test can tell `File.open` from `open` here
+      # any more. The explicit receiver is kept: on older rubies it is
+      # what refuses to run a lock path as a command.
+      def open_file(name, mode, &)
+        File.open(name, mode, &)
+      end
+    end
+  end
+end

data/lib/simplecov/result_merger/unloaded_files.rb

@@ -0,0 +1,95 @@
+# 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`.
+    #
+    # 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 (#1250).
+    module UnloadedFiles
+      extend self
+
+      # A collector for the merge to hand `merge_valid_results`, gathering the
+      # tracked paths of every resultset that survives the merge timeout.
+      # Absent from resultsets written before this was recorded, in which case
+      # those processes injected their own unloaded files already.
+      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
+
+      # Simulates 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. Idempotent,
+      # so resultsets 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 what 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.
+      #
+      # 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 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%.
+      def never_executed(coverage)
+        coverage.each_with_object(Set.new) do |(filename, file_coverage), set|
+          counts = Array(file_coverage["lines"]) #: Array[Integer?]
+          # A line count is an Integer or nil, and every Integer is truthy, so a
+          # truthy element is exactly a relevant line.
+          next unless counts.any?
+
+          set << filename unless Combine::CoverageAccumulator.executed?(counts)
+        end
+      end
+    end
+  end
+end