simplecov 1.1.1 → 1.3.0

data/sig/simplecov.rbs

@@ -1,20 +1,11 @@
-# Code coverage for Ruby. See the README for a full introduction.
 module SimpleCov
-  # A coverage criterion that can be enabled, measured, and reported.
   type criterion = :line | :branch | :method
   type line_coverage_alternatives = Hash[criterion | :oneshot_line, :line | :oneshot_line]
 
-  # Anything accepted by `skip` / `group` (and the deprecated
-  # `add_filter` / `add_group`): a path-segment substring, a Regexp, a
-  # prebuilt Filter, a predicate on the SourceFile, or an Array of those.
   type filter_arg = String | Regexp | Filter[untyped] | ^(SourceFile source_file) -> boolish | Array[filter_arg]
 
-  # Anything accepted by `cover`: a shell-glob String, Regexp, Proc,
-  # prebuilt Filter, or an Array of those.
   type cover_arg = String | Regexp | ^(SourceFile source_file) -> boolish | Filter[untyped] | Array[cover_arg]
 
-  # Raised when a user's configuration is internally inconsistent — e.g.
-  # every coverage criterion has been disabled.
   class ConfigurationError < StandardError
   end
 
@@ -26,36 +17,40 @@ module SimpleCov
     def self?.validate!: (Array[String] group_names) -> Array[String]
   end
 
-  # Maps SimpleCov's criterion names to the keys `Coverage.start` expects.
   CRITERION_TO_RUBY_COVERAGE: Hash[Symbol, Symbol]
 
   extend Configuration
+  extend SingleForwardable
 
-  self.@subprocess_serial: Integer?
-  self.@forked_subprocess: bool?
+  self.@current_run: CurrentRun?
   self.@autoloading_dot_simplecov: bool?
   self.@dot_simplecov_start_warned: bool?
   self.@at_exit_hook_installed: bool?
   self.@run_id: String?
   self.@worker_id: String?
 
+  def self.current_run: () -> CurrentRun
+
+  attr_writer self.current_run: CurrentRun?
+
   attr_accessor self.pid: Integer?
 
-  # When this process started tracking coverage.
   attr_accessor self.process_start_time: Time?
 
   def self.run_id: () -> String
 
   def self.worker_id: () -> String
 
-  # Should something external (e.g. the Minitest plugin) own the
-  # at_exit behavior instead of SimpleCov's own hook?
+  def self.track_test: [T] (String test_id) { () -> T } -> T
+
+  def self.test_tracker: () -> TestTracker?
+
+  def self.start_test_tracking: () -> void
+
   attr_accessor self.external_at_exit: bool?
 
   def self.external_at_exit?: () -> bool
 
-  # A monotonically increasing serial assigned to each forked
-  # subprocess; the default `at_fork` builds worker command names from it.
   def self.subprocess_serial: () -> Integer
 
   def self.next_subprocess_serial!: () -> Integer
@@ -64,38 +59,20 @@ module SimpleCov
 
   def self.mark_forked_subprocess!: () -> void
 
-  # `:oneshot_line` stats are folded into the `:line` bucket, so use
-  # the returned criterion to look up `coverage_statistics`.
   def self.coverage_statistics_key: ((criterion | :oneshot_line) criterion) -> criterion
 
-  # Sets up SimpleCov to run against your project:
-  #
-  #     SimpleCov.start
-  #     SimpleCov.start 'rails'           # using a profile
-  #     SimpleCov.start { skip 'test' }   # with a config block
-  #
   def self.start: (?(String | Symbol)? profile) ?{ () [self: singleton(SimpleCov)] -> void } -> void
 
   def self.with_dot_simplecov_autoload: [T] () { () -> T } -> T
 
   def self.warn_about_start_in_dot_simplecov: () -> void
 
-  # Install the at_exit hook that formats results and runs exit-code
-  # checks. Idempotent; `SimpleCov.start` calls this automatically.
   def self.install_at_exit_hook: () -> void
 
-  # Reset at_exit state a forked child inherits from its parent (a
-  # possibly consumed hook and a Minitest deferral pid-pinned to the
-  # parent), so the child re-arms a hook that fires at its own exit.
-  # Called by the fork hook; see issue #1227.
   def self.reset_inherited_at_exit_state!: () -> void
 
-  # Begin coverage tracking without applying configuration. Pairs with
-  # `SimpleCov.configure { ... }`.
   def self.start_tracking: () -> void
 
-  # Implementation details of `start` / `start_tracking` (private in Ruby;
-  # RBS cannot mark singleton methods private).
   def self.start_coverage_measurement: () -> void
 
   def self.minitest_autorun_pending?: () -> bool
@@ -105,90 +82,61 @@ module SimpleCov
   def self.warn_if_jruby_full_trace_disabled: () -> void
 end
 
-# ----- version -----
 
 module SimpleCov
   VERSION: String
 end
 
-# ----- result_processing -----
 
-# Result-building façade: turns the raw `Coverage.result` hash into a
-# `SimpleCov::Result`, applies filters and groups, drives merging, and
-# exposes the `collate` entry point.
 module SimpleCov
   self.@result: Result?
-  self.@collating_result: bool?
 
-  # Collate a series of resultset files into a single merged report. By
-  # default ignores `merge_timeout` so every listed resultset merges;
-  # pass `ignore_timeout: false` to honor it. `processes:` above 1 fans the
-  # merge out across that many forked workers, for an identical report;
-  # anything below 1 is taken as 1.
   def self.collate: (Array[String] result_filenames, ?(String | Symbol)? profile, ?processes: Integer, ?ignore_timeout: bool) ?{ () [self: singleton(SimpleCov)] -> void } -> void
 
-  # The result for the current coverage run, merged across test suites
-  # when merging is active. nil when no coverage was tracked.
   def self.result: () -> Result?
 
-  # The memoized result, or false/nil when it has not been computed yet.
+  def self.merge_own_slice: () -> untyped
+
+  def self.build_result: (untyped raw, untyped coverage, not_loaded: untyped, tracked: untyped, report: untyped) -> Result
+
   def self.result?: () -> (Result | false | nil)
 
   def self.collating_result?: () -> boolish
 
-  # Applies the configured filters to the given source files.
   def self.filtered: ((Array[SourceFile] | FileList) files) -> FileList
 
-  # Bin the given source files by group filter. Files matched by no
-  # group fall into the implicit "Ungrouped" bucket.
   def self.grouped: ((Array[SourceFile] | FileList) files, ?groups: Hash[String, Filter[untyped]]) -> Hash[String, FileList]
 
-  # Applies the profile of the given name to the configuration.
   def self.load_profile: ((String | Symbol) name) -> void
 
-  # Clear the cached result. Primarily useful in testing.
   def self.clear_result: () -> void
 
   def self.write_last_run: (Result result) -> void
 
-  # Round coverage down to two decimals.
   def self.round_coverage: (Numeric coverage) -> Numeric
 
-  # Implementation details of `collate` / `result` (private in Ruby;
-  # RBS cannot mark singleton methods private).
   def self.initial_setup: ((String | Symbol)? profile) ?{ () [self: singleton(SimpleCov)] -> void } -> void
 
   def self.grouped_file_set: (Hash[String, FileList] grouped) -> Set[SourceFile]
 
   def self.unloaded_file_discovery_globs: () -> Array[String]
 
-  # Every path this process was told to track, whether or not it loaded them.
-  # Recorded on the result (and from there into the resultset) so that a merge
-  # in another process can inject the ones nobody loaded without needing this
-  # process's `cover` / `track_files` configuration.
   def self.tracked_file_paths: () -> Array[String]
 
-  # Add simulated coverage for each of `candidate_paths` the result doesn't
-  # already carry, and return it with the set of paths added.
-  #
-  # @api private — the seam `SimpleCov::ResultMerger` injects through.
+  def self.warn_templates_tracked: (Array[String] templates) -> void
+
   def self.inject_unloaded_files: (Hash[String, untyped] result, Array[String] candidate_paths, ?synthesize: bool?, ?lines: bool?) -> [Hash[String, untyped], Set[String]]
 
-  # Build this process's slice of the coverage result. `standalone` is true
-  # when no merge step follows, which makes this the final result: it is the
-  # one that reports dropped source files, and the one that injects unloaded
-  # files. When a merge does follow, both jobs belong to the merged result.
   def self.collect_own_coverage: (standalone: bool) -> void
 
   def self.process_coverage_result: (report: bool, ?inject_unloaded: bool) -> void
 end
 
-# ----- configuration -----
 
-# Bundles the configuration options used for SimpleCov. All methods
-# defined here are usable from SimpleCov directly.
 module SimpleCov
   module Configuration
+    def __send__: (Symbol name, *untyped args) -> untyped
+
     @root: String
     @coverage_dir: String
     @coverage_dir_explicit: bool?
@@ -200,66 +148,43 @@ module SimpleCov
     @at_fork: Proc?
     @project_name: String?
 
-    # The root for the project, defaulting to the current working
-    # directory. Get, or set with `SimpleCov.root('/my/project/path')`.
     def root: (?String? root) -> String
 
-    # The name of the output and cache directory. Defaults to "coverage".
+    def root=: (String? root) -> String
+
     def coverage_dir: (?String? dir) -> String
 
-    # The full path to the output directory. By default `root` +
-    # `coverage_dir`; assign an absolute path to pin the destination
-    # regardless of later `root` / `coverage_dir` changes (see #716).
+    def coverage_dir=: (String? dir) -> String
+
     def coverage_path: (?String? path) -> String
 
-    # The name of the command (a.k.a. test suite) currently running.
-    # Auto-detected when not set explicitly.
+    def coverage_path=: (String path) -> untyped
+
     def command_name: (?String? name) -> String
 
-    # The hash of available profiles.
+    def command_name=: (String name) -> String
+
     def profiles: () -> Profiles
 
-    # Configure SimpleCov in a block. A zero-argument block runs with the
-    # configuration target as `self`; a parameterized block keeps its lexical
-    # `self` and receives the target explicitly:
-    #
-    #     SimpleCov.configure { skip "test" }
-    #     SimpleCov.configure { |config| config.skip caller_filter }
-    #
     def configure: () { () [self: self] -> untyped } -> self
                  | () { (self config) -> untyped } -> self
 
