simplecov 1.1.1 → 1.2.0

data/lib/simplecov.rb

@@ -1,17 +1,13 @@
 # frozen_string_literal: true
 
-#
-# Code coverage for ruby. Please check out README for a full introduction.
-#
+require "forwardable"
+require_relative "simplecov/configuration_error"
+require_relative "simplecov/current_run"
+
 module SimpleCov
-  # Raised when a user's configuration is internally inconsistent — e.g.
-  # every coverage criterion has been disabled.
-  class ConfigurationError < StandardError; end
-
-  # Maps SimpleCov's criterion names to the keys `Coverage.start` expects.
-  # Lives at module scope (not inside `class << self`) so it can be
-  # declared in the RBS signatures; lexical scoping keeps every existing
-  # reference inside the singleton class working.
+  # At module scope rather than inside `class << self` so it can be declared in
+  # the RBS signatures; lexical scoping keeps references inside the singleton
+  # class working.
   CRITERION_TO_RUBY_COVERAGE = {
     branch: :branches,
     line: :lines,
@@ -19,68 +15,38 @@ module SimpleCov
     oneshot_line: :oneshot_lines
   }.freeze
 
-  class << self
-    attr_accessor :pid
-    # When this process started tracking coverage. Captured by SimpleCov.start
-    # so JSONFormatter can detect when an existing coverage.json was written
-    # by a sibling process running concurrently.
-    attr_accessor :process_start_time
-
-    # A monotonically increasing serial the parent assigns to each forked
-    # subprocess (see SimpleCov::ProcessForkHook). The default `at_fork`
-    # builds the worker's command_name from this rather than the OS pid:
-    # the serial sequence is the same from one run to the next, so a re-run
-    # overwrites the previous run's resultset entries instead of writing
-    # uniquely-named ones that pile up until merge_timeout. See issue #1171.
-    def subprocess_serial
-      @subprocess_serial ||= 0
-    end
+  # `SingleForwardable` rather than `Forwardable` on the singleton class,
+  # because RBS has no way to speak about the singleton class's own ancestors.
+  extend SingleForwardable
 
-    # @api private — bump the serial in the parent before a fork so the
-    # child inherits its own ordinal via copy-on-write.
-    def next_subprocess_serial!
-      @subprocess_serial = subprocess_serial + 1
-    end
+  def_delegators :current_run,
+    :pid, :pid=, :process_start_time, :process_start_time=,
+    :subprocess_serial, :next_subprocess_serial!,
+    :forked_subprocess?, :mark_forked_subprocess!,
+    :result?, :collating_result?
 
-    # @api private — true in a process that was forked while coverage was
-    # running (set by SimpleCov::ProcessForkHook in the child). Such a child
-    # stores its own slice but must not act as the final-result process: the
-    # process that forked it merges every slice and produces the report. Only
-    # consulted when no parallel-test adapter is active, since adapters answer
-    # `first_worker?` themselves. See issue #1171.
-    def forked_subprocess?
-      !!(defined?(@forked_subprocess) && @forked_subprocess)
+  class << self
+    def current_run
+      @current_run ||= CurrentRun.new
     end
 
-    # @api private — marked in the child immediately after a fork.
-    def mark_forked_subprocess!
-      @forked_subprocess = true
-    end
-    # Should we take care of at_exit behavior or something else? Used by the
-    # minitest plugin. See lib/minitest/simplecov_plugin.rb.
+    # @api private
+    attr_writer :current_run
+
     attr_accessor :external_at_exit
 
     # `:oneshot_line` data is folded into the `:line` bucket of
-    # `coverage_statistics` by `ResultAdapter`, so use `:line` to look
-    # up stats for either criterion.
+    # `coverage_statistics` by `ResultAdapter`. The cast is steep's: it narrows
+    # a union on `==` but not on `equal?`.
     def coverage_statistics_key(criterion)
-      criterion == :oneshot_line ? :line : criterion
+      criterion.equal?(:oneshot_line) ? :line : _ = criterion
     end
 
-    # Coerce to a proper boolean so rspec-mocks 4's predicate matcher
-    # (`expect(...).not_to be_external_at_exit`) accepts the result.
+    # Coerced so rspec-mocks 4's predicate matcher accepts the result.
     def external_at_exit?
       !!@external_at_exit
     end
 
