simplecov 0.22.0 → 1.3.0

data/lib/simplecov/parallel_result_merger.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "parallel_result_merger/worker_payload"
+
+module SimpleCov
+  #
+  # `ResultMerger.absorb_results` fanned out across forked workers, driving
+  # `SimpleCov.collate(..., processes: N)`. Each worker folds a contiguous
+  # slice of the file list and ships the pair back over a pipe.
+  #
+  # The slices are contiguous and merged back in order, so the fold visits the
+  # resultsets in the order the serial fold visits them and the merged result
+  # is identical to `SimpleCov.collate`'s, not merely equivalent.
+  #
+  module ParallelResultMerger
+    extend self
+
+    def merge_and_store(*file_paths, processes:, ignore_timeout: false)
+      return ResultMerger.merge_and_store(*file_paths, ignore_timeout: ignore_timeout) if processes < 2
+
+      result = merge_results(*file_paths, processes: processes, ignore_timeout: ignore_timeout)
+      ResultMerger.store_result(result) if result
+      result
+    end
+
+    def merge_results(*file_paths, processes:, ignore_timeout: false)
+      tracked_files = Set.new
+      context_maps = ContextMap::Union.new
+      pair = absorb_results(file_paths, processes: processes, ignore_timeout: ignore_timeout,
+        tracked_files: tracked_files, context_maps: context_maps)
+      return ResultMerger.merge_results(*file_paths, ignore_timeout: ignore_timeout) unless pair
+
+      command_names, coverage = pair
+      ResultMerger.create_result(command_names, coverage, tracked_files: tracked_files, contexts: context_maps.map)
+    end
+
+    # Answers nil when the work could not be fanned out and the caller should
+    # merge in this process instead. The tracked paths and context-map union a
+    # worker's slice carried come back with its payload rather than through a
+    # collector block, since that block would be mutating state in the wrong
+    # process.
+    def absorb_results(file_paths, processes:, ignore_timeout: false, tracked_files: Set.new,
+      context_maps: ContextMap::Union.new)
+      return nil if processes < 2 || file_paths.size < 2
+      # JRuby cannot fork on the JVM and deliberately answers false here, but
+      # still defines `Kernel#fork` and raises `NotImplementedError` from it,
+      # so probing that instead would send it down the fan-out.
+      return nil unless Process.respond_to?(:fork)
+
+      fan_out(chunk(file_paths, processes), ignore_timeout: ignore_timeout, tracked_files: tracked_files,
+        context_maps: context_maps)
+    end
+
+    def chunk(file_paths, processes)
+      groups = [processes, file_paths.size].min
+      base, remainder = file_paths.size.divmod(groups)
+      remaining = file_paths.dup
+
+      Array.new(groups) { |index| remaining.shift(base + ((index < remainder) ? 1 : 0)) }
+    end
+
+    # A `fork` that fails here raises, and is left to: the runtimes that never
+    # fork are already excluded, so what remains is the OS refusing a process
+    # we expected to get, which says something is wrong with the machine rather
+    # than with the merge.
+    def fan_out(chunks, ignore_timeout:, tracked_files:, context_maps:)
+      workers = spawn_workers(chunks, ignore_timeout: ignore_timeout)
+      payloads = collect_payloads(workers)
+      return nil unless payloads
+
+      payloads.each { |payload| WorkerPayload.absorb(payload, tracked_files, context_maps) }
+      ResultMerger.merge_coverage(*payloads.map { |payload| WorkerPayload.pair(payload) })
+    end
+
+    def spawn_workers(chunks, ignore_timeout:)
+      workers = [] #: Array[Hash[Symbol, untyped]]
+      chunks.each do |chunk|
+        workers << spawn_worker(chunk, ignore_timeout: ignore_timeout)
+      rescue
+        abandon(workers)
+        raise
+      end
+      workers
+    end
+
+    def abandon(workers)
+      workers.each do |worker|
+        worker.fetch(:reader).close
+        succeeded?(worker.fetch(:pid))
+      end
+    end
+
+    # The caller cleans up the workers it knows about, but this pipe is ours.
+    # The safe navigation keeps the cleanup well-defined when `IO.pipe` itself
+    # raised, and Steep cannot type body locals inside an ensure.
+    def spawn_worker(chunk, ignore_timeout:)
+      reader, writer = IO.pipe
+      pid = fork { run_in_child(reader, writer, chunk, ignore_timeout) }
+      {pid: pid, reader: reader}
+    ensure
+      # @type var writer: IO?
+      # @type var reader: IO?
+      # @type var pid: Integer?
+      writer&.close
+      reader&.close unless pid
+    end
+
+    # `exit!` rather than `exit` because the child must never fall through to
+    # the collating process's inherited `at_exit` handlers, SimpleCov's own
+    # report generation included.
+    def run_in_child(reader, writer, chunk, ignore_timeout)
+      reader.close
+      exit!(run_worker(chunk, writer, ignore_timeout: ignore_timeout))
+    end
+
+    # Kept free of the exit itself so it can be exercised in-process.
+    def run_worker(chunk, writer, ignore_timeout:)
+      Marshal.dump(WorkerPayload.build(chunk, ignore_timeout: ignore_timeout), writer)
+      writer.close
+      0
+    rescue => e
+      warn "[SimpleCov]: parallel merge worker failed: #{e.class}: #{e}" if SimpleCov.print_errors
+      1
+    end
+
+    # Answers nil if any worker failed, so the caller redoes the fold serially
+    # rather than report a subset of the resultsets as the whole.
+    def collect_payloads(workers)
+      payloads = drain(workers)
+      failed = workers.count { |worker| !succeeded?(worker.fetch(:pid)) }
+      return warn_about_failed_workers(failed, workers.size) unless failed.zero? && payloads.all?
+
+      payloads
+    ensure
+      workers.each { |worker| worker.fetch(:reader).close }
+    end
+
+    # A thread per worker, so every pipe is drained while the workers are still
+    # writing. A payload larger than the pipe buffer would otherwise block its
+    # worker mid-write, and the parent would block reaping a worker that can
+    # never finish.
+    def drain(workers)
+      workers.map { |worker| Thread.new { read_payload(worker.fetch(:reader)) } }.map(&:value)
+    end
+
+    def read_payload(reader)
+      # The writer is a fork of this very process and the pipe never leaves it,
+      # so this is our own data coming back through our own kernel buffer, not
+      # input.
+      Marshal.load(reader) # rubocop:disable Security/MarshalLoad
+    rescue
+      nil
+    end
+
+    def succeeded?(pid)
+      _pid, status = Process.wait2(pid)
+      status.success?
+    rescue SystemCallError
+      # Errno::ECHILD: nothing left to reap, so there is no status to judge
+      # this worker's slice by and we have to assume it did not finish.
+      false
+    end
+
+    def warn_about_failed_workers(failed, total)
+      return unless SimpleCov.print_errors
+
+      warn "[SimpleCov]: parallel merge did not complete (#{failed} of #{total} workers failed); " \
+           "merging the resultsets in this process instead."
+    end
+  end
+end