-    # Gets or sets the behavior that processes coverage results at
-    # process exit. The default stores/merges the current result and
-    # formats only from the final reporting process.
     def at_exit: () ?{ () -> void } -> Proc
 
-    # Whether SimpleCov has anything to do at exit: coverage is being
-    # tracked, or a result has already been assembled (e.g. by collate).
-    def active_session?: () -> boolish
+    def active_session?: () -> bool
+
+    def coverage_running?: () -> bool
 
-    # Gets or sets the behavior run in a newly forked process. The
-    # block receives the child pid. The default renames the command
-    # from the fork serial, silences errors, and restarts SimpleCov.
     def at_fork: () ?{ (Integer pid) -> void } -> Proc
 
-    # The project name — defaults to the last dirname in `root`,
-    # capitalized, with underscores replaced by spaces.
     def project_name: (?String? new_name) -> String
 
   end
 end
 
-# ----- configuration/coverage_criteria -----
 
-# Selection and validation of the coverage criteria Ruby's `Coverage`
-# library should track: `:line` (default), `:branch`, `:method`, and
-# `:oneshot_line`. The standalone `:eval` toggle lives in
-# `configuration/eval_coverage.rb`.
 module SimpleCov
   module Configuration
-    # Members are line, branch, method, and oneshot_line (%i[] literals
-    # infer as Array[Symbol]).
     SUPPORTED_COVERAGE_CRITERIA: Array[Symbol]
 
     DEFAULT_COVERAGE_CRITERION: :line
@@ -272,38 +197,22 @@ module SimpleCov
     @coverage_criteria: Set[criterion | :oneshot_line]?
     @coverage_for_eval_enabled: bool?
 
-    # Enable one or more coverage criteria. `:eval` is accepted as a
-    # shorthand for the standalone eval-coverage toggle. `:line` and
-    # `:oneshot_line` replace each other; the last enabled mode wins.
     def enable_coverage: (*(criterion | :oneshot_line | :eval) criteria) -> void
 
-    # Remove `criterion` from the set of enabled coverage criteria.
-    # `:eval` turns the standalone eval-coverage toggle back off.
-    # Disabling every criterion raises at `start_tracking`, not here.
     def disable_coverage: ((criterion | :oneshot_line | :eval) criterion) -> void
 
-    # Gets the report's leading criterion, or sets it. The setter
-    # validates at runtime that the criterion is enabled; the parameter
-    # type also rejects unknown criteria statically.
     def primary_coverage: (?(criterion | :oneshot_line)? criterion) -> (criterion | :oneshot_line)
 
-    # The currently enabled criteria. Defaults to `Set[:line]`.
+    def primary_coverage=: ((criterion | :oneshot_line) criterion) -> (criterion | :oneshot_line)
+
     def coverage_criteria: () -> Set[criterion | :oneshot_line]
 
-    # Any Symbol is accepted: asking whether an unknown criterion is
-    # enabled is a legitimate question (the answer is false), and the
-    # private validators rely on it.
     def coverage_criterion_enabled?: (Symbol criterion) -> bool
 
-    # Reset the criteria back to the lazy default (`Set[:line]`).
     def clear_coverage_criteria: () -> void
 
     def validate_coverage_criteria!: () -> void
 
-    # Whether this run produces line data at all. The oneshot variant counts:
-    # `ResultAdapter` turns its executed-line list back into a line array. A
-    # branch-only or method-only run produces none, and `Coverage.result`
-    # entries for the files it loaded carry no `"lines"` key.
     def line_coverage?: () -> bool
 
     def branch_coverage?: () -> bool
@@ -314,37 +223,29 @@ module SimpleCov
 
     def method_coverage_supported?: () -> bool
 
-    # Whether the running Ruby's Coverage library supports the given
-    # criterion, named in Coverage's own plural vocabulary
-    # (`:lines`, `:branches`, `:methods`, `:oneshot_lines`, `:eval`).
     def coverage_criterion_supported?: (Symbol criterion) -> bool
 
+    def load_coverage: () -> untyped
+
     private
 
     def add_coverage_criterion: ((criterion | :oneshot_line) criterion) -> void
 
     def default_primary_coverage: () -> (criterion | :oneshot_line)
 
-    # Validators: any Symbol is accepted at the type level; the whole
-    # point of these is raising ConfigurationError on bad input.
     def raise_if_criterion_disabled: (Symbol criterion) -> void
 
     def raise_if_criterion_unsupported: (Symbol criterion) -> void
   end
 end
 
-# ----- configuration/eval_coverage -----
 
-# The standalone eval-coverage toggle (`enable_coverage :eval`),
-# instrumenting `eval`'d code on Rubies that support it. A boolean
-# toggle, never a member of the enabled-criteria set.
 module SimpleCov
   module Configuration
     def coverage_for_eval_supported?: () -> bool
 
     def coverage_for_eval_enabled?: () -> bool
 
-    # DEPRECATED: use `enable_coverage :eval` instead.
     def enable_coverage_for_eval: () -> void
 
     private
@@ -355,97 +256,92 @@ module SimpleCov
   end
 end
 
-# ----- configuration/coverage -----
-
-# The criterion-first `coverage` configuration method: naming a
-# criterion enables it, and every threshold is declared with the same
-# syntax regardless of criterion.
-#
-#   SimpleCov.start do
-#     coverage :line do
-#       minimum          90
-#       minimum_per_file 80
-#       minimum_per_file 100, only: "app/mailers/request_mailer.rb"
-#       maximum_drop     5
-#     end
-#
-#     coverage :branch, minimum: 80
-#   end
+
+module SimpleCov
+  module Configuration
+    DEFAULT_VIEW_GLOBS: Array[String]
+
+    @view_globs: Array[String]?
+
+    def cover_views: (*(String | Array[String?] | nil) globs) -> Array[String]
+
+    def view_globs: () -> Array[String]?
+
+    def view_coverage?: () -> bool
+  end
+end
+
+
 module SimpleCov
   module Configuration
-    # Members are minimum, maximum, exact, maximum_drop, and
-    # minimum_per_file (%i[] literals infer as Array[Symbol]).
     COVERAGE_THRESHOLD_OPTIONS: Array[Symbol]
 
-    # Configure (and, unless `enabled: false`, enable) a coverage
-    # criterion. `primary: true` makes it the report's leading
-    # criterion; `oneshot: true` (only for `:line`) selects
-    # oneshot-lines mode. Threshold keywords mirror the block verbs
-    # for one-liner use. Returns the criterion symbol the thresholds
-    # were stored under.
-    # The threshold keywords (minimum:, maximum:, exact:, maximum_drop:,
-    # minimum_per_file:) arrive via **thresholds in the implementation, so
-    # they are typed as a Numeric kwarg splat. The block runs under
-    # instance_eval, which also yields the receiver as an optional argument.
-    def coverage: ((criterion | :eval) criterion, ?primary: bool, ?enabled: bool, ?oneshot: bool, **Numeric thresholds) ?{ (?CoverageCriterion) [self: CoverageCriterion] -> void } -> (criterion | :oneshot_line | :eval)
+    def coverage: ((criterion | :eval) criterion, ?primary: bool, ?enabled: bool, ?oneshot: bool, **untyped thresholds) ?{ (?CoverageCriterion) [self: CoverageCriterion] -> void } -> (criterion | :oneshot_line | :eval)
 
     private
 
-    def apply_threshold_options: (CoverageCriterion configurator, Hash[Symbol, Numeric] options) -> void
+    def apply_threshold_options: (CoverageCriterion configurator, Hash[Symbol, untyped] options) -> void
 
     def enable_coverage_criterion: ((criterion | :eval) criterion, enabled: bool, oneshot: bool) -> (criterion | :oneshot_line | :eval)
 
     def resolve_criterion_variant: ((criterion | :eval) criterion, bool oneshot) -> (criterion | :oneshot_line | :eval)
 
-    # Threshold-store writers used by CoverageCriterion via `send`.
-    # They accept any criterion Symbol; `raise_on_invalid_coverage`
-    # rejects invalid ones (including `:eval`) at runtime.
     def store_overall_threshold: (Symbol setting, Symbol criterion, Numeric percent) -> void
 
     def store_minimum_per_file: (Symbol criterion, Numeric percent, (String | Regexp)? target) -> void
 
     def store_minimum_per_group: (Symbol criterion, Numeric percent, String group_name) -> void
 
+    def store_missed_cap: (Symbol setting, Symbol criterion, Integer count) -> void
+
+    def store_maximum_missed_per_file: (Symbol criterion, Integer count, (String | Regexp)? target) -> void
+
     public
 
-    # Receiver for a `coverage <criterion> do ... end` block. Each verb
-    # writes a threshold for the single criterion the block configures,
-    # so values are always plain percentages.
     class CoverageCriterion
+      type per_target = nil | :file | String | Regexp | GroupTarget
+
+      class GroupTarget
+        attr_reader name: String | Symbol
+
+        def initialize: (name: String | Symbol) -> void
+      end
+
       @config: Configuration
       @criterion: Symbol
 
       def initialize: (Configuration config, Symbol criterion) -> void
 
-      # Overall (suite-wide) minimum for this criterion.
-      def minimum: (Numeric percent) -> void
+      def minimum: (Numeric percent, ?per: per_target) -> void
 
-      # Overall maximum: fails the build if coverage rises above it.
       def maximum: (Numeric percent) -> void
 
-      # Pin coverage to an exact figure (sets both minimum and maximum).
       def exact: (Numeric percent) -> void
 
-      # Maximum allowed drop between runs (0 refuses any drop).
       def maximum_drop: (Numeric percent) -> void
 
-      # Per-file minimum. With no `only:`, the default for every file;
-      # with `only:` (String path or Regexp), an override for matches.
+      def maximum_missed: (Integer count, ?per: per_target) -> void
+
+      def group: (String | Symbol name) -> GroupTarget
+
+      def ignore: (*(Symbol | Array[Symbol]) types) -> Array[Symbol]
+
       def minimum_per_file: (Numeric percent, ?only: (String | Regexp)?) -> void
 
-      # Per-group minimum for the named group (defined via `group`).
       def minimum_per_group: (Numeric percent, only: String) -> void
 