-    #
-    # Sets up SimpleCov to run against your project. See README for
-    # the full DSL, or:
-    #
-    #     SimpleCov.start
-    #     SimpleCov.start 'rails'                # using a profile
-    #     SimpleCov.start { add_filter 'test' }  # with a config block
-    #
     def start(profile = nil, &)
       warn_about_start_in_dot_simplecov if @autoloading_dot_simplecov
 
@@ -90,15 +56,7 @@ module SimpleCov
     end
 
     # @api private
-    #
-    # Mark the duration of a `.simplecov` auto-load so any `SimpleCov.start`
-    # call inside the file can warn about the impending migration to a
-    # config-only file. Tracking still begins for backward compatibility;
-    # the warning is the cue to move `SimpleCov.start` into a test helper.
-    # See #581.
     def with_dot_simplecov_autoload
-      # Read in the ensure clause, where flow analysis cannot see the
-      # assignment above; anchor the type here.
       previous = @autoloading_dot_simplecov # : bool?
       @autoloading_dot_simplecov = true
       yield
@@ -119,62 +77,39 @@ module SimpleCov
            "See https://github.com/simplecov-ruby/simplecov/issues/581."
     end
 
-    #
-    # Install the at_exit hook that formats results and runs exit-code
-    # checks. `SimpleCov.start` calls this automatically. Idempotent —
-    # safe to call multiple times. Callers that drive the formatting
-    # pipeline themselves (e.g., dogfood test setups) can skip it by
-    # using `start_tracking` directly instead of `start`.
-    #
     def install_at_exit_hook
       return if @at_exit_hook_installed
 
       @at_exit_hook_installed = true
-      # Never defer in a forked child: Minitest pins its after_run at_exit
-      # to the pid that armed autorun, so the deferral target can't fire
-      # there and the child's resultset would be silently dropped. See
-      # issue #1227.
+      # Never defer in a forked child: Minitest pins its after_run at_exit to
+      # the pid that armed autorun, so the deferral target can't fire there and
+      # the child's resultset would be silently dropped (#1227).
       defer_to_minitest_after_run if minitest_autorun_pending? && !forked_subprocess?
       Kernel.at_exit do
-        next if SimpleCov.external_at_exit?
+        next if external_at_exit?
 
-        SimpleCov.at_exit_behavior
+        at_exit_behavior
       end
     end
 
-    #
-    # Begin coverage tracking without applying configuration. Pairs with
-    # `SimpleCov.configure { ... }` for callers that want to separate
-    # the two — for example a dogfood test that has already started
-    # `Coverage` itself before requiring simplecov, but still wants the
-    # process_start_time / pid / fork-hook bookkeeping.
-    #
     def start_tracking
       require "coverage"
       warn_if_jruby_full_trace_disabled
       validate_coverage_criteria!
-      # simplecov:disable — fork-hook is enabled via SimpleCov.enable_for_subprocesses, off by default
-      require_relative "simplecov/process" if SimpleCov.enabled_for_subprocesses? &&
-                                              ::Process.respond_to?(:_fork)
-      # simplecov:enable
+      require_relative "simplecov/process" if enabled_for_subprocesses? && Process.respond_to?(:_fork)
 
-      # Select the parallel adapter and generate identities before any forks.
-      SimpleCov::RunIdentity.prepare
+      # Must happen before any forks.
+      RunIdentity.prepare
 
-      @result = nil
+      self.current_run = current_run.successor
       self.pid = Process.pid
       self.process_start_time = Time.now
 
       start_coverage_measurement
     end
 
-  private
+    private
 
-    #
-    # Trigger Coverage.start with the configured criteria. Every supported
-    # runtime (CRuby >= 3.2, JRuby >= 10, TruffleRuby >= 22) accepts the
-    # criteria-hash form, so no compatibility fallback is needed.
-    #
     def start_coverage_measurement
       start_arguments = coverage_criteria.to_h do |criterion|
         [CRITERION_TO_RUBY_COVERAGE.fetch(criterion), true]
@@ -183,15 +118,14 @@ module SimpleCov
       start_arguments[:eval] = true if coverage_for_eval_enabled?
 
       Coverage.start(**start_arguments) unless Coverage.running?
+      start_test_tracking
     end
 