data/lib/simplecov/process.rb

@@ -1,19 +1,41 @@
 # frozen_string_literal: true
 
-module Process
+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), and external_at_exit may point at a Minitest.after_run deferral
+    # that is pid-pinned to the parent. Resetting both is what lets the at_fork
+    # proc's `SimpleCov.start` install a hook that actually fires (#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 re-runs SimpleCov's
+  # at_fork callback in the child. `Process._fork` is the official extension
+  # point: `Kernel#fork`, `Process.fork`, and `IO.popen("-")` all funnel
+  # through it, and prepending composes with other libraries doing the same.
+  module ProcessForkHook
+    # The next serial is assigned in the parent, before the fork, so the child
+    # inherits its own stable ordinal via copy-on-write, and the child is marked
+    # 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 (#1171, #1227).
+    def _fork
+      active = defined?(SimpleCov) && Coverage.running?
+      SimpleCov.next_subprocess_serial! if active
+      pid = super
+      if pid.zero? && active
+        SimpleCov.mark_forked_subprocess!
+        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/production/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module Production
+    # Configuration and store-format failures. Sink errors raised from `store` are
+    # not wrapped in this: the runtime rescues them, warns, and retries on the
+    # next interval.
+    class Error < StandardError
+    end
+  end
+end

data/lib/simplecov/production/file_sink.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "error"
+
+module SimpleCov
+  module Production
+    # The bundled sink: a single JSON file, union-merged under an exclusive
+    # lock so any number of processes on the same host can share it. This is
+    # the reference for the sink contract:
+    #
+    #   store(coverage)  # {"lib/foo.rb" => [1, 3, 12], ...} of
+    #                    # root-relative paths to sorted line numbers
+    #
+    # A sink must merge (never replace: many processes each hold only a
+    # slice), must be idempotent (the same lines may arrive twice), and
+    # signals failure by raising, which makes the runtime keep the delta and
+    # retry next interval.
+    #
+    # `last_seen` stamps each file with the last store that carried it.
+    # Oneshot clears on drain, so still-running code re-reports every interval
+    # and the stamp tracks real recency, not first sighting. The field is
+    # optional on read: a v1 store written before it existed simply has no
+    # recency evidence to offer.
+    class FileSink
+      # The envelope key, which is also how `read` tells a production coverage
+      # file from an arbitrary JSON document it must not clobber or misread.
+      ENVELOPE = "simplecov_production"
+      FORMAT_VERSION = 1
+
+      attr_reader :path
+
+      def initialize(path:)
+        @path = File.expand_path(path)
+      end
+
+      def store(coverage)
+        FileUtils.mkdir_p(File.dirname(path))
+        with_exclusive_lock do |file|
+          existing = self.class.parse(file.read, path)
+          rewrite(file, envelope(existing, coverage))
+        end
+        true
+      end
+
+      # Truncates any leftover tail from a previously larger document.
+      def rewrite(file, payload)
+        file.rewind
+        file.write(JSON.generate(payload))
+        file.truncate(file.pos)
+      end
+
+      # Raises `Error` for anything that is not a production coverage file,
+      # naming the path: misreading an arbitrary JSON file as empty coverage
+      # would quietly report every line dead.
+      def self.read(path)
+        parse(File.read(path), path)
+      end
+
+      # @api private -- shared by `read` and `store`'s read-modify-write. An
+      # empty or missing file is a fresh store. JSON answers plain hashes,
+      # arrays, and scalars, never a subclass of one, so the shape checks ask
+      # about the class itself.
+      def self.parse(content, path)
+        return {"coverage" => {}, "last_seen" => {}, "started_at" => nil} if content.match?(/\A\s*\z/)
+
+        inner = envelope_of(JSON.parse(content), path)
+        inner["coverage"] = {} unless inner["coverage"].instance_of?(Hash)
+        inner["last_seen"] = {} unless inner["last_seen"].instance_of?(Hash)
+        inner
+      rescue JSON::ParserError => e
+        # One line of the parser's complaint, which for some inputs quotes the
+        # document back and runs long.
+        raise Error, "#{path} is not valid JSON (#{e.message.lines.first.to_s.rstrip})"
+      end
+
+      # The refusal is what keeps an arbitrary JSON file from being misread as
+      # empty coverage.
+      def self.envelope_of(document, path)
+        inner = document[ENVELOPE] if document.instance_of?(Hash)
+        raise Error, "#{path} is not a SimpleCov production coverage file" unless inner.instance_of?(Hash)
+
+        inner
+      end
+
+      private
+
+      # Both halves of the read-modify-write happen through the one handle, so
+      # processes sharing the file take turns rather than overwriting each
+      # other. The open flags are summed, which for disjoint bits is the same
+      # number OR would build and leaves no spelling of the combination
+      # without a witness.
+      def with_exclusive_lock
+        open_file(path, File::RDWR + File::CREAT, 0o644) do |file|
+          file.flock(File::LOCK_EX)
+          yield file
+        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 store path as a command.
+      def open_file(name, mode, perm, &)
+        File.open(name, mode, perm, &)
+      end
+
+      def merge(existing, incoming)
+        incoming.each_with_object(existing) do |(file, lines), merged|
+          merged[file] = ((merged[file] || []) | lines).sort
+        end
+      end
+
+      def envelope(existing, incoming)
+        now = Time.now.utc.iso8601
+        {
+          ENVELOPE => {
+            "format_version" => FORMAT_VERSION,
+            "started_at" => existing["started_at"] || now,
+            "updated_at" => now,
+            "coverage" => merge(existing.fetch("coverage"), incoming).sort.to_h,
+            "last_seen" => existing.fetch("last_seen").merge(incoming.transform_values { now }).sort.to_h
+          }
+        }
+      end
+    end
+  end
+end