-      # Make this criterion the report's primary (leading) criterion.
+      def maximum_missed_per_file: (Integer count, ?only: (String | Regexp)?) -> void
+
       def primary: () -> void
+
+      private
+
+      def raise_invalid_per: (untyped per) -> bot
     end
   end
 end
 
-# ----- configuration/filters -----
 
-# Inclusion / exclusion / grouping methods: `cover`, `skip`, `group`,
-# plus the deprecated `track_files` / `add_filter` / `add_group` aliases.
 module SimpleCov
   module Configuration
     attr_writer filters: Array[Filter[untyped]]
@@ -455,56 +351,36 @@ module SimpleCov
     @cover_filters: Array[Filter[untyped]]?
     @tracked_files: String?
 
-    # Restrict the report to files matching one or more shell globs,
-    # regexps, or block predicates. Multiple calls union. String globs
-    # are also expanded on disk so unloaded files appear at 0% coverage.
     def cover: (*cover_arg args) ?{ (SourceFile source_file) -> boolish } -> Array[Filter[untyped]]
 
-    # The configured inclusion filters added via `cover`.
     def cover_filters: () -> Array[Filter[untyped]]
 
-    # The string globs passed to `cover`, driving unloaded-file discovery.
     def cover_globs: () -> Array[String]
 
-    # DEPRECATED: use `cover` instead.
     def track_files: (String? glob) -> String?
 
     def track_files_replacement_hint: (String? glob) -> String
 
-    # The glob used to include files that were not explicitly required.
     def tracked_files: () -> String?
 
-    # The configured exclusion filters added via `skip` (or the
-    # deprecated `add_filter`).
     def filters: () -> Array[Filter[untyped]]
 
-    # Drop matching files from the coverage report. The inverse of
-    # `cover`. Strings match at path-segment boundaries.
     def skip: (?filter_arg? filter_argument) ?{ (SourceFile source_file) -> boolish } -> Array[Filter[untyped]]
 
-    # DEPRECATED: use `skip` instead (same arguments, same behavior).
     def add_filter: (?filter_arg? filter_argument) ?{ (SourceFile source_file) -> boolish } -> Array[Filter[untyped]]
 
-    # Remove any filters whose `filter_argument` equals the given
-    # value. Returns true when at least one filter was removed.
     def remove_filter: (untyped filter_argument) -> bool
 
-    # Remove every filter from the chain, including the defaults
-    # installed by `SimpleCov.start`.
     def clear_filters: () -> Array[Filter[untyped]]
 
-    # The configured groups. Add groups using `group`.
     def groups: () -> Hash[String, Filter[untyped]]
 
-    # Define a display group for files. Same matcher grammar as `skip`,
-    # but bins matches under `group_name` instead of dropping them.
+    def default_groups: () -> Hash[String, Filter[untyped]]
+
     def group: (String group_name, ?filter_arg? filter_argument) ?{ (SourceFile source_file) -> boolish } -> Filter[untyped]
 
-    # DEPRECATED: use `group` instead (same arguments, same behavior).
     def add_group: (String group_name, ?filter_arg? filter_argument) ?{ (SourceFile source_file) -> boolish } -> Filter[untyped]
 
-    # Drop every previously installed filter (defaults included) so
-    # subsequent `skip` calls start from a clean slate.
     def no_default_skips: () -> Array[Filter[untyped]]
 
     private
@@ -517,15 +393,9 @@ module SimpleCov
   end
 end
 
-# ----- configuration/formatting -----
 
-# Formatter selection (`formatter` / `formatters`), reporting toggles
-# (`print_errors`, `color`, `source_in_json`), and the deprecated
-# `# :nocov:` token hook.
 module SimpleCov
   module Configuration
-    # A formatter is a Class whose instances respond to `format(result)`
-    # (including the anonymous Class built by `MultiFormatter.new`).
     attr_writer formatter: Class?
 
     attr_writer print_error_status: bool
@@ -534,71 +404,64 @@ module SimpleCov
     @source_in_json: bool
     @nocov_token: String
 
-    # Gets or sets the configured formatter. Pass `false` (or `nil`) to
-    # opt out of formatting entirely (see #964).
+    BUILT_IN_FORMATS: Hash[Symbol, Symbol]
+
+    LAZY_FORMAT_REQUIRES: Hash[Symbol, String]
+
+    def formats: (*untyped names) -> (Array[Class] | Class | nil)
+
     def formatter: (?(Class | false | :__no_arg__)? formatter) -> Class?
 
-    # Gets the formatter chain, or sets it. Accepts an Array, a single
-    # formatter, or nil / `[]` to opt out of formatting entirely.
-    # Returns the passed value when setting.
     def formatters: (?(Array[Class] | Class | :__no_arg__)? formatters) -> (Array[Class] | Class | nil)
 
-    # Sets the configured formatters (single formatters are wrapped;
-    # nil / `[]` opts out of formatting entirely).
     def formatters=: ((Array[Class] | Class)? formatters) -> void
 
-    # Whether stderr diagnostics are colorized: `true`, `false`, or
-    # `:auto` (default — respects TTY, NO_COLOR, and FORCE_COLOR).
     def color: (?(bool | :auto | :__no_arg__) value) -> (bool | :auto)
 
-    # Whether SimpleCov prints its own diagnostic warnings to stderr.
-    # Defaults to true.
+    def color=: (untyped value) -> untyped
+
     def print_errors: (?(bool | :__no_arg__) value) -> bool
 
-    # Whether `coverage.json` embeds the full source text of every
-    # file. Defaults to true.
+    def print_errors=: (bool value) -> bool
+
     def source_in_json: (?(bool | :__no_arg__) value) -> bool
 
-    # DEPRECATED: use `print_errors` instead (same value).
+    def source_in_json=: (bool value) -> bool
+
     def print_error_status: () -> bool
 
-    # DEPRECATED: use `# simplecov:disable` / `# simplecov:enable`
-    # directive comments instead of `# :nocov:` toggles.
     def nocov_token: (?String? nocov_token) -> String
 
-    # DEPRECATED: alias for `nocov_token`.
     alias skip_token nocov_token
 
     def current_nocov_token: (?String? value) -> String
+
+    private
+
+    def combined_formatter: (Array[untyped] formatters) -> untyped
+
+    def resolve_format: (untyped name) -> untyped
+
+    def require_html_formatter: (untyped name) -> void
   end
 end
 
-# ----- configuration/ignored_entries -----
 
-# Coverage-entry filters scoped to branch / method criteria. See
-# `ignore_branches` / `ignore_methods` and #1033 / #1046.
 module SimpleCov
   module Configuration
-    # Branch types accepted by `ignore_branches`: implicit_else and
-    # eval_generated (%i[] literals infer as Array[Symbol]).
     IGNORABLE_BRANCH_TYPES: Array[Symbol]
 
-    # Method types accepted by `ignore_methods`: eval_generated (%i[]
-    # literals infer as Array[Symbol]).
     IGNORABLE_METHOD_TYPES: Array[Symbol]
 
     @ignored_branches: Array[Symbol]?
     @ignored_methods: Array[Symbol]?
 
-    # Opt out of synthetic branch entries. Variadic; multiple calls
-    # union. Recorded even when branch coverage is not (yet) enabled.
     def ignore_branches: (*(:implicit_else | :eval_generated) types) -> Array[Symbol]
 
     def ignored_branches: () -> Array[Symbol]
 
     def ignored_branch?: (Symbol type) -> bool
 
-    # Opt out of synthetic method entries (currently `:eval_generated` only).
     def ignore_methods: (*:eval_generated types) -> Array[Symbol]
 
     def ignored_methods: () -> Array[Symbol]
@@ -607,22 +470,37 @@ module SimpleCov
 
     private
 
+    def store_ignored_branches: (Array[Symbol] types) -> Array[Symbol]
+
+    def store_ignored_methods: (Array[Symbol] types) -> Array[Symbol]
+
     def raise_if_branch_type_unsupported: (Symbol type) -> void
 
     def raise_if_method_type_unsupported: (Symbol type) -> void
   end
 end
 
-# ----- configuration/merging -----
 
-# Result merging and subprocess / parallel-test coordination:
-# `merging`, `merge_subprocesses`, `merge_timeout`, `finalize_merge`,
-# `parallel_tests`, `parallel_wait_timeout`.
 module SimpleCov
   module Configuration
-    # `defined?`-guarded module state. Declared non-nil where every
-    # read is guarded, so readers don't have to refute a nil that
-    # cannot be observed.
+    @track_tests: bool
+    @track_tests_granularity: Symbol?
+
+    TRACK_TESTS_GRANULARITIES: Array[Symbol]
+
+    def track_tests: (?bool? enabled, ?granularity: Symbol?) -> bool
+
+    def track_tests_granularity: () -> Symbol
+
+    def track_tests?: () -> bool
+
+    def validate_test_tracking!: () -> void
+  end
+end
+
+
+module SimpleCov
+  module Configuration
     @enable_for_subprocesses: bool
     @parallel_tests: bool?
     @use_merging: bool
@@ -632,50 +510,42 @@ module SimpleCov
     @merge_timeout: Integer?
     @parallel_wait_timeout: Integer?
 
-    # Get or set whether SimpleCov hooks `Process._fork` to attach
-    # itself to subprocesses (e.g. Rails' `parallelize(workers:)`).
-    # Defaults to false.
     def merge_subprocesses: (?bool? value) -> bool
 
+    def merge_subprocesses=: (bool? value) -> untyped
+
     def enabled_for_subprocesses?: () -> bool
 
-    # Get or set whether SimpleCov auto-requires the `parallel_tests`
-    # gem when it sees its environment variables. nil (the default)
-    # means auto-detect. See #1018.
     def parallel_tests: (?(:__no_arg__ | bool)? value) -> bool?
 
-    # DEPRECATED: use `merge_subprocesses` instead (same value).
+    def parallel_tests=: (untyped value) -> untyped
+
     def enable_for_subprocesses: (?bool? value) -> bool
 
-    # Get or set whether to merge results from multiple test suites
-    # into a single coverage report. Defaults to true.
     def merging: (?bool? use) -> bool
 