-    # `Rake::TestTask` runs `ruby -e 'require "minitest/autorun"; ...'`,
-    # which means Minitest's at_exit registers before SimpleCov's. Since
-    # at_exit fires LIFO, SimpleCov's hook would otherwise run *before*
-    # Minitest gets a chance to invoke the tests — and format an empty
-    # resultset. When we can see that Minitest is loaded and its autorun
-    # is armed, route the report through `Minitest.after_run` instead,
-    # which fires after the suite completes. See issues #1099 and #1112.
+    # `Rake::TestTask` runs `ruby -e 'require "minitest/autorun"; ...'`, so
+    # Minitest's at_exit registers before SimpleCov's and, at_exit being LIFO,
+    # SimpleCov's would format an empty resultset before the tests ever run.
+    # Routing through `Minitest.after_run` instead fires after the suite
+    # completes (#1099, #1112).
     def minitest_autorun_pending?
       return false unless defined?(Minitest) && Minitest.respond_to?(:after_run)
       return false unless Minitest.class_variable_defined?(:@@installed_at_exit)
@@ -201,19 +135,21 @@ module SimpleCov
 
     def defer_to_minitest_after_run
       self.external_at_exit = true
-      Minitest.after_run { SimpleCov.at_exit_behavior }
+      Minitest.after_run { at_exit_behavior }
     end
 
     # JRuby coverage data is unreliable unless full-trace mode is enabled.
     # @see https://github.com/jruby/jruby/issues/1196
     # @see https://github.com/simplecov-ruby/simplecov/issues/420
     # @see https://github.com/simplecov-ruby/simplecov/issues/86
+    # mutant:disable — every line below the guard is JRuby-only, and no
+    # example running on the engine this suite runs on can reach one.
     def warn_if_jruby_full_trace_disabled
       return unless defined?(JRUBY_VERSION) && defined?(JRuby) # simplecov:disable — JRuby-only branch
 
       # simplecov:disable — JRuby-only branches; unreachable from CRuby
-      # `org` is JRuby's Java-package entry point; it does not exist on
-      # CRuby, so no RBS declaration can be truthful here.
+      # `org` is JRuby's Java-package entry point, absent on CRuby, so no RBS
+      # declaration can be truthful here.
       return if org.jruby.RubyInstanceConfig.FULL_TRACE_ENABLED # steep:ignore NoMethod
 
       warn 'Coverage may be inaccurate; set the "--debug" command line option, ' \
@@ -224,8 +160,6 @@ module SimpleCov
   end
 end
 
-# requires are down here for a load order reason I'm not sure what it is about
-require "forwardable"
 require_relative "simplecov/color"
 require_relative "simplecov/deprecation"
 require_relative "simplecov/group_names"
@@ -244,8 +178,18 @@ require_relative "simplecov/result"
 require_relative "simplecov/filter"
 require_relative "simplecov/formatter"
 require_relative "simplecov/last_run"
+require_relative "simplecov/history"
 require_relative "simplecov/report_stamp"
+require_relative "simplecov/baseline"
 require_relative "simplecov/lines_classifier"
+require_relative "simplecov/context_map"
+require_relative "simplecov/context_map/union"
+require_relative "simplecov/test_tracker/constant_watch"
+require_relative "simplecov/test_tracker/delta"
+require_relative "simplecov/test_tracker"
+require_relative "simplecov/test_tracker/framework_hooks"
+require_relative "simplecov/test_tracker/accessors"
+SimpleCov.extend SimpleCov::TestTracker::Accessors
 require_relative "simplecov/result_merger"
 require_relative "simplecov/parallel_result_merger"
 require_relative "simplecov/parallel_adapters"
@@ -264,12 +208,12 @@ require_relative "simplecov/combine/results_combiner"
 require_relative "simplecov/useless_results_remover"
 require_relative "simplecov/simulate_coverage"
 require_relative "simplecov/unloaded_file_injector"
+require_relative "simplecov/view_coverage"
 require_relative "simplecov/result_processing"
 require_relative "simplecov/exit_handling"
 require_relative "simplecov/report_deferral"
 require_relative "simplecov/parallel_coordination"
 
-# Load default config
 # simplecov:disable — env-var never set in the dogfooded test process
 # (sandbox fixture subprocesses set it via simplecov/no_defaults)
 require_relative "simplecov/defaults" unless ENV["SIMPLECOV_NO_DEFAULTS"]

