simplecov 1.1.0 → 1.2.0

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 (Ruby 3.2 or later)"
+      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/rails.rb

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

data/lib/simplecov/profiles/root_filter.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
 SimpleCov.profiles.define "root_filter" do
-  # Exclude all files outside of simplecov root. Shares the regex with
-  # SimpleCov::UselessResultsRemover so the root-prefix logic lives in one
-  # place; this profile is the user-facing entry point that tools like
-  # `SimpleCov.filtered` apply.
   skip do |src|
     src.filename !~ SimpleCov::UselessResultsRemover.root_regex
   end

data/lib/simplecov/profiles/strict.rb

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

data/lib/simplecov/profiles.rb

@@ -1,63 +1,41 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  #
-  # Profiles are SimpleCov configuration procs that can be easily
-  # loaded using SimpleCov.start :rails and defined using
-  #   SimpleCov.profiles.define :foo do
-  #     # SimpleCov configuration here, same as in  SimpleCov.configure
-  #   end
-  #
+  # Configuration procs loaded with `SimpleCov.start :rails` and defined with
+  # `SimpleCov.profiles.define`.
   class Profiles < Hash
-    #
-    # Define a SimpleCov profile:
-    #   SimpleCov.profiles.define 'rails' do
-    #     # Same as SimpleCov.configure do .. here
-    #   end
-    #
     def define(name, &blk)
       name = name.to_sym
-      raise SimpleCov::ConfigurationError, "SimpleCov Profile '#{name}' is already defined" unless self[name].nil?
+      raise ConfigurationError, "SimpleCov Profile '#{name}' is already defined" unless self[name].nil?
 
       self[name] = blk
     end
 
-    #
-    # Applies the profile of given name on SimpleCov.configure
-    #
     def load(name)
       SimpleCov.configure(&fetch_proc(name))
     end
 
-    #
-    # Returns the proc registered for the given profile name, autoloading
-    # bundled or plugin-gem profiles on first lookup. Raises if the profile
-    # cannot be located.
-    #
-    # Lookup order:
-    #   1. already registered via #define
-    #   2. require "simplecov/profiles/<name>"   (bundled profiles)
-    #   3. require "simplecov-profile-<name>"    (third-party plugin gems)
-    #
+    # Lookup order: already registered via #define, then
+    # `require "simplecov/profiles/<name>"` for the bundled profiles, then
+    # `require "simplecov-profile-<name>"` for third-party plugin gems.
     def fetch_proc(name)
       name = name.to_sym
       autoload_profile(name) unless key?(name)
-      return self[name] if key?(name)
+      return fetch(name) if key?(name)
 
-      raise SimpleCov::ConfigurationError, "Could not find SimpleCov Profile called '#{name}'"
+      raise ConfigurationError, "Could not find SimpleCov Profile called '#{name}'"
     end
 
-  private
+    private
 
     def autoload_profile(name)
       require "simplecov/profiles/#{name}"
     rescue LoadError
       begin
-        # simplecov:disable — third-party gem fallback (no such gem in test env)
         require "simplecov-profile-#{name}"
-        # simplecov:enable
       rescue LoadError
-        # fall through; #fetch_proc raises the user-facing error
+        # Neither a bundled profile nor a plugin gem; `fetch_proc` raises the
+        # user-facing error.
       end
     end
   end

data/lib/simplecov/report_deferral.rb

@@ -1,15 +1,12 @@
 # frozen_string_literal: true
 
-# The clobber-prevention backstop: an empty process stands down instead
-# of formatting over a fresher report a sibling produced. Split from
-# exit_handling.rb, which orchestrates the at_exit flow that consults
-# this. See issue #581.
+# The clobber-prevention backstop: an empty process stands down instead of
+# formatting over a fresher report a sibling produced. Typically fires when
+# `SimpleCov.start` ran in a parent process that shelled out to the test runner
+# (#581).
+
 module SimpleCov
   class << self
-    # Returns true when our process has no coverage data to contribute
-    # (after the resultset merge) and a newer report already exists on
-    # disk. Typically fires when `SimpleCov.start` ran in a parent
-    # process that shelled out to the test runner. See issue #581.
     def defer_to_existing_report?
       return false unless existing_report_newer_than_us?
 
@@ -19,15 +16,14 @@ module SimpleCov
       empty
     end
 
-    # `.last_run.json` only exists after fully successful runs, so alone
-    # it left the backstop inert when the child run failed — the case
-    # where clobbering its report hurts most. The report stamp is
-    # touched by every formatting process regardless of exit status. The
-    # rescue covers a file vanishing mid-at_exit (`rm -rf coverage`).
+    # `.last_run.json` only exists after fully successful runs, so alone it left
+    # the backstop inert when the child run failed, the case where clobbering its
+    # report hurts most. The report stamp is touched by every formatting process
+    # regardless of exit status. The rescue covers a file vanishing mid-at_exit.
     def existing_report_newer_than_us?
       return false unless process_start_time
 
-      [SimpleCov::LastRun.last_run_path, SimpleCov::ReportStamp.path].any? do |path|
+      [LastRun.last_run_path, ReportStamp.path].any? do |path|
         File.mtime(path) > process_start_time
       rescue SystemCallError
         false
@@ -37,7 +33,7 @@ module SimpleCov
     def warn_about_deferred_report
       return unless print_errors
 
-      ExitCodes.print_error SimpleCov::Color.colorize(
+      ExitCodes.print_error Color.colorize(
         "Skipping SimpleCov report — this process tracked no application code and a newer " \
         "report already exists at #{coverage_path}. This usually means SimpleCov.start ran in a " \
         "parent process (e.g. a Rakefile or Rails' Bundler.require) that shelled out to the test " \

data/lib/simplecov/report_stamp.rb

@@ -3,24 +3,21 @@
 require "fileutils"
 
 module SimpleCov
-  # Touches coverage/.report_stamp whenever a report is formatted, no
-  # matter how the run ends. The clobber-prevention backstop
-  # (`SimpleCov.defer_to_existing_report?`) needs an on-disk signal that
-  # a fresher report exists, and `.last_run.json` can't be it alone:
-  # that file is only written after fully successful runs, which left
-  # the backstop inert exactly when the child run failed and its report
-  # mattered most.
+  # Touches coverage/.report_stamp whenever a report is formatted, no matter how
+  # the run ends. The clobber-prevention backstop needs an on-disk signal that a
+  # fresher report exists, and `.last_run.json` can't be it alone: that file is
+  # only written after fully successful runs.
   module ReportStamp
     class << self
       def path
         File.join(SimpleCov.coverage_path, ".report_stamp")
       end
 
+      # A read-only or vanished coverage dir must not crash reporting; the stamp
+      # only powers the deferral heuristic.
       def touch
         FileUtils.touch(path)
       rescue SystemCallError
-        # A read-only or vanished coverage dir must not crash reporting;
-        # the stamp only powers the deferral heuristic.
         nil
       end
     end

data/lib/simplecov/result/filter_config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class Result
+    # The filter and grouping configuration a Result applies to its source files
+    # after building them. Each field defaults to the SimpleCov singleton's
+    # configuration, so ordinary callers never construct one; tests pass a custom
+    # instance to opt out of the project's filters or groups.
+    class FilterConfig
+      attr_reader :filters, :cover_filters, :groups
+
+      def initialize(filters: SimpleCov.filters, cover_filters: SimpleCov.cover_filters, groups: SimpleCov.groups)
+        @filters = filters
+        @cover_filters = cover_filters
+        @groups = groups
+      end
+    end
+  end
+end