-    # Get or set whether SimpleCov's selected final process owns merge processing:
-    # waiting for sibling workers, merging, formatting, enforcing
-    # thresholds, and writing `.last_run.json`. Defaults to true except
-    # for recognized multi-worker parallel runs writing to a custom
-    # coverage destination (those likely finalize via an external
-    # `SimpleCov.collate` step). See #1215.
-    def finalize_merge: (?(:__no_arg__ | bool) value) -> bool
+    def merging=: (bool use) -> bool
+
+    def finalize_merge: (*bool value) -> bool
+
+    def finalize_merge=: (bool value) -> bool
 
     def finalize_merge?: () -> bool
 
     def merge_finalization_owner?: () -> boolish
 
-    # DEPRECATED: use `merging` instead (same value, same behavior).
-    # Returns nil when merging had already been disabled.
     def use_merging: (?bool? use) -> bool
 
-    # The maximum age (in seconds) of a resultset to still be included
-    # in merged results. Defaults to 600.
     def merge_timeout: (?Integer? seconds) -> Integer
 
-    # How long (in seconds) the reporting process waits for remaining
-    # parallel-test workers to write their resultsets before it
-    # proceeds with a partial merge. Defaults to 60. See #1171.
+    def merge_timeout=: (untyped seconds) -> untyped
+
+    def env_merge_timeout: () -> Integer?
+
     def parallel_wait_timeout: (?Integer? seconds) -> Integer
 
+    def parallel_wait_timeout=: (untyped seconds) -> untyped
+
     private
 
     def inferred_finalize_merge?: () -> bool
@@ -690,83 +560,70 @@ module SimpleCov
 
     def inferred_finalize_merge_warning: () -> String
 
-    # Host contract: defined on SimpleCov itself (result_processing.rb).
-    # This module is only ever extended onto SimpleCov, where both methods
-    # are available to `merge_finalization_owner?`.
     def collating_result?: () -> boolish
 
     def final_result_process?: () -> boolish
   end
 end
 
-# ----- configuration/thresholds -----
 
-# Coverage threshold configuration: `minimum_coverage`,
-# `maximum_coverage`, `expected_coverage`, `maximum_coverage_drop`,
-# `refuse_coverage_drop`, and the deprecated by-file / by-group forms.
 module SimpleCov
   module Configuration
-    # Thresholds are stored per criterion; a bare Numeric argument is
-    # normalized to `{primary_coverage => value}`. Keys are criterion
-    # symbols — Symbol rather than the `criterion` alias because the
-    # stores also carry `:oneshot_line`, and the validating setters are
-    # the layer that rejects unknown symbols (with ConfigurationError).
     type coverage_thresholds = Hash[Symbol, Numeric]
 
+    type missed_caps = Hash[Symbol, Integer]
+
     @minimum_coverage: coverage_thresholds?
     @maximum_coverage: coverage_thresholds?
     @maximum_coverage_drop: coverage_thresholds?
+    @maximum_missed: missed_caps?
+    @maximum_missed_per_file: missed_caps?
+    @maximum_missed_per_file_overrides: Hash[String | Regexp, missed_caps]?
     @minimum_coverage_by_file: coverage_thresholds?
     @minimum_coverage_by_file_overrides: Hash[String | Regexp, coverage_thresholds]?
     @minimum_coverage_by_group: Hash[String, coverage_thresholds]?
 
-    # The minimum overall coverage required for the suite to pass.
-    # Default: none (0%, disabled).
     def minimum_coverage: (?(Numeric | coverage_thresholds)? coverage) -> coverage_thresholds
 
-    def raise_on_invalid_coverage: (coverage_thresholds coverage, String coverage_setting) -> void
+    def raise_on_invalid_coverage: (coverage_thresholds coverage, (String | Symbol) coverage_setting) -> void
 
-    # The maximum overall coverage allowed — an unexpected jump above
-    # it fails the build. Pair with `minimum_coverage` (or use
-    # `expected_coverage`) to pin coverage. See #187.
     def maximum_coverage: (?(Numeric | coverage_thresholds)? coverage) -> coverage_thresholds
 
-    # Pin the suite to an exact figure: sets both `minimum_coverage`
-    # and `maximum_coverage`. See #187.
     def expected_coverage: (?(Numeric | coverage_thresholds)? coverage) -> coverage_thresholds
 
-    # The maximum coverage drop between runs allowed for the suite to
-    # pass. Default: none (100%, disabled).
     def maximum_coverage_drop: (?(Numeric | coverage_thresholds)? coverage_drop) -> coverage_thresholds
 
-    # DEPRECATED: use `coverage(criterion) { minimum_per_file ... }`.
-    # Symbol keys declare per-criterion defaults; String / Regexp keys
-    # declare per-path overrides.
+    def maximum_missed: (?(Numeric | missed_caps)? counts) -> missed_caps
+
+    def maximum_missed_per_file: (?(Numeric | missed_caps)? counts) -> missed_caps
+
+    def maximum_missed_per_file_overrides: () -> Hash[String | Regexp, missed_caps]
+
     def minimum_coverage_by_file: () -> coverage_thresholds
                                 | ((Numeric | Hash[Symbol | String | Regexp, Numeric | coverage_thresholds]) coverage) -> Hash[String | Regexp, coverage_thresholds]
 
-    # The per-path overrides set via `minimum_coverage_by_file` (or
-    # `coverage(criterion) { minimum_per_file N, only: ... }`).
     def minimum_coverage_by_file_overrides: () -> Hash[String | Regexp, coverage_thresholds]
 
-    # DEPRECATED: use `coverage(criterion) { minimum_per_group ... }`.
     def minimum_coverage_by_group: () -> Hash[String, coverage_thresholds]
                                  | (Hash[String, Numeric | coverage_thresholds] coverage) -> Hash[String, coverage_thresholds]
 
-    # Refuse any coverage drop for the given criteria (all enabled
-    # criteria when none are given). Coverage may only increase.
     def refuse_coverage_drop: (*(criterion | :oneshot_line) criteria) -> coverage_thresholds
 
     private
 
-    # Shared normalize-and-validate step behind every threshold setter.
     def normalized_threshold: ((Numeric | coverage_thresholds) coverage, String setting) -> coverage_thresholds
 
+    def normalized_missed_caps: ((Numeric | missed_caps) counts, String setting) -> missed_caps
+
+    def raise_on_invalid_missed_cap: (untyped cap, (String | Symbol) setting) -> void
+
+    def missed_per_file_replacement: ((Numeric | missed_caps) counts) -> String
+
     def partition_per_file_thresholds: (Hash[Symbol | String | Regexp, Numeric | coverage_thresholds] coverage) -> [coverage_thresholds, Hash[String | Regexp, coverage_thresholds]]
 
     def validate_per_file_key: ((Symbol | String | Regexp) key) -> void
 
-    def minimum_possible_coverage_exceeded: (String coverage_option) -> void
+    def minimum_possible_coverage_exceeded: ((String | Symbol) coverage_option) -> void
 
     def per_file_coverage_replacement: (coverage_thresholds defaults, Hash[String | Regexp, coverage_thresholds] overrides) -> String
 
@@ -776,35 +633,30 @@ module SimpleCov
   end
 end
 
-# ----- result -----
 
 module SimpleCov
-  # A coverage result built from the Hash Ruby's Coverage library
-  # produces: filename => per-criterion coverage data.
   class Result
     extend Forwardable
+    include Serialization
 
     attr_reader original_result: Hash[String, untyped]
 
-    # Every path the producing process was told to track, loaded or not.
     attr_reader tracked_files: Array[String]
     attr_reader run_id: String?
     attr_reader worker_id: String?
     attr_reader files: FileList
     alias source_files files
-    # The writers accept the strict types; the ivars stay nilable because
-    # both default to nil and are lazily backfilled by the readers.
+    attr_reader contexts: ContextMap?
     attr_writer created_at (): Time
     attr_writer command_name (): String
+    attr_writer command_names (): Array[String]
 
     @created_at: Time?
     @command_name: String?
+    @command_names: Array[String]?
     @groups_config: Hash[String, Filter[untyped]]
     @groups: Hash[String, FileList]?
 
-    # Bundles filter and grouping configuration. Every field defaults to
-    # the SimpleCov singleton's configuration; tests pass a custom
-    # instance (e.g. `filters: []`) to opt out.
     class FilterConfig
       attr_reader filters: Array[Filter[untyped]]
       attr_reader cover_filters: Array[Filter[untyped]]
@@ -813,22 +665,19 @@ module SimpleCov
       def initialize: (?filters: Array[Filter[untyped]], ?cover_filters: Array[Filter[untyped]], ?groups: Hash[String, Filter[untyped]]) -> void
     end
 
-    def initialize: (Hash[String, untyped] original_result, ?command_name: String?, ?created_at: Time?, ?not_loaded_files: Set[String], ?tracked_files: _ToA[String], ?run_id: String?, ?worker_id: String?, ?report: bool, ?filter_config: FilterConfig) -> void
+    def initialize: (Hash[String, untyped] original_result, ?command_name: String?, ?created_at: Time?, ?not_loaded_files: Set[String], ?tracked_files: _ToA[String]?, ?run_id: String?, ?worker_id: String?, ?contexts: ContextMap?, ?report: bool, ?filter_config: FilterConfig) -> void
 
     def filenames: () -> Array[String]
-    # Accepts an absolute or project-relative path (resolved against SimpleCov.root).
     def source_file_for: (String path) -> SourceFile?
     def coverage_for: (String path) -> Hash[criterion, CoverageStatistics]?
     def groups: () -> Hash[String, FileList]
-    # Returns nil when formatting is opted out of (`formatter false` /
-    # `formatters []`); otherwise whatever the configured formatter returns.
+    def configured_group?: (String group_name) -> bool
     def format!: () -> untyped
     def created_at: () -> Time
     def command_name: () -> String
-    def to_hash: () -> Hash[String, Hash[String, untyped]]
+    def command_names: () -> Array[String]
     def self.from_hash: (Hash[String, untyped] hash) -> Array[Result]
 
-    # Delegated to #files (see FileList).
     def covered_percent: (?criterion) -> Float?
     def covered_percentages: () -> Array[Float?]
     def least_covered_file: () -> String?
@@ -848,20 +697,47 @@ module SimpleCov
 
     private
 