data/lib/simplecov_json_formatter.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
 # Backward-compatibility shim: simplecov_json_formatter is now part of simplecov.
+
 require_relative "simplecov/formatter/json_formatter"

data/man/simplecov.1

@@ -0,0 +1,349 @@
+.TH SIMPLECOV 1 "2026-08-24" "simplecov 1.2.0" "User Commands"
+.SH NAME
+simplecov \- coverage reports and questions from the terminal
+.SH SYNOPSIS
+.B simplecov
+.I command
+.RI [ options ]
+.SH DESCRIPTION
+The simplecov command reads the JSON report a SimpleCov run writes next to its
+HTML report (coverage/coverage.json by default) and answers coverage questions
+from the terminal. Default paths follow SimpleCov.coverage_dir from a
+project's .simplecov when one is present. Every command answers \-\-help with
+its own usage.
+.SH COMMANDS
+.TP
+.B run <command...>
+Execute <command> with SimpleCov pre\-loaded
+.TP
+.B coverage <path>
+Print coverage stats for the given file
+.TP
+.B show <path>
+Print the file's source annotated with hit counts and misses
+.TP
+.B report
+Print the overall summary and group totals
+.TP
+.B status
+Report freshness: age, commit distance, recorded tests
+.TP
+.B history
+Print the recorded coverage trend, a sparkline per criterion
+.TP
+.B badge
+Render the coverage percent as an SVG badge
+.TP
+.B uncovered
+List the lowest\-coverage files
+.TP
+.B tests [<path>[:<line>]]
+List recorded tests for a file or line (needs track_tests)
+.TP
+.B affected
+List test files touching code changed since a git ref (needs track_tests)
+.TP
+.B merge <files...>
+Merge multiple .resultset.json files
+.TP
+.B diff <baseline>
+Show per\-file coverage delta vs baseline
+.TP
+.B patch
+Show coverage of the lines a change touched
+.TP
+.B ratchet
+Rewrite the per\-file coverage baseline, only ever tightening
+.TP
+.B dead\-code
+Cross production coverage with the report to find dead code
+.TP
+.B open
+Open the HTML report in the default browser
+.TP
+.B serve
+Serve the coverage report over HTTP
+.TP
+.B watch <command...>
+Re\-run <command> on save and live\-reload the served report
+.TP
+.B clean
+Remove the coverage report directory
+.TP
+.B completions <shell>
+Emit the completion script for fish, bash, or zsh
+.TP
+.B help
+Show this message
+.TP
+.B version
+Print the version (also \-\-version / \-v)
+.SH OPTIONS
+.SS coverage
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-json
+Print the file's JSON entry verbatim
+.SS show
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-uncovered\-only
+Print only <path>:<ranges> of the missed lines
+.TP
+.B \-\-json
+Emit path, missed lines, per\-line hits, and markers as JSON
+.SS report
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-json
+Emit totals and group sections as JSON
+.SS status
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-json
+Emit the freshness facts as a JSON object
+.SS history
+.TP
+.B \-\-input PATH
+Read from PATH instead of the coverage directory's .history.json
+.TP
+.B \-\-file PATH
+Follow one file's trajectory instead of the totals
+.TP
+.B \-\-json
+Emit the entries (or the file's trajectory) as JSON
+.TP
+.B \-\-no\-color
+Disable colorized deltas (also honors NO_COLOR / FORCE_COLOR env)
+.SS badge
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-output PATH
+Write the badge to PATH instead of stdout
+.TP
+.B \-\-criterion C
+line, branch, or method (default: line)
+.TP
+.B \-\-label TEXT
+The badge's left\-side text (default: the criterion's, like "line coverage")
+.SS uncovered
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-threshold N
+Only show files below N% coverage
+.TP
+.B \-\-top N
+Show at most N files (default: 10)
+.TP
+.B \-\-criterion C
+line, branch, or method (default: line)
+.TP
+.B \-\-missing
+Append the missed line ranges to each row
+.TP
+.B \-\-annotate github
+Emit ::warning workflow commands instead of rows
+.TP
+.B \-\-json
+Emit results as a JSON array (for CI)
+.SS tests
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-redundant
+List only tests whose covered lines other tests also cover
+.TP
+.B \-\-json
+Emit the test ids as a JSON array
+.SS affected
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-base REF
+Diff against the merge base of REF and HEAD (default: origin's HEAD, else
+main)
+.TP
+.B \-\-run <command...>
+Run <command> (all args after \-\-run) with the selection appended, or bare on
+a full\-suite fallback, exiting with the command's status
+.TP
+.B \-\-json
+Emit {full_suite, triggers, tests} as a JSON object
+.SS merge
+.TP
+.B \-\-output PATH
+Write merged resultset to PATH (default: coverage/.resultset.json)
+.TP
+.B \-\-honor\-timeout
+Drop entries older than merge_timeout
+.TP
+.B \-\-dry\-run
+Print what would be written without writing
+.TP
+.B \-q, \-\-quiet
+Suppress the success status line
+.SS diff
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-fail\-on\-drop
+Exit non\-zero when any file's coverage dropped vs baseline (deletions don't
+count)
+.TP
+.B \-\-json
+Emit results as a JSON array (for CI)
+.TP
+.B \-\-threshold N
+Only show files whose absolute delta in any criterion is at least N%
+.SS patch
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-base REF
+Diff against the merge\-base of REF for the touched lines (default: origin's
+HEAD, else main, or in CI the PR's target branch)
+.TP
+.B \-\-minimum N
+Exit non\-zero when patch coverage on any measured criterion is below N%
+.TP
+.B \-\-find\-renames
+Follow a renamed file instead of counting the moved file as all\-new
+.TP
+.B \-\-json
+Emit results as a JSON array (for CI)
+.SS ratchet
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-baseline PATH
+The baseline file to rewrite (default: the project's `baseline_file`,
+\&.simplecov_baseline.yml)
+.TP
+.B \-\-init
+Regenerate from scratch: add entries for new files and reset every floor to
+the current state
+.TP
+.B \-\-dry\-run
+Print what would change without writing
+.TP
+.B \-\-json
+Emit the summary (tightened / pruned / regressed entries) as JSON
+.SS dead-code
+.TP
+.B \-\-input PATH
+Read from PATH instead of coverage/coverage.json
+.TP
+.B \-\-no\-color
+Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+.TP
+.B \-\-production PATH
+The production coverage file a SimpleCov::Production sink wrote (default: the
+project's `production_coverage`, required when none is configured)
+.TP
+.B \-\-untested\-in\-production
+Print code production runs that no test covers, instead of the dead rows
+.TP
+.B \-\-json
+Emit every category (dead, possibly dead, untested in production) as JSON
+.SS open
+.TP
+.B \-\-report PATH
+Open PATH instead of coverage/index.html
+.SS serve
+.TP
+.B \-\-port N
+Bind to port N (default: random open port)
+.TP
+.B \-\-host HOST
+Bind to HOST (default: 127.0.0.1)
+.SS watch
+.TP
+.B \-\-port N
+Bind to port N (default: random open port)
+.TP
+.B \-\-host HOST
+Bind to HOST (default: 127.0.0.1)
+.TP
+.B \-\-interval SECONDS
+Poll the tracked files this often (default: 0.5)
+.TP
+.B \-\-open
+Open the served report in the default browser
+.SS clean
+.TP
+.B \-\-dry\-run
+Print what would be removed without deleting
+.TP
+.B \-q, \-\-quiet
+Suppress status lines
+.SH ENVIRONMENT
+.TP
+.B NO_COLOR
+Disable colorized output. FORCE_COLOR forces it on, and \-\-no\-color beats
+both.
+.TP
+.B SIMPLECOV_MERGE_TIMEOUT
+Override merge_timeout in seconds. The watch command sets it for child runs so
+subset re\-runs keep merging into a whole report.
+.SH FILES
+.TP
+.B coverage/coverage.json
+The JSON report the read\-only commands consume. The bundled HTML formatter
+writes it alongside index.html.
+.TP
+.B coverage/.resultset.json
+The merged raw resultset the merge command reads and writes.
+.TP
+.B .simplecov
+Project configuration. Its SimpleCov.coverage_dir setting moves every default
+path above.
+.SH SEE ALSO
+Full documentation with examples for every command lives in docs/CLI.md in the
+source tree and at https://github.com/simplecov\-ruby/simplecov