data/lib/simplecov/production.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "coverage"
+require_relative "production/error"
+
+#
+# Production coverage mode (#1271). Deliberately loadable on its own:
+# `require "simplecov/production"` pulls in none of the reporting machinery,
+# because a production process wants a measurement tap and nothing else.
+# Nothing here runs unless `SimpleCov::Production.start` is called explicitly.
+#
+module SimpleCov
+  module Production
+    class << self
+      # Answers false, with a warning naming why, when it safely declines
+      # (already running, another Coverage owner such as a test suite, or a
+      # runtime without oneshot lines). Configuration mistakes raise `Error`
+      # instead: a typo'd interval should fail deployment, not quietly measure
+      # wrong.
+      #
+      # In a forking server, call this from the worker-boot hook (Puma's
+      # `on_worker_boot`, Unicorn's `after_fork`): the flush thread does not
+      # survive a fork, and `start` in the child picks the inherited
+      # measurement back up.
+      def start(root: Dir.pwd, sink: nil, flush_interval: 60, flush_jitter: nil, sample_rate: 1.0,
+        max_buffered_lines: 1_000_000)
+        validate!(flush_interval, flush_jitter, sample_rate, max_buffered_lines)
+        return warn_decline("SimpleCov::Production is already running") if running?
+        return false unless claim_coverage
+
+        configure(root, sink, flush_interval: flush_interval, flush_jitter: flush_jitter,
+          sample_rate: sample_rate, max_buffered_lines: max_buffered_lines)
+        @running = true
+        @pid = Process.pid
+        install_at_exit
+        spawn_flush_thread
+        true
+      end
+
+      # Both are small Integers, so identity settles it: a measurement belongs to
+      # the process that started it and to no other.
+      def running?
+        !!@running && @pid.equal?(Process.pid)
+      end
+
+      # Called by the flush thread every interval; public so a deploy hook (or a
+      # signal handler) can force one. An empty delta counts as accepted.
+      def flush
+        return false unless running?
+
+        @mutex.synchronize do
+          pull_pending
+          push_pending
+        end
+      end
+
+      def stop
+        return false unless running?
+
+        @running = false
+        wake_flush_thread
+        @thread&.join
+        @mutex.synchronize do
+          pull_pending
+          push_pending
+          Coverage.result(stop: true, clear: true)
+        end
+        true
+      end
+
+      # @api private -- clears module state between tests. The at_exit
+      # registration flag survives on purpose: one hook per process.
+      def reset!
+        @running = false
+        wake_flush_thread if @thread
+        @thread&.join
+        @thread = nil
+        @pending = {}
+        @pid = nil
+        @started_coverage = false
+      end
+
+      private
+
+      def validate!(flush_interval, flush_jitter, sample_rate, max_buffered_lines)
+        raise Error, "flush_interval must be a positive number of seconds" unless flush_interval.positive?
+
+        validate_jitter!(flush_jitter)
+        raise Error, "sample_rate must be within (0, 1]" unless sample_rate.positive? && sample_rate <= 1
+        raise Error, "max_buffered_lines must be positive" unless max_buffered_lines.positive?
+        return unless sample_rate < 1 && !Coverage.respond_to?(:suspend)
+
+        raise Error, "sample_rate below 1.0 needs Coverage.suspend, which this Ruby does not provide"
+      end
+
+      def validate_jitter!(flush_jitter)
+        return if flush_jitter.nil? || (flush_jitter.is_a?(Numeric) && flush_jitter >= 0)
+
+        raise Error, "flush_jitter must be a non-negative number of seconds"
+      end
+
+      # A running Coverage belongs to someone else, unless this very module
+      # started it before a fork, in which case the child inherits the
+      # measurement and only needs its own flush thread.
+      def claim_coverage
+        if Coverage.running?
+          return true if @started_coverage && @pid && !@pid.equal?(Process.pid)
+
+          return warn_decline("Coverage is already running (a test suite or another tool owns it)")
+        end
+        return warn_decline("this runtime has no oneshot lines support") unless oneshot_supported?
+
+        Coverage.start(oneshot_lines: true)
+        @started_coverage = true
+      end
+
+      def oneshot_supported?
+        !Coverage.respond_to?(:supported?) || Coverage.supported?(:oneshot_lines)
+      end
+
+      def configure(root, sink, flush_interval:, flush_jitter:, sample_rate:, max_buffered_lines:)
+        @root_prefix = File.expand_path(root) + File::SEPARATOR
+        @sink = sink || default_sink(root)
+        @flush_interval = flush_interval
+        @flush_jitter = flush_jitter || (flush_interval / 10.0)
+        @sample_rate = sample_rate
+        @max_buffered_lines = max_buffered_lines
+        @pending = {} #: Hash[String, Set[Integer]]
+        @measuring = true
+        @mutex = Mutex.new
+        @waiter = ConditionVariable.new
+      end
+
+      def default_sink(root)
+        FileSink.new(path: File.join(root, "tmp", "simplecov", "production.json"))
+      end
+
+      def spawn_flush_thread
+        thread = Thread.new { flush_loop }
+        thread.name = "SimpleCov::Production flusher"
+        @thread = thread
+      end
+
+      # The condition variable rather than a bare sleep is what lets `stop`
+      # return promptly instead of waiting out a long interval.
+      def flush_loop
+        @mutex.synchronize do
+          while @running
+            @waiter.wait(@mutex, interval_with_jitter)
+            cycle if @running
+          end
+        end
+      end
+
+      # A fresh share is drawn per wait: a fleet of workers booted together
+      # would otherwise contend on the shared sink at the same instant every
+      # interval, forever.
+      def interval_with_jitter
+        @flush_interval + (rand * @flush_jitter)
+      end
+
+      def wake_flush_thread
+        @mutex.synchronize { @waiter.signal }
+      end
+
+      def cycle
+        resample
+        pull_pending
+        push_pending
+      end
+
+      # Duty-cycle sampling: with `sample_rate` 0.25, roughly one interval in
+      # four measures and the rest are suspended, capping steady-state overhead
+      # while every line still gets its chance over time.
+      def resample
+        return unless @sample_rate < 1
+
+        wanted = rand < @sample_rate
+        if wanted && !@measuring
+          Coverage.resume
+        elsif !wanted && @measuring
+          Coverage.suspend
+        end
+        @measuring = wanted
+      end
+
+      # Clearing on read means a line executed again later re-reports, which is
+      # what lets a dropped buffer heal for still-hot code.
+      def pull_pending
+        Coverage.result(stop: false, clear: true).each do |path, data|
+          lines = data[:oneshot_lines]
+          next if lines.nil? || lines.empty?
+
+          relative = relativize(path)
+          next unless relative
+
+          (@pending[relative] ||= Set.new).merge(lines)
+        end
+      end
+
+      # On failure the buffer is kept for the next interval, bounded by the
+      # ceiling so a long outage cannot grow memory without limit.
+      def push_pending
+        return true if @pending.empty?
+
+        @sink.store(@pending.transform_values(&:sort))
+        @pending.clear
+        true
+      rescue => e
+        warn "[SimpleCov::Production] flush failed (#{e.class}: #{e}); retrying next interval"
+        enforce_ceiling
+        false
+      end
+
+      # Oneshot's re-reporting is what makes dropping safe-ish: lines still being
+      # executed report again after the drop, and only code that ran during the
+      # outage and never again is lost.
+      def enforce_ceiling
+        return if @pending.sum { |_path, lines| lines.size } <= @max_buffered_lines
+
+        @pending.clear
+        warn "[SimpleCov::Production] buffer ceiling (#{@max_buffered_lines} lines) exceeded " \
+             "while the sink was unreachable; dropping buffered coverage"
+      end
+
+      def relativize(path)
+        return nil unless path.start_with?(@root_prefix)
+
+        path[@root_prefix.length..]
+      end
+
+      def warn_decline(reason)
+        warn "[SimpleCov::Production] not starting: #{reason}"
+        false
+      end
+
+      def install_at_exit
+        return if @at_exit_installed
+
+        @at_exit_installed = true
+        at_exit do
+          stop
+        end
+      end
+    end
+  end
+end
+
+require_relative "production/file_sink"

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,19 @@
 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 "Channels", "app/channels"
+  group "Controllers", "app/controllers"
+  group "Helpers", "app/helpers"
+  group "Jobs", %w[app/jobs app/workers]
+  group "Libraries", "lib/"
+  group "Mailers", "app/mailers"
+  group "Models", "app/models"
+  group "Views", "app/views"
 
-  track_files "{app,lib}/**/*.rb"
+  @tracked_files = "{app,lib}/**/*.rb"
+
+  merge_subprocesses true
 end

data/lib/simplecov/profiles/root_filter.rb

@@ -1,10 +1,7 @@
 # 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
+  skip do |src|
+    src.filename !~ SimpleCov::UselessResultsRemover.root_regex
   end
 end