-    def initialize_coordination_metadata: (_ToA[String] tracked_files, String? run_id, String? worker_id) -> void
-    def warn_about_missing_source_files: (Array[String] missing, Integer input_size) -> void
-    def coverage: () -> Hash[String, untyped]
+    def initialize_resultset_metadata: (_ToA[String]? tracked_files, String? run_id, String? worker_id, ContextMap? contexts) -> void
+    def warn_about_missing_source_files: (Array[String] missing) -> void
     def apply_filters!: (Array[Filter[untyped]] filters) -> void
     def apply_cover_filters!: (Array[Filter[untyped]] cover_filters) -> void
   end
+
+  class Result
+    interface _SerializableResult
+      def original_result: () -> Hash[String, untyped]
+
+      def created_at: () -> Time
+
+      def command_name: () -> String
+
+      def run_id: () -> String?
+
+      def worker_id: () -> String?
+
+      def tracked_files: () -> Array[String]
+
+      def contexts: () -> ContextMap?
+
+      def filenames: () -> Array[String]
+    end
+
+    module Serialization : _SerializableResult
+      def to_hash: () -> Hash[String, Hash[String, untyped]]
+
+      private
+
+      def append_contexts: (Hash[String, untyped] data) -> void
+
+      def context_filenames: () -> Set[String]
+
+      def coverage: () -> Hash[String, untyped]
+    end
+  end
 end
 
-# ----- file_list -----
 
 module SimpleCov
-  # An Enumerable of SourceFile instances with aggregate coverage
-  # helpers. Aggregate readers return nil when the corresponding
-  # criterion was not enabled for the run.
   class FileList
     include Enumerable[SimpleCov::SourceFile]
     extend Forwardable
@@ -872,7 +748,6 @@ module SimpleCov
     @coverage_statistics: Hash[criterion, CoverageStatistics]?
     @coverage_statistics_by_file: Hash[criterion, Array[CoverageStatistics]]?
 
-    # Delegated to the underlying Array.
     def each: () { (SourceFile) -> void } -> void
             | () -> Enumerator[SourceFile, untyped]
     def size: () -> Integer
@@ -917,23 +792,16 @@ module SimpleCov
   end
 end
 
-# ----- source_file -----
 
 module SimpleCov
-  # A source file with its coverage data, source lines, and helpers to
-  # interpret that data.
   class SourceFile
     include BuilderContext
 
-    # Full absolute path to the file.
     attr_reader filename: String
-    # Coverage.result-shaped data for this file, e.g.
-    # {"lines" => [...], "branches" => {...}, "methods" => {...}}.
     attr_reader coverage_data: Hash[String, untyped]
 
     def initialize: (String filename, Hash[String, untyped] coverage_data, ?loaded: bool) -> void
 
-    # Memoization backing for the lazy readers below.
     @loaded: bool
     @src: Array[String]?
     @coverage_statistics: Hash[criterion, CoverageStatistics]?
@@ -951,15 +819,10 @@ module SimpleCov
     @covered_methods: Array[Method]?
     @missed_methods: Array[Method]?
 
-    # Project-relative path with no leading separator (e.g. "lib/foo.rb").
     def project_filename: () -> String
-    # Source lines, read lazily.
     def src: () -> Array[String]
     alias source src
 
-    # With no argument returns a Hash keyed by every supported criterion
-    # (disabled criteria collapse to 0/0/0); pass a criterion to get that
-    # one CoverageStatistics.
     def coverage_statistics: () -> Hash[criterion, CoverageStatistics]
                            | (criterion) -> CoverageStatistics?
 
@@ -970,7 +833,6 @@ module SimpleCov
     def never_lines: () -> Array[Line]
     def skipped_lines: () -> Array[Line]
     def lines_of_code: () -> Integer
-    # 1-based line lookup.
     def line: (Integer number) -> Line?
     def covered_percent: (?criterion) -> Float?
     def covered_strength: (?criterion) -> Float?
@@ -979,11 +841,8 @@ module SimpleCov
 
     def branches: () -> Array[Branch]
     def no_branches?: () -> bool
-    # DEPRECATED: use `covered_percent(:branch)`.
     def branches_coverage_percent: () -> Float?
-    # All relevant (covered + missed) branches, not a count.
     def total_branches: () -> Array[Branch]
-    # line number => Array of [branch type, hit count] pairs.
     def branches_report: () -> Hash[Integer, Array[[ Symbol, Integer ]]]
     def covered_branches: () -> Array[Branch]
     def missed_branches: () -> Array[Branch]
@@ -993,21 +852,15 @@ module SimpleCov
     def methods: () -> Array[Method]
     def covered_methods: () -> Array[Method]
     def missed_methods: () -> Array[Method]
-    # DEPRECATED: use `covered_percent(:method)`.
     def methods_coverage_percent: () -> Float?
 
-    # Whether this file was added via `cover` / `track_files` but never
-    # loaded during the run.
     def not_loaded?: () -> bool
   end
 end
 
-# ----- source_file/line -----
 
 module SimpleCov
   class SourceFile
-    # A single source line with its coverage: nil (not relevant, e.g. a
-    # comment), 0 (missed), or >= 1 (times executed).
     class Line
       attr_reader src: String
       attr_reader line_number: Integer
@@ -1018,8 +871,6 @@ module SimpleCov
       alias line line_number
       alias number line_number
 
-      # Raises ArgumentError unless src is a String, line_number an
-      # Integer, and coverage an Integer or nil.
       def initialize: (String src, Integer line_number, Integer? coverage) -> void
 
       def missed?: () -> bool
@@ -1027,22 +878,18 @@ module SimpleCov
       def never?: () -> bool
       def skipped!: () -> void
       def skipped?: () -> bool
-      # "covered", "missed", "skipped", or "never" — useful e.g. as a css class.
-      def status: () -> String?
+      def status: () -> String
     end
   end
 end
 
-# ----- source_file/branch -----
 
 module SimpleCov
   class SourceFile
-    # A single branch detected in the coverage data.
     class Branch
       attr_reader start_line: Integer
       attr_reader end_line: Integer
       attr_reader coverage: Integer
-      # Branch arm type as reported by Coverage (:then, :else, :when, ...).
       attr_reader type: Symbol
 
       @inline: bool
@@ -1053,28 +900,21 @@ module SimpleCov
       def inline?: () -> bool
       def covered?: () -> bool
       def missed?: () -> bool
-      # The line the branch is reported on: its own start line when
-      # inline, otherwise the line above (the if/else itself).
       def report_line: () -> Integer
       def skipped!: () -> void
       def skipped?: () -> bool
       def overlaps_with?: (Range[Integer] line_range) -> bool
-      # [branch type, hit count]
       def report: () -> [ Symbol, Integer ]
     end
   end
 end
 
-# ----- source_file/method -----
 
 module SimpleCov
   class SourceFile
-    # A single method detected in the coverage data.
     class Method
       attr_reader source_file: SourceFile
       attr_reader coverage: Integer
-      # A Module when the data comes straight from Coverage, a String
-      # after a JSON round-trip through a resultset.
       attr_reader class_name: Module | String
       attr_reader method_name: Symbol | String
       attr_reader start_line: Integer?
@@ -1085,15 +925,12 @@ module SimpleCov
       @skipped: bool
       @lines: Array[Line]?
 
-      # info is the Coverage method key minus its class entry:
-      # [class_name, method_name, start_line, start_col, end_line, end_col].
       def initialize: (SourceFile source_file, [ Module | String, Symbol | String, Integer?, Integer?, Integer?, Integer? ] info, Integer coverage) -> void
 
       def covered?: () -> bool
       def skipped?: () -> bool
       def skipped!: () -> void
       def missed?: () -> bool
-      # The source lines spanned by this method ([] when the location is unknown).
       def lines: () -> Array[Line]
       def overlaps_with?: (Range[Integer] line_range) -> bool
       def to_s: () -> String
@@ -1101,12 +938,9 @@ module SimpleCov
   end
 end
 
-# ----- source_file/statistics -----
 
 module SimpleCov
   class SourceFile
-    # Builds the CoverageStatistics triple (:line/:branch/:method) for a
-    # SourceFile; disabled or empty criteria collapse to 0/0/0.
     class Statistics
       @source_file: SourceFile
 
@@ -1122,54 +956,35 @@ module SimpleCov
 
       def method_statistics: () -> Hash[criterion, CoverageStatistics]
 
+      def unaccounted?: (SourceFile source_file, String table) -> bool
+
       def coverage_statistics: (Array[Line | Branch | Method] covered, Array[Line | Branch | Method] missed, ?omitted: Integer, ?percent: Float?) -> CoverageStatistics
     end
   end
 end
 
-# ----- source_file/builder_context -----
 
 module SimpleCov
   class SourceFile
-    # Helpers shared by the per-criterion builders (LineBuilder /
-    # BranchBuilder / MethodBuilder). Mixed into SourceFile so each
-    # builder can ask the file for its skip-chunk ranges and Prism-derived
-    # real source positions without duplicating the memoization.
     module BuilderContext
-      # Positions extracted from the parsed source: branch start lines,
-      # and [method name, line] pairs. Method names are Symbols from
-      # runtime data and Strings after a JSON round-trip.
       type real_positions = { branches: Set[Integer], methods: Set[[untyped, Integer]] }
 
       @skip_chunks: SkipChunks?
       @real_source_positions: real_positions?
 
-      # Skip-chunk lookup for the named criterion (`:line`, `:branch`,
-      # `:method`).
       def skip_chunks_for: (criterion) -> Array[Range[Integer]]
 
-      # Memoized set of real source positions extracted via Prism. Returns
-      # nil when Prism is unavailable or parsing fails, signaling callers
-      # to keep every Coverage entry (no false drops). The `defined?`
-      # guard preserves a nil memoization across calls.
       def real_source_positions: () -> real_positions?
 
-      # Provided by the including class (SourceFile).
       def filename: () -> String
       def src: () -> Array[String]
     end
   end
 end
 
-# ----- coverage_statistics -----
 
 module SimpleCov
-  # Uniform per-criterion coverage statistics. Counts are Integers;
-  # percent and strength are Floats. `percent` is 100.0 whenever nothing
-  # was missed, including the 0-of-0 case; `strength` is 0.0 when there
-  # is nothing to cover.
   class CoverageStatistics
-    # Seed for the reduce in .from: covered, missed, omitted, strength.
     ZERO_STATS: [Integer, Integer, Integer, Float]
 
     attr_reader total: Integer
@@ -1181,8 +996,6 @@ module SimpleCov
 
     def self.from: (Array[CoverageStatistics] coverage_statistics) -> CoverageStatistics
 
-    # `percent:` overrides the computed percentage (used to report 0%
-    # for tracked-but-never-loaded files).
     def initialize: (covered: Integer, missed: Integer, ?omitted: Integer, ?total_strength: Integer | Float, ?percent: Float?) -> void
 
     private
@@ -1192,16 +1005,11 @@ module SimpleCov
   end
 end
 
-# ----- last_run -----
 
 module SimpleCov
-  # Reads and writes coverage/.last_run.json — the previous run's
-  # coverage percentages used by MaximumCoverageDropCheck.
   module LastRun
     def self.last_run_path: () -> String
 
-    # nil when the file does not exist, is blank, or does not hold a
-    # JSON object. Keys are symbolized.
     def self.read: () -> Hash[Symbol, untyped]?
 
     def self.write: (Hash[Symbol, untyped] json) -> void
@@ -1210,41 +1018,29 @@ module SimpleCov
   end
 end
 
-# ----- filter -----
 
 module SimpleCov
-  # Base filter class. Inherit and override `matches?` to create custom
-  # filters. `T` is the type of the configured filter argument.
   class Filter[T]
     attr_reader filter_argument: T
 
     def initialize: (T filter_argument) -> void
 
-    # The base implementation raises NotImplementedError.
     def matches?: (SourceFile source_file) -> boolish
 
-    # Whether the verdict depends only on the path, so it can be decided
-    # before the file has any coverage.
     def path_only?: () -> bool
 
     def self.build_filter: (filter_arg filter_argument, ?string_filter: singleton(Filter)) -> Filter[untyped]
 
     def self.class_for_argument: (filter_arg filter_argument) -> singleton(Filter)
 
-    # Maps raw filter-argument classes (String, Regexp, Array, Proc) to
-    # the Filter subclass that handles them. Private class method.
     self.@filter_classes_by_argument_type: Hash[Class, singleton(Filter)]?
 
     def self.filter_classes_by_argument_type: () -> Hash[Class, singleton(Filter)]
   end
 
-  # Matches when the project path contains the configured string at a
-  # path-segment boundary ("lib" matches "lib/foo.rb" but not "library/").
   class StringFilter < Filter[String]
     def matches?: (SourceFile source_file) -> bool
 
-    # Whether the verdict depends only on the path, so it can be decided
-    # before the file has any coverage.
     def path_only?: () -> bool
 
     private
@@ -1256,122 +1052,81 @@ module SimpleCov
     def compute_segment_pattern: () -> Regexp
   end
 
-  # Matches when the project path matches the configured Regexp.
   class RegexFilter < Filter[Regexp]
     def matches?: (SourceFile source_file) -> bool
 
-    # Whether the verdict depends only on the path, so it can be decided
-    # before the file has any coverage.
     def path_only?: () -> bool
   end
 
-  # Matches when the configured block returns truthy for the source file.
   class BlockFilter < Filter[^(SourceFile) -> boolish]
     def matches?: (SourceFile source_file) -> boolish
 
-    # Whether the verdict depends only on the path, so it can be decided
-    # before the file has any coverage.
     def path_only?: () -> bool
   end
 
-  # Matches when the project path matches the configured shell glob
-  # (e.g. "lib/**/*.rb").
   class GlobFilter < Filter[String]
     def matches?: (SourceFile source_file) -> bool
 
-    # Whether the verdict depends only on the path, so it can be decided
-    # before the file has any coverage.
     def path_only?: () -> bool
   end
 
-  # Matches when any of the component filters built from the array's
-  # elements match. Note: `filter_argument` holds the built Filter
-  # objects, not the raw array passed to `new`.
   class ArrayFilter < Filter[Array[Filter[untyped]]]
     def initialize: (Array[filter_arg] filter_argument) -> void
 
     def matches?: (SourceFile source_file) -> boolish
 
-    # Whether the verdict depends only on the path, so it can be decided
-    # before the file has any coverage.
     def path_only?: () -> bool
   end
 end
 
-# ----- formatter -----
 
 module SimpleCov
-  # Namespace for result formatters. A formatter is any class whose
-  # instances respond to `#format(result)` and that can be instantiated
-  # with no arguments, or a ready-built instance responding to
-  # `#format(result)`; wire one up via `SimpleCov.formatter=` or
-  # `SimpleCov.formatters=`.
   module Formatter
-    # Structural interface for custom formatter instances.
     interface _Formatter
       def format: (SimpleCov::Result result) -> untyped
     end
 
-    # Normalizes a configured formatter — class or ready-built
-    # instance — into an instance. See #1240.
     def self.instance_for: (untyped formatter) -> untyped
 
-    # Instantiates a formatter class when necessary and dispatches the result.
+    def self.instantiable?: (untyped formatter) -> bool
+
     def self.format: (untyped formatter, SimpleCov::Result result) -> untyped
   end
 end
 
-# ----- formatter/base -----
 
 module SimpleCov
   module Formatter
-    # @api private — shared scaffolding for formatters that write a
-    # report to an output directory and emit the "Coverage report
-    # generated for X to Y" status line on stderr. Subclasses implement
-    # `format`.
     class Base
       @silent: bool
       @output_dir: String?
 
-      # `output_dir` defaults to `SimpleCov.coverage_path` when nil.
       def initialize: (?silent: bool, ?output_dir: String?) -> void
 
       private
 
-      # Subclasses prepend a marker (e.g. "JSON ") to the summary line.
       def message_prefix: () -> String
 
       def output_path: () -> String
 
-      # Directory (relative to cwd when inside it) plus the subclass's
-      # `entry_point_filename`, for the status line. See issue #197.
       def displayable_output_path: () -> String
 
       def relative_or_absolute_output_path: () -> String
 
-      # Subclasses name the report's entry-point file (`index.html`,
-      # `coverage.json`); nil leaves the bare directory in the status line.
       def entry_point_filename: () -> String?
 
-      # Prints `output_message` to stderr unless silent; the one home of
-      # the "status lines go to stderr, not through warn" decision (#1225).
-      def emit_status: (SimpleCov::Result result) -> void
+      def emit_status: (untyped result) -> void
 
-      def output_message: (SimpleCov::Result result) -> String
+      def output_message: (untyped result) -> String
 
-      # nil for branch/method criteria with nothing to measure, so the
-      # summary doesn't print "Branch coverage: 0 / 0 (100.00%)" noise.
       def stats_line: (Symbol criterion, SimpleCov::CoverageStatistics stat) -> String?
     end
   end
 end
 
-# ----- formatter/simple_formatter -----
 
 module SimpleCov
   module Formatter
-    # Renders the result as a plain-text string, one section per group.
-    # Returns the string; does not write anything to disk.
     class SimpleFormatter
       def format: (SimpleCov::Result result) -> String
 
@@ -1382,52 +1137,31 @@ module SimpleCov
   end
 end
 
-# ----- formatter/multi_formatter -----
 
 module SimpleCov
   module Formatter
-    # Wraps multiple formatters so one configured formatter can drive
-    # several output formats (HTML + JSON, etc.) in a single run.
     class MultiFormatter
-      # Shared `#format` implementation, included into the anonymous
-      # classes that `MultiFormatter.new` builds. Formatter errors are
-      # rescued and mapped to nil, so the result array can hold nils.
       module InstanceMethods
         def format: (SimpleCov::Result result) -> Array[untyped]
 
-        # Defined via `define_method` on each class `MultiFormatter.new`
-        # builds; declared here so users of those classes type-check.
         def formatters: () -> Array[untyped]
       end
 
-      # Returns a newly built Class (not a MultiFormatter instance) whose
-      # instances respond to `#format` and `#formatters`. The argument is
-      # normalized with `Array()`: a single formatter, an array of
-      # formatters, or nil are all accepted.
       def self.new: (?untyped formatters) -> Class
     end
   end
 end
 
-# ----- formatter/html_formatter -----
 
 module SimpleCov
   module Formatter
-    # Writes the HTML report as a single self-contained index.html (the
-    # compiled template with the coverage JSON substituted at the data
-    # marker), and coverage.json as a side artifact (shared serialization
-    # via JSONFormatter.build_hash).
     class HTMLFormatter < Base
       DATA_MARKER: "<!-- SIMPLECOV_COVERAGE_DATA -->"
 
-      # The sibling files a 1.0.0 through 1.0.3 report wrote next to
-      # index.html, removed by format when an earlier version left them.
       LEGACY_REPORT_FILES: Array[String]
 
       def format: (SimpleCov::Result result) -> void
 
-      # Generate HTML from a pre-existing coverage.json file without a
-      # live SimpleCov::Result or a running test suite.
       def format_from_json: (String json_path, String output_dir) -> void
 
       private
@@ -1436,11 +1170,8 @@ module SimpleCov
 
       def source_less_hash: (Hash[Symbol, untyped] hash) -> Hash[Symbol, untyped]
 
-      # Write coverage.json and index.html, then clear any legacy
-      # sibling files an earlier version left in the output directory.
       def write_report_files: (Hash[untyped, untyped] json_hash, Hash[untyped, untyped] viewer_hash, SimpleCov::Result result) -> void
 
-      # Substitute the coverage JSON into the compiled template.
       def render_report: (String json) -> String
 
       def public_dir: () -> String
@@ -1448,13 +1179,40 @@ module SimpleCov
   end
 end
 
-# ----- formatter/coverage_json_writer -----
 
 module SimpleCov
   module Formatter
-    # Shared writer for the coverage.json artifact (JSONFormatter's
-    # report and HTMLFormatter's side file): one pretty-printed binary
-    # write plus the issue-#1171 concurrent-overwrite warning.
+    class BaselineFormatter < Base
+      def format: (SimpleCov::Result result) -> void
+
+      private
+
+      def ratchet: (SimpleCov::Result result) -> String
+
+      def generate: (Baseline::current_floors current) -> String
+
+      def summary: (Baseline::Outcome outcome, bool changed) -> String
+
+      def below_floors: (Array[String] regressed) -> String
+
+      def current_floors: (SimpleCov::Result result) -> Baseline::current_floors
+
+      def measured_criteria: () -> Array[Symbol]
+
+      def floor_of: (untyped file, Symbol criterion) -> { percent: Numeric, missed: Integer }
+
+      def write: (Baseline baseline) -> void
+
+      def output_path: () -> String
+
+      def output_message: (untyped message) -> String
+    end
+  end
+end
+
+
+module SimpleCov
+  module Formatter
     module CoverageJSONWriter
       FILENAME: "coverage.json"
 
@@ -1462,20 +1220,14 @@ module SimpleCov
 
       def self?.write: (untyped output_path, Hash[Symbol, untyped] hash, SimpleCov::Result result) -> String
 
-      # Warns when an existing coverage.json is newer than this process's
-      # start time (a concurrent sibling writer). See issue #1171.
       def self?.warn_if_concurrent_overwrite: (String path, SimpleCov::Result result) -> void
 
-      # timestamp stays untyped (not Time) so the comparison sites don't
-      # require the stdlib `time` extension sigs; the value is produced by
-      # Time.iso8601 at runtime.
       def self?.existing_meta: (String path) -> ({ timestamp: untyped, command_name: untyped })?
 
+      def self?.parse_time: (untyped value) -> untyped
+
       def self?.parse_meta: (String path) -> Hash[Symbol, untyped]?
 
-      # Bounded head read that parses just the flat meta object of files
-      # this module wrote; nil on any miss so parse_meta falls back to a
-      # full parse.
       def self?.parse_meta_head: (String path) -> Hash[Symbol, untyped]?
 
       def self?.parse_meta_full: (String path) -> Hash[Symbol, untyped]?
@@ -1483,18 +1235,12 @@ module SimpleCov
   end
 end
 
-# ----- formatter/json_formatter -----
 
 module SimpleCov
   module Formatter
-    # Writes coverage results as JSON to coverage/coverage.json.
     class JSONFormatter < Base
       FILENAME: "coverage.json"
 
-      # The hash serialized to coverage.json ($schema, meta, total,
-      # coverage, groups, errors). `include_source:` defaults to
-      # `SimpleCov.source_in_json`; pass true to force the per-file
-      # source arrays regardless of the global setting.
       def self.build_hash: (SimpleCov::Result result, ?include_source: bool) -> Hash[Symbol, untyped]
 
       def format: (SimpleCov::Result result) -> void
@@ -1508,10 +1254,8 @@ module SimpleCov
   end
 end
 
-# ----- exit_codes -----
 
 module SimpleCov
-  # Exit codes SimpleCov uses when a coverage check fails.
   module ExitCodes
     SUCCESS: 0
 
@@ -1523,20 +1267,15 @@ module SimpleCov
 
     MAXIMUM_COVERAGE: 4
 
-    # Threshold-violation reports and exit-status notices: enforcement
-    # output on stderr, deliberately not routed through Kernel#warn.
+    UNITS: Hash[Symbol, String]
+
     def self.print_error: (String message) -> void
   end
 end
 
-# ----- exit_codes/exit_code_handling -----
 
 module SimpleCov
   module ExitCodes
-    # The threshold-limit readers ExitCodeHandling consults. Satisfied by
-    # SimpleCov's own configuration, or by any object exposing the same
-    # readers (see the dogfood check in spec/helper.rb for an example
-    # built from a plain Data class).
     interface _CoverageLimits
       def minimum_coverage: () -> Hash[Symbol, Numeric]
 
@@ -1549,66 +1288,313 @@ module SimpleCov
       def maximum_coverage: () -> Hash[Symbol, Numeric]
 
       def maximum_coverage_drop: () -> Hash[Symbol, Numeric]
+
+      def maximum_missed: () -> Hash[Symbol, Integer]
+
+      def maximum_missed_per_file: () -> Hash[Symbol, Integer]
+
+      def maximum_missed_per_file_overrides: () -> untyped
+
+      def baseline: () -> Baseline?
     end
 
-    # Runs every coverage check against the result and returns the exit
-    # code of the first failing one, or SUCCESS when all pass.
     module ExitCodeHandling
       def self?.call: (SimpleCov::Result result, coverage_limits: _CoverageLimits) -> Integer
 
       def self?.coverage_checks: (SimpleCov::Result result, _CoverageLimits coverage_limits) -> Array[untyped]
+
+      def self?.minimum_by_file_check: (SimpleCov::Result result, _CoverageLimits coverage_limits) -> untyped
+
+      def self?.maximum_missed_per_file_check: (SimpleCov::Result result, _CoverageLimits coverage_limits) -> untyped
     end
   end
 end
 
-# ----- profiles -----
 
 module SimpleCov
-  # Registry of named configuration procs, loadable via
-  # `SimpleCov.start :rails` and definable via
-  # `SimpleCov.profiles.define(:foo) { ... }`. The stored blocks are
-  # evaluated through `SimpleCov.configure`, so they self-bind to the
-  # configuration DSL.
-  # A stored profile block. The self-type is untyped because the block
-  # is written against the configuration DSL but stored as a plain Proc;
-  # it self-binds when SimpleCov.configure evaluates it.
+  module History
+    ENVELOPE: String
+
+    FORMAT_VERSION: Integer
+
+    type entry = Hash[String, untyped]
+
+    def self.history_path: () -> String
+
+    def self.record: (SimpleCov::Result result) -> void
+
+    def self.read: () -> Array[entry]
+
+    def self.entries_with: (SimpleCov::Result result) -> Array[entry]
+
+    def self.git_info: () -> [String?, String?]
+
+    private
+
+    def self.entry_for: (SimpleCov::Result result) -> entry
+
+    def self.measured_percents: (untyped stats_source) -> Hash[String, Numeric]
+
+    def self.files_percents: (SimpleCov::Result result) -> Hash[String, Hash[String, Numeric]]
+
+    def self.write: (Array[entry] entries) -> void
+
+    def self.invalid_history: () -> Array[entry]
+
+    def self.git: (*String args) -> String?
+  end
+end
+
+
+module SimpleCov
+  module Configuration
+    DROP_BASELINES: Array[Symbol]
+
+    @history_limit: Integer?
+
+    @drop_baseline: Symbol?
+
+    def history_limit: (?Integer? limit) -> Integer
+
+    def history_limit=: (Integer limit) -> Integer
+
+    def drop_baseline: (?Symbol? mode) -> Symbol
+  end
+end
+
+
+module SimpleCov
+  module Configuration
+    @production_coverage: String?
+
+    def production_coverage: (?String? path) -> String?
+
+    def production_coverage=: (String path) -> String
+  end
+end
+
+
+module SimpleCov
+  module Production
+    class Error < StandardError
+    end
+
+    interface _Sink
+      def store: (Hash[String, Array[Integer]] coverage) -> untyped
+    end
+
+    self.@running: bool?
+    self.@pid: Integer?
+    self.@started_coverage: bool?
+    self.@root_prefix: String
+    self.@sink: _Sink
+    self.@flush_interval: Float | Integer
+    self.@flush_jitter: Float | Integer
+    self.@sample_rate: Float | Integer
+    self.@max_buffered_lines: Integer
+    self.@pending: Hash[String, Set[Integer]]
+    self.@measuring: bool
+    self.@mutex: Mutex
+    self.@waiter: ConditionVariable
+    self.@thread: Thread?
+    self.@at_exit_installed: bool?
+
+    def self.start: (?root: String, ?sink: _Sink?, ?flush_interval: (Float | Integer),
+                     ?flush_jitter: (Float | Integer)?, ?sample_rate: (Float | Integer),
+                     ?max_buffered_lines: Integer) -> bool
+
+    def self.running?: () -> bool
+
+    def self.flush: () -> bool
+
+    def self.stop: () -> bool
+
+    def self.reset!: () -> void
+
+    private
+
+    def self.validate!: ((Float | Integer) flush_interval, (Float | Integer)? flush_jitter,
+                        (Float | Integer) sample_rate, Integer max_buffered_lines) -> void
+
+    def self.validate_jitter!: ((Float | Integer)? flush_jitter) -> void
+
+    def self.claim_coverage: () -> boolish
+
+    def self.oneshot_supported?: () -> bool
+
+    def self.configure: (String root, _Sink? sink, flush_interval: (Float | Integer),
+                         flush_jitter: (Float | Integer)?, sample_rate: (Float | Integer),
+                         max_buffered_lines: Integer) -> void
+
+    def self.default_sink: (String root) -> FileSink
+
+    def self.spawn_flush_thread: () -> void
+
+    def self.flush_loop: () -> void
+
+    def self.interval_with_jitter: () -> (Float | Integer)
+
+    def self.wake_flush_thread: () -> void
+
+    def self.cycle: () -> void
+
+    def self.resample: () -> void
+
+    def self.pull_pending: () -> void
+
+    def self.push_pending: () -> bool
+
+    def self.enforce_ceiling: () -> void
+
+    def self.relativize: (String path) -> String?
+
+    def self.warn_decline: (String reason) -> false
+
+    def self.install_at_exit: () -> void
+
+  end
+end
+
+
+module SimpleCov
+  module Production
+    class FileSink
+      ENVELOPE: String
+
+      FORMAT_VERSION: Integer
+
+      attr_reader path: String
+
+      def initialize: (path: String) -> void
+
+      def store: (Hash[String, Array[Integer]] coverage) -> true
+
+      def self.read: (String path) -> Hash[String, untyped]
+
+      def self.parse: (String content, String path) -> Hash[String, untyped]
+
+      def self.envelope_of: (untyped document, String path) -> Hash[String, untyped]
+
+      private
+
+      def with_exclusive_lock: [T] () { (File file) -> T } -> T
+
+      def open_file: [T] (String name, Integer mode, Integer perm) { (File file) -> T } -> T
+
+      def rewrite: (File file, Hash[String, untyped] payload) -> void
+
+      def merge: (Hash[String, untyped] existing, Hash[String, Array[Integer]] incoming) -> Hash[String, untyped]
+
+      def envelope: (Hash[String, untyped] existing, Hash[String, Array[Integer]] incoming) -> Hash[String, untyped]
+    end
+  end
+end
+
+
+module SimpleCov
+  class Baseline
+    DEFAULT_FILENAME: String
+
+    class Floor
+      attr_reader percent: Numeric
+      attr_reader missed: Integer?
+
+      def initialize: (percent: Numeric, missed: Integer?) -> void
+    end
+
+    class Outcome
+      attr_reader baseline: Baseline
+      attr_reader tightened: Array[String]
+      attr_reader pruned: Array[String]
+      attr_reader regressed: Array[String]
+      attr_reader unchanged: Array[String]
+
+      def initialize: (baseline: Baseline, tightened: Array[String], pruned: Array[String],
+                       regressed: Array[String], unchanged: Array[String]) -> void
+    end
+
+    type current_floors = Hash[String, Hash[Symbol, {percent: Numeric, missed: Integer}]]
+
+    def self.read_if_exists: (String path) -> Baseline?
+
+    def self.read: (String path) -> Baseline?
+
+    def self.generate: (current_floors current) -> Baseline
+
+    attr_reader entries: Hash[String, Hash[Symbol, Floor]]
+
+    def initialize: (Hash[String, Hash[Symbol, Floor]] entries) -> void
+
+    def entry_for: (String project_filename) -> Hash[Symbol, Floor]?
+
+    def floor_for: (String project_filename, Symbol criterion) -> Floor?
+
+    def covers?: (String project_filename, Symbol criterion) -> bool
+
+    def ratchet: (current_floors current) -> Outcome
+
+    def to_yaml: () -> String
+
+    private
+
+    def ratchet_entry: (Hash[Symbol, Floor] entry, Hash[Symbol, {percent: Numeric, missed: Integer}]? current_entry) -> {bucket: Symbol, ?entry: Hash[Symbol, Floor]}
+
+    def bucket_for: (Hash[Symbol, Floor] entry, Hash[Symbol, Floor] merged, Hash[Symbol, {percent: Numeric, missed: Integer}] current_entry) -> Symbol
+
+    def tighten: (Floor? floor, {percent: Numeric, missed: Integer}? current) -> Floor
+
+    def dump_floor: (Floor floor) -> Hash[String, untyped]
+  end
+end
+
+
+module SimpleCov
+  module Configuration
+    DEPRECATION_MODES: Array[Symbol]
+
+    @deprecations: Symbol?
+
+    def deprecations: (?Symbol? mode) -> Symbol
+  end
+end
+
+
+module SimpleCov
+  module Configuration
+    @baseline_file: String?
+
+    @baseline: Baseline?
+
+    @baseline_path: String?
+
+    def baseline_file: (?String? path) -> String
+
+    def baseline_file=: (String path) -> String
+
+    def baseline: () -> Baseline?
+  end
+end
+
+
+module SimpleCov
   type profile_proc = ^() [self: untyped] -> void
 
   class Profiles < Hash[Symbol, profile_proc]
-    # Raises SimpleCov::ConfigurationError when the name is taken.
-    # The block runs via instance_exec against the SimpleCov module itself
-    # (which extends Configuration), not a Configuration instance.
     def define: (Symbol | String name) { () [self: singleton(SimpleCov)] -> void } -> profile_proc
 
-    # Applies the named profile via SimpleCov.configure.
     def load: (Symbol | String name) -> void
 
-    # Returns the proc for the given profile name, autoloading bundled
-    # ("simplecov/profiles/<name>") or plugin-gem
-    # ("simplecov-profile-<name>") profiles on first lookup. Raises
-    # SimpleCov::ConfigurationError when none is found.
     def fetch_proc: (Symbol | String name) -> profile_proc
 
     private
 
-    # Tries `require "simplecov/profiles/<name>"`, then
-    # `require "simplecov-profile-<name>"`; swallows LoadError so
-    # fetch_proc raises the user-facing error.
     def autoload_profile: (Symbol name) -> void
   end
 end
 
-# ----- parallel_adapters -----
 
 module SimpleCov
-  # Registry + selection for parallel-test-runner adapters. An adapter is
-  # a class (used as a singleton, never instantiated) answering the
-  # `_Adapter` contract; subclass `ParallelAdapters::Base` to inherit
-  # no-op defaults. Register custom adapters via
-  # `SimpleCov::ParallelAdapters.register MyRunnerAdapter`.
   module ParallelAdapters
-    # The class-level contract an adapter must answer. `singleton(Base)`
-    # and its subclasses satisfy this structurally.
     interface _Adapter
       def active?: () -> boolish
 
@@ -1621,93 +1607,51 @@ module SimpleCov
       def expected_worker_count: () -> Integer
     end
 
-    # Registry state. Declared on both the instance and singleton sides
-    # because `module_function` bodies type-check as instance methods
-    # while runtime state lives on the module itself.
     @adapters: Array[_Adapter]?
 
     self.@adapters: Array[_Adapter]?
 
-    # Memoized current adapter. Distinguishes "not yet computed" (ivar
-    # undefined) from "computed, no adapter active" (nil), hence the
-    # `defined?` guard in the implementation.
     @current: _Adapter?
 
     self.@current: _Adapter?
 
-    # Adapters in selection order: user-registered adapters first, then
-    # ParallelTestsAdapter, then GenericAdapter.
     def self?.adapters: () -> Array[_Adapter]
 
-    # Registers a custom adapter at the front of the selection list and
-    # returns it. Clears the memoized `current` selection.
     def self?.register: (_Adapter adapter) -> _Adapter
 
-    # The first registered adapter whose `active?` returns true, or nil
-    # when no recognized parallel runner is active (single-worker run).
     def self?.current: () -> _Adapter?
 
-    # Clears the memoized `current` selection (primarily for tests that
-    # mutate env vars between examples).
     def self?.reset_current!: () -> void
   end
 end
 
-# ----- parallel_adapters/base -----
 
 module SimpleCov
   module ParallelAdapters
-    # No-op defaults for a parallel-test-runner adapter: behave like a
-    # single-process run. Real adapters subclass and override what they
-    # need. The contract methods are class methods; adapters are never
-    # instantiated.
     class Base
-      # Should this adapter be selected for the current process? The
-      # first registered adapter whose `active?` returns truthy wins.
       def self.active?: () -> boolish
 
-      # Should THIS worker do the final-result work (wait for siblings,
-      # merge resultsets, run threshold checks, format the report)?
-      # Defaults to true for the single-process case.
       def self.first_worker?: () -> bool
 
-      # Optional: block until sibling workers have finished writing
-      # their resultsets. The no-op default leaves synchronization to
-      # SimpleCov's resultset polling fallback.
       def self.wait_for_siblings: () -> void
 
-      # Does `wait_for_siblings` block until every sibling process has
-      # exited? When true, a settled resultset count below
-      # `expected_worker_count` is accepted as final.
       def self.native_wait?: () -> boolish
 
-      # How many parallel workers participate in this run. Defaults to 1.
       def self.expected_worker_count: () -> Integer
 
-      # The user's explicit `SimpleCov.parallel_tests false` opt-out.
       def self.forced_off?: () -> bool
 
-      # Shared PARALLEL_TEST_GROUPS parsing; 1 for unset, empty,
-      # non-numeric, or non-positive values.
       def self.parallel_test_groups_count: () -> Integer
     end
   end
 end
 
-# ----- parallel_adapters/generic -----
 
 module SimpleCov
   module ParallelAdapters
-    # Catch-all adapter for runners that follow the `TEST_ENV_NUMBER` /
-    # `PARALLEL_TEST_GROUPS` env-var convention without shipping a Ruby
-    # API (parallel_rspec, knapsack-style splitters, custom CI sharding).
-    # Activates when `TEST_ENV_NUMBER` is set, unless
-    # `SimpleCov.parallel_tests false` opted out.
     class GenericAdapter < Base
       def self.active?: () -> bool
 
-      # First worker is TEST_ENV_NUMBER "" (parallel_tests convention)
-      # or "1" (runners that number from 1).
       def self.first_worker?: () -> bool
 
       def self.expected_worker_count: () -> Integer
@@ -1715,32 +1659,20 @@ module SimpleCov
   end
 end
 
-# ----- parallel_adapters/parallel_tests -----
 
 module SimpleCov
   module ParallelAdapters
-    # Adapter for grosser/parallel_tests. Requires the full native
-    # coordination contract (ParallelTests constant loaded,
-    # TEST_ENV_NUMBER and PARALLEL_PID_FILE set); env-var-only setups
-    # fall through to GenericAdapter.
     class ParallelTestsAdapter < Base
       def self.active?: () -> bool
 
-      # Delegates to ParallelTests.first_process? (the first started
-      # process does the final-result work; see issue #922).
       def self.first_worker?: () -> bool
 
-      # Uses ParallelTests.wait_for_other_processes_to_finish when the
-      # pid-file contract is present.
       def self.wait_for_siblings: () -> void
 
       def self.native_wait?: () -> bool
 
       def self.expected_worker_count: () -> Integer
 
-      # Auto-requires parallel_tests when installed and the env vars it
-      # sets are present; a missing gem is treated as "not using
-      # parallel_tests" (see issue #1018).
       def self.ensure_loaded: () -> void
 
       def self.env_suggests_parallel_tests?: () -> bool
@@ -1750,28 +1682,29 @@ module SimpleCov
   end
 end
 
-# ----- deprecation -----
 
 module SimpleCov
-  # Emits legacy-API deprecation warnings, deduplicated by the source
-  # location that triggered them (see issue #1204).
   module Deprecation
-    # Warns about a deprecated API at most once per call-site location.
-    # `message` is the notice without the `[DEPRECATION]` tag or location
-    # prefix; `location` defaults to the caller of the deprecated method.
+    MODES: Array[Symbol]
+
+    def self?.mode: () -> Symbol
+
+    def self?.mode=: (Symbol mode) -> Symbol
+
     def self?.warn: (String message, ?location: String?) -> void
 
-    # Dedup keys (locations, or messages when no backtrace is available)
-    # already emitted by this process. Declared on both the instance and
-    # singleton sides because `module_function` bodies type-check as
-    # instance methods while runtime state lives on the module itself.
+    def self?.caller_location: () -> String?
+
     @emitted: Set[String]?
 
     self.@emitted: Set[String]?
 
+    @mode: Symbol?
+
+    self.@mode: Symbol?
+
     def self?.emitted: () -> Set[String]
 
-    # @api private — reset emitted state between tests.
     def self?.reset!: () -> void
   end
 end