ultra-pro-pkg 0.0.1

data/simplecov-1.0.0/README.md

@@ -0,0 +1,1524 @@
+SimpleCov [![Gem Version](https://badge.fury.io/rb/simplecov.svg)](https://badge.fury.io/rb/simplecov) [![Build Status](https://github.com/simplecov-ruby/simplecov/actions/workflows/stable.yml/badge.svg?branch=main)][Continuous Integration] [![Lint](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/lint.yml) [![Typecheck](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml/badge.svg?branch=main)](https://github.com/simplecov-ruby/simplecov/actions/workflows/typecheck.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/c071d197d61953a7e482/maintainability)](https://codeclimate.com/github/simplecov-ruby/simplecov/maintainability)
+=========
+
+**Code coverage for Ruby**
+
+  * [Source Code]
+  * [API documentation]
+  * [Configuration]
+  * [Changelog]
+  * [Rubygem]
+  * [Continuous Integration]
+
+[Coverage]: https://docs.ruby-lang.org/en/master/Coverage.html "API doc for Ruby's Coverage library"
+[Source Code]: https://github.com/simplecov-ruby/simplecov "Source Code @ GitHub"
+[API documentation]: http://rubydoc.info/gems/simplecov/frames "RDoc API Documentation at Rubydoc.info"
+[Configuration]: http://rubydoc.info/gems/simplecov/SimpleCov/Configuration "Configuration options API documentation"
+[Changelog]: https://github.com/simplecov-ruby/simplecov/blob/main/CHANGELOG.md "Project Changelog"
+[Rubygem]: http://rubygems.org/gems/simplecov "SimpleCov @ rubygems.org"
+[Continuous Integration]: https://github.com/simplecov-ruby/simplecov/actions?query=workflow%3Astable "SimpleCov is built around the clock by github.com"
+
+SimpleCov is a code coverage analysis tool for Ruby. It uses [Ruby's built-in Coverage][Coverage] library to gather
+coverage data, but makes processing the results much easier by providing a clean API to filter, group, merge, format,
+and display them — a complete coverage suite you can set up in just a couple of lines.
+
+SimpleCov tracks covered Ruby code; gathering coverage for templating solutions like ERB, Slim, and Haml is not
+supported (though see [Eval coverage](#eval-coverage) for ERB).
+
+In most cases you'll want overall coverage results spanning all of your tests — unit tests, Cucumber features, and so
+on. SimpleCov handles this automatically by caching and merging results as it generates reports, so a report reflects
+coverage across your whole test suite and gives you a truer picture of your blank spots.
+
+SimpleCov bundles two formatters that need no extra gems: the default HTML formatter (which renders the browsable
+report) and a JSON formatter. Both were once separate gems (`simplecov-html` and `simplecov_json_formatter`) but are
+now built into SimpleCov and configured automatically when you launch it.
+
+## Getting started
+
+1. Add SimpleCov to your `Gemfile` and `bundle install`:
+
+    ```ruby
+    gem 'simplecov', require: false, group: :test
+    ```
+
+2. Load and launch SimpleCov **at the very top** of your test helper — `test/test_helper.rb`, `spec/spec_helper.rb`,
+   `rails_helper.rb`, Cucumber's `features/support/env.rb`, or whatever setup file your framework uses. SimpleCov
+   doesn't care which framework you run in; it just watches what code executes and reports on it, so the same two lines
+   work everywhere:
+
+    ```ruby
+    require 'simplecov'
+    SimpleCov.start
+
+    # Previous content of test helper now starts here
+    ```
+
+   > **Important:** `SimpleCov.start` **must** run **before any of your application code is required** — otherwise
+   > SimpleCov (and the underlying Coverage library) can't track those files. This bites hardest with tools that keep
+   > your app loaded between runs, like Spring; see the [Spring section](#using-spring-with-simplecov).
+
+   SimpleCov must run in the process you want to analyze. When you test a server process (e.g. a JSON API) from a
+   separate test process (e.g. via Selenium) and want to see all code the `rails server` executes — not just code in
+   your test files — require SimpleCov in the server process. For Rails, add this near the top of `bin/rails`, below
+   the shebang and after `config/boot` is required:
+
+    ```ruby
+    if ENV['RAILS_ENV'] == 'test'
+      require 'simplecov'
+      SimpleCov.start 'rails'
+    end
+    ```
+
+3. Run your full test suite to see your application's coverage.
+
+4. Open the HTML report in your default browser:
+
+    ```sh
+    simplecov open
+    ```
+
+   (The bundled `simplecov` CLI picks the right opener for your platform — `open` on macOS, `xdg-open` on Linux/BSD,
+   `start` on Windows. Pass `--report PATH` to open a non-default location. See [Command-line interface](#command-line-interface)
+   for the full set of subcommands.)
+
+5. Optionally, keep coverage results out of Git:
+
+    ```sh
+    echo coverage >> .gitignore
+    ```
+
+For Rails applications, SimpleCov ships a built-in `rails` [profile](#profiles) that sets up groups for your
+Controllers, Models, Helpers, and Libraries:
+
+```ruby
+require 'simplecov'
+SimpleCov.start 'rails'
+```
+
+## Example output
+
+**Coverage results report, fully browsable locally with sorting and much more:**
+
+![SimpleCov coverage report](https://github.com/user-attachments/assets/33275385-e0f3-482d-b63e-2a6cd4965fe0)
+
+**Source file coverage details view:**
+
+![SimpleCov source file detail view](https://github.com/user-attachments/assets/abcd93b4-a45d-48bb-a0e4-6129c4429193)
+
+## Configuration
+
+[Configuration] settings can be applied in three equivalent formats:
+
+* Directly in your start block (the most common way):
+
+    ```ruby
+    SimpleCov.start do
+      some_config_option 'foo'
+    end
+    ```
+
+* As direct setters:
+
+    ```ruby
+    SimpleCov.some_config_option 'foo'
+    ```
+
+* In a `configure` block — useful when you don't want to start coverage immediately, or want to add configuration later:
+
+    ```ruby
+    SimpleCov.configure do
+      some_config_option 'foo'
+    end
+    ```
+
+See the [Configuration] API documentation for the full list of options.
+
+### Using `.simplecov` for centralized config
+
+If you merge multiple test-suite results (e.g. RSpec and Cucumber) into a single report, you'd otherwise have to repeat
+your filters / groups / profile in every test helper. To avoid that, place a `.simplecov` file at your project root
+with the shared configuration; each test helper then requires SimpleCov and explicitly starts it:
+
+```ruby
+# .simplecov — configuration only
+SimpleCov.load_profile 'rails'
+SimpleCov.skip 'lib/generators'
+SimpleCov.group 'Models', 'app/models'
+
+# spec/spec_helper.rb
+require 'simplecov'
+SimpleCov.start
+
+# features/support/env.rb
+require 'simplecov'
+SimpleCov.start
+```
+
+This is recommended whenever you merge frameworks that rely on each other, like Cucumber and RSpec.
+
+> [!NOTE]
+> Calling `SimpleCov.start` directly from `.simplecov` is deprecated. Tracking still begins for backward
+> compatibility, but a one-time deprecation warning fires; a future release will require the explicit `SimpleCov.start`
+> from a test helper. Migrating prevents a long-standing bug where `.simplecov` auto-loaded in a Rakefile or Rails'
+> `Bundler.require` would leave an empty parent-process report that overwrites the test subprocess's good one. See
+> [#581](https://github.com/simplecov-ruby/simplecov/issues/581).
+
+### Changing the report location
+
+By default the report ends up in `SimpleCov.root / SimpleCov.coverage_dir`. For out-of-tree build setups
+(CMake/CTest, Bazel, etc.) — where the build directory is elsewhere on the filesystem and you don't want the report
+under the source root — set `SimpleCov.coverage_path` directly:
+
+```ruby
+SimpleCov.start do
+  root '/source/checkout'
+  coverage_path '/tmp/build/coverage'
+end
+```
+
+Setting `coverage_path` explicitly pins the destination — subsequent changes to `root` or `coverage_dir` don't move
+it. The directory is created if it doesn't already exist.
+
+### Running coverage only on demand
+
+The Ruby STDLIB Coverage library is *very* fast (on a ~10-minute Rails suite the slowdown is only a couple of seconds),
+so SimpleCov's policy is to generate coverage on every run — it costs you almost nothing and you always have the latest
+results. There's therefore no built-in on-demand switch, but you can add one with an `ENV` conditional:
+
+```ruby
+SimpleCov.start if ENV["COVERAGE"]
+```
+
+Then coverage runs only when you ask for it:
+
+```sh
+COVERAGE=true rake test
+```
+
+### Migrating from the legacy configuration API
+
+The configuration API was redesigned to use a smaller set of consistent verbs. The legacy methods continue to work but
+emit deprecation warnings that name their replacement; the table below is the canonical migration map.
+
+| Legacy                              | New                              | Notes                                                                                                                  |
+|-------------------------------------|----------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| `add_filter "lib/legacy"`           | `skip "lib/legacy"`              | Identical matcher grammar (string = path-segment substring; Regexp; block; Array). No behavior change.                 |
+| `add_group "Models", "app/models"`  | `group "Models", "app/models"`   | Identical matcher grammar. No behavior change.                                                                         |
+| `track_files "lib/**/*.rb"`         | `cover "lib/**/*.rb"`            | `cover` includes unloaded files (the legacy `track_files` behavior) **and** restricts the report to the matching set. To keep the old additive-only behavior, pass every directory you want reported: `cover "lib/**/*.rb", "app/**/*.rb"`. |
+| `use_merging false`                 | `merging false`                  | Same value, same behavior.                                                                                             |
+| `enable_for_subprocesses true`      | `merge_subprocesses true`        | Same value, same behavior.                                                                                             |
+| `enable_coverage_for_eval`          | `enable_coverage :eval`          | Eval coverage now folds into the same call you use to enable `:line`/`:branch`/`:method`: `enable_coverage :branch, :eval`. |
+| `print_error_status` (reader)       | `print_errors`                   | Reader only. The `print_error_status=` writer still works without a warning, but `print_errors true`/`print_errors false` is the new spelling. |
+| `minimum_coverage_by_file line: 70, 'app/x.rb' => 100` | `coverage(:line) { minimum_per_file 70; minimum_per_file 100, only: 'app/x.rb' }` | The `coverage` block fixes the criterion, so per-path overrides are plain percentages with an `only:` target instead of a hash mixing Symbol / String / Regexp keys. See [Per-criterion thresholds](#per-criterion-thresholds-with-coverage). |
+| `minimum_coverage_by_group 'Models' => { line: 90 }` | `coverage(:line) { minimum_per_group 90, only: 'Models' }` | Same uniform shape as `minimum_per_file`. |
+
+Brand-new in the redesigned API (no legacy method to migrate from):
+
+| Method                              | Purpose                                                                                                                  |
+|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `cover "lib/**/*.rb"`               | Positive scope (allowlist). Multiple calls union; strings are globs. See above for the relationship with `track_files`.  |
+| `no_default_skips`                  | Clear every previously-installed filter — defaults and anything earlier in the block — so subsequent `skip`s start clean.|
+| `formatter false` / `formatters []` | Opt out of formatting entirely. Workers in big parallel CI runs only need their `.resultset.json` for a final `SimpleCov.collate` step; skipping the formatter saves the per-job HTML / multi-formatter overhead. See [#964](https://github.com/simplecov-ruby/simplecov/issues/964). |
+| `parallel_tests true` / `false`     | Force on / off the auto-require of the `parallel_tests` gem. Default (unset) auto-detects from `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` and silently skips if the gem isn't installed. Set explicitly when you use those env vars for unrelated subprocess coordination. See [#1018](https://github.com/simplecov-ruby/simplecov/issues/1018). |
+
+Example before/after:
+
+```ruby
+# Before
+SimpleCov.start do
+  add_filter "/test/"
+  add_filter %r{\Aconfig/}
+  add_group "Models", "app/models"
+  track_files "lib/**/*.rb"
+  enable_coverage_for_eval
+  use_merging true
+  enable_for_subprocesses true
+end
+
+# After
+SimpleCov.start do
+  skip "/test/"
+  skip %r{\Aconfig/}
+  group "Models", "app/models"
+  cover "lib/**/*.rb"
+  enable_coverage :eval
+  merging true
+  merge_subprocesses true
+end
+```
+
+## Coverage criteria
+
+Line coverage is on by default. You can additionally enable branch, method, oneshot-line, and eval coverage, and choose
+which criterion leads the report.
+
+### Disabling line coverage
+
+If you want a branch-only or method-only run (e.g. you find the line numbers noisy in CI and only care about whether
+each conditional was exercised), enable the criterion you want and then disable line coverage:
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  disable_coverage :line
+end
+```
+
+If you disable every criterion, `SimpleCov.start` raises `SimpleCov::ConfigurationError` — at least one of `:line`,
+`:branch`, or `:method` must remain enabled.
+
+### Branch coverage
+
+Branch coverage records whether each branch of a condition executed, not just whether a line ran.
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+end
+```
+
+It's handy for one-line conditionals:
+
+```ruby
+number.odd? ? "odd" : "even"
+```
+
+Line coverage always marks this line as executed, but never tells you whether both arms were taken. Guard clauses have
+the same story:
+
+```ruby
+return if number.odd?
+
+# more code
+```
+
+If the whole method is covered you still won't know whether the guard ever triggered — line coverage just sees the
+condition evaluated.
+
+In the HTML report, lines are annotated as `branch_type: hit_count`:
+
+* `then: 2` — the `then` branch (of an `if`) was executed twice
+* `else: 0` — the `else` branch (of an `if` or `case`) was never executed
+
+Even if you don't write an `else` branch, it still shows up: a missed implicit `else` means the `if` condition was
+never false, or no `when` of a `case` matched.
+
+**Is branch coverage strictly better?** No. Branch coverage only concerns itself with conditionals — coverage of
+sequential code is of no interest to it. A file with no conditional logic has no branch data, and SimpleCov reports its
+0-of-0 branches as 100% (everything coverable was covered). So look at both metrics together: missing 10% of your lines
+might account for 50% of your branches.
+
+#### Ignoring implicit `else` branches
+
+Ruby's `Coverage` library reports an `:else` branch for several constructs even when the source has no literal `else`
+keyword — exhaustive `case/in` pattern matches, `case/when` without an `else` arm, `||=` / `&&=`, and `if` / `unless`
+without an `else`. Those synthetic branches show up as missed and depress the branch-coverage percentage despite there
+being no code to test. If your style relies on exhaustive pattern matching (or you just want `||=` to stop tanking
+coverage), opt out:
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  ignore_branches :implicit_else
+end
+```
+
+`ignore_branches` is variadic; `:implicit_else` and `:eval_generated` (below) are the supported tokens. Calling it
+before (or without) `enable_coverage :branch` is harmless: the setting is stored and applies once branch coverage is
+enabled. Explicit `else` arms still count.
+
+#### Ignoring eval-generated branches and methods
+
+Rails' `delegate` (and other macros that call `module_eval(body, __FILE__, __LINE__)`) make Ruby's `Coverage` library
+attribute the eval'd code to the macro's source line. The result is a `delegate :foo, to: :bar` line that surfaces in
+the report as if it had its own `def foo` and an `if` branch — both reported as missed when the delegated method isn't
+called from the suite. Drop those synthetic entries:
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  enable_coverage :method
+  ignore_branches :eval_generated
+  ignore_methods :eval_generated
+end
+```
+
+`ignore_methods` is variadic; `:eval_generated` is the only supported token. Both filters detect eval-generated entries
+by walking the static source with [Prism](https://github.com/ruby/prism) and dropping any Coverage entry whose start
+line lacks a real `def` keyword (for methods) or branch construct (for branches). Prism is bundled with Ruby 3.3+; on
+older Rubies `gem install prism` enables the filter, otherwise it's a silent no-op. Real `def`s and branches that share
+a line with an eval-generated entry are kept (line-presence is the matcher).
+
+### Oneshot lines coverage
+
+Oneshot lines coverage is a faster alternative to line coverage.
+
+Traditional coverage records *how many times* each line ran. Often it's enough to know *whether* each line ran at
+least once — and the counting just adds overhead. Oneshot coverage records only the first execution of each line; the
+hook for each line fires once, after which the program runs with zero overhead.
+
+```ruby
+SimpleCov.start do
+  enable_coverage :oneshot_line
+  primary_coverage :oneshot_line
+end
+```
+
+### Eval coverage
+
+You can measure coverage for code evaluated by `Kernel#eval`. Supported in CRuby 3.2+.
+
+```ruby
+SimpleCov.start do
+  enable_coverage :eval
+end
+```
+
+This is typically useful for ERB. Set `ERB#filename=` so SimpleCov can trace the original `.erb` source file.
+
+### Primary coverage
+
+By default the primary coverage type is `line`. The primary type determines what comes first in all output, and which
+type is checked when you customize exit behavior without naming a type (e.g. `SimpleCov.minimum_coverage 90`). To change
+it:
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  primary_coverage :branch
+end
+
+# or, outside a block:
+SimpleCov.primary_coverage :branch
+```
+
+Coverage must first be enabled for non-default types.
+
+## Filters
+
+Filters remove selected files from your coverage data.
+
+### Default filters
+
+`SimpleCov.start` loads four filters out of the box:
+
+* **`root_filter`** — drops every file outside of `SimpleCov.root`, so you don't end up with coverage reports for the
+  source files of every gem in your bundle. (See [Covering files outside the root](#covering-files-outside-the-root).)
+* **`bundler_filter`** — drops `/vendor/bundle/` (in case a project keeps its gems checked into the repo).
+* **`hidden_filter`** — drops any path that starts with a dot, matching the regex `/\A\..*/`. This is what hides
+  `.bundle/`, `.semaphore-cache/`, and similar dotfile directories — but it also hides legitimate top-level directories
+  like `.scripts/`. If you keep code in such a directory, remove this filter (see below).
+* **`test_frameworks`** — drops common test directories (`test/`, `spec/`, `features/`, `autotest/`), matching the
+  regex `%r{\A(test|features|spec|autotest)/}`. Running the test suite always executes 100% of the test files
+  themselves, which inflates the overall percentage and obscures application coverage. Remove this filter if you
+  prefer to see test files in the report (e.g. to surface dead helpers).
+
+For a clean slate (no defaults at all), `require 'simplecov/no_defaults'` *before* `require 'simplecov'`, or call
+`SimpleCov.clear_filters` from your config block. To drop a specific default while keeping the others, use
+`remove_filter`:
+
+```ruby
+SimpleCov.start do
+  remove_filter(/\A\..*/) # restore coverage for .scripts/, .tooling/, etc.
+end
+```
+
+`remove_filter` matches by value, so pass back the same `String` or `Regexp` the default profile used. For filters
+added with a block, pass the same `Proc` object you originally handed to `skip`.
+
+### Defining custom filters
+
+Define your own filters to remove configuration files, tests, or anything else you don't need in the report. A filter
+can be a String or Regexp (Regexp-matched against each source file's path), a block, your own Filter class, or an array
+of any of these.
+
+#### String filter
+
+```ruby
+SimpleCov.start do
+  skip "/test/"
+end
+```
+
+Removes all files whose path matches "/test/".
+
+#### Regex filter
+
+```ruby
+SimpleCov.start do
+  skip %r{^/test/}
+end
+```
+
+Removes all files whose path starts with /test/.
+
+#### Block filter
+
+```ruby
+SimpleCov.start do
+  skip do |source_file|
+    source_file.lines.count < 5
+  end
+end
+```
+
+Block filters receive a `SimpleCov::SourceFile` and return `true` to remove the file or `false` to keep it. (See the
+RDoc for `SimpleCov::SourceFile` for the available methods.) The example above removes files with fewer than 5 lines.
+
+#### Custom filter class
+
+```ruby
+class LineFilter < SimpleCov::Filter
+  def matches?(source_file)
+    source_file.lines.count < filter_argument
+  end
+end
+
+SimpleCov.skip LineFilter.new(5)
+```
+
+Inherit from `SimpleCov::Filter` and define `matches?(source_file)`; a `true` return removes the file. The
+`filter_argument` is set in the `SimpleCov::Filter` initializer — `5` in this example.
+
+#### Array filter
+
+```ruby
+SimpleCov.start do
+  proc = Proc.new { |source_file| false }
+  skip ["string", /regex/, proc, LineFilter.new(5)]
+end
+```
+
+Pass an array containing any of the other filter types.
+
+### Ignoring/skipping code
+
+Disable coverage for a span of code with `# simplecov:disable` and `# simplecov:enable` comments. The available
+categories are `line`, `branch`, and `method`; combine them with commas, and omit them to target all three. Anything
+trailing the directive is treated as a free-form reason and ignored — no separator is required, though `--` or any
+other marker is fine if you prefer one.
+
+```ruby
+# simplecov:disable line
+def skipped_lines
+  never_reached
+end
+# simplecov:enable line
+
+# simplecov:disable branch, method legacy adapter, scheduled for removal
+class LegacyAdapter
+  def call(value)
+    value ? :yes : :no
+  end
+end
+# simplecov:enable
+
+raise "absurd" # simplecov:disable
+```
+
+Inline directives (trailing real code) only affect the line they sit on. Block directives sit on their own line and
+remain in effect until the matching `# simplecov:enable` for the same category — or end of file if never closed.
+Directive markers inside string literals or heredocs are ignored.
+
+> [!WARNING]
+> The older `# :nocov:` toggle still works but is **deprecated** and will be removed in a future release. Each file
+> that uses it emits a one-time deprecation warning pointing at the recommended `# simplecov:disable` /
+> `# simplecov:enable` replacement. The configurable token name (`SimpleCov.nocov_token`) is similarly deprecated.
+
+> [!NOTE]
+> You shouldn't have to skip private methods that are included in your coverage. If you appropriately test the public
+> interface of your classes and objects, you should automatically get full coverage of your private methods.
+
+### How `cover` and `skip` interact
+
+`cover` and `skip` operate on different sides of the same chain. `skip` (and its deprecated `add_filter` alias) drops
+matching files from the report. `cover` declares a positive scope that restricts the final report to files matching at
+least one `cover` matcher.
+
+Order: `skip` runs first, then `cover`. A file matched by any `skip` filter is dropped before `cover` is consulted, so
+a file matched by both is dropped, not kept. The two are not commutative.
+
+```ruby
+SimpleCov.start do
+  cover "{app,lib}/**/*.rb"
+  skip  "app/legacy"
+end
+```
+
+That config covers `app/` and `lib/`, then drops `app/legacy/`. With only `cover` and no overlapping `skip`, every
+configured default filter (hidden files, vendored gems, test directories) still applies — `cover` doesn't bypass them.
+Use `no_default_skips` to opt out of the defaults wholesale before adding your own.
+
+`cover` also expands string-glob matchers on disk so files that exist but were never `require`'d during the run still
+appear in the report (at 0% coverage). Regexp and Proc cover matchers don't trigger disk discovery — they only filter
+the universe of files that Ruby's `Coverage` library reported.
+
+### Covering files outside the root
+
+The `root_filter` drops every file outside of `SimpleCov.root` from the raw coverage data before any other filters or
+groups run, so paths you might want to track (a Rails Engine installed as a gem, sibling directories in a Docker
+layout, etc.) never reach your filter chain. To include them, widen `SimpleCov.root` to a directory that contains both
+the project and the extra paths — `'/'` works when there's no useful common ancestor — and then express the
+inclusion/exclusion as filters or groups:
+
+```ruby
+SimpleCov.root '/'
+SimpleCov.start :rails do
+  skip { |src| !src.filename.start_with?(Rails.root.to_s, '/path/to/my_engine') }
+end
+```
+
+## Groups
+
+Separate your source files into groups — for example, a Rails app might list Models, Controllers, Helpers, and Libs
+separately. Group definition works like filters (and also accepts custom filter classes), but a source file ends up in
+a group when the filter *passes* (returns `true`), as opposed to being excluded from results when a filter returns
+`true`.
+
+```ruby
+SimpleCov.start do
+  group "Models", "app/models"
+  group "Controllers", "app/controllers"
+  group "Long files" do |src_file|
+    src_file.lines.count > 100
+  end
+  group "Multiple Files", ["app/models", "app/controllers"] # You can also pass in an array
+  group "Short files", LineFilter.new(5) # Using the LineFilter class defined in the Filters section above
+end
+```
+
+## Profiles
+
+By default, SimpleCov's only assumption is that you want coverage for files inside your project root. To avoid
+repetitive configuration, you can use predefined blocks of configuration called 'profiles', or define your own. Pass a
+profile's name as the first argument to `SimpleCov.start`.
+
+SimpleCov bundles a `rails` profile that looks roughly like this:
+
+```ruby
+SimpleCov.profiles.define 'rails' do
+  skip '/test/'
+  skip '/config/'
+
+  group 'Controllers', 'app/controllers'
+  group 'Models', 'app/models'
+  group 'Helpers', 'app/helpers'
+  group 'Libraries', 'lib'
+end
+```
+
+It's just a `SimpleCov.configure` block. Launch it from your test helper, optionally adding more config:
+
+```ruby
+SimpleCov.start 'rails'
+
+# or
+
+SimpleCov.start 'rails' do
+  # additional config here
+end
+```
+
+### The `strict` profile
+
+For projects that have already reached full coverage (or want to ratchet up to it), the bundled `strict` profile
+enables line, branch, and method coverage and pins each minimum threshold at 100%:
+
+```ruby
+SimpleCov.start 'strict'
+```
+
+That's equivalent to:
+
+```ruby
+SimpleCov.start do
+  enable_coverage :branch
+  enable_coverage :method
+  enable_coverage :eval if Coverage.respond_to?(:supported?) && Coverage.supported?(:eval)
+  minimum_coverage line: 100, branch: 100, method: 100
+end
+```
+
+The profile drops the branch / method clauses on engines that don't support those criteria (JRuby), so it still loads
+cleanly there, enforcing line coverage at 100%. `:eval` is included on Ruby 3.2+ (where the runtime supports it), so
+any code reached through `Kernel#eval` — typically ERB templates with `ERB#filename=` set — is held to the same 100%
+bar. On older Rubies, the `:eval` clause is silently skipped.
+
+### Custom profiles
+
+Load additional profiles with `SimpleCov.load_profile('xyz')`. This lets you build on an existing profile and reuse
+it across unit tests and Cucumber features:
+
+```ruby
+# lib/simplecov_custom_profile.rb
+require 'simplecov'
+SimpleCov.profiles.define 'myprofile' do
+  load_profile 'rails'
+  skip 'vendor' # Don't include vendored stuff
+end
+
+# features/support/env.rb
+require 'simplecov_custom_profile'
+SimpleCov.start 'myprofile'
+
+# test/test_helper.rb
+require 'simplecov_custom_profile'
+SimpleCov.start 'myprofile'
+```
+
+### Profile plugin gems
+
+If `SimpleCov.start "<name>"` doesn't find a profile registered under `<name>`, the bundled profile loader tries to
+autoload one in two steps: first `require "simplecov/profiles/<name>"` (where bundled profiles like `rails` and
+`strict` live), then `require "simplecov-profile-<name>"` (the conventional name for a third-party plugin gem). Either
+require is expected to call `SimpleCov.profiles.define "<name>" do ... end` so the registered block can be applied. If
+both requires fail or neither registers the profile, `SimpleCov.start` raises `SimpleCov::ConfigurationError`.
+
+To publish your own profile as a gem, name it `simplecov-profile-<name>` and have its main file call
+`SimpleCov.profiles.define`:
+
+```ruby
+# In a gem named simplecov-profile-myteam
+SimpleCov.profiles.define "myteam" do
+  enable_coverage :branch
+  cover "{app,lib}/**/*.rb"
+  skip  "app/legacy"
+end
+```
+
+A user who adds the gem to their Gemfile can then `SimpleCov.start "myteam"` without explicitly requiring it.
+
+## Merging results and parallel tests
+
+You normally want coverage analyzed across ALL of your test suites at once. SimpleCov automatically caches results in
+`(coverage_path)/.resultset.json` and merges them with subsequent runs — or overrides them, depending on whether it
+considers a subsequent run a different test suite or the same one. To make that distinction, SimpleCov uses the concept
+of **test suite names**.
+
+### Test suite names
+
+SimpleCov guesses the running suite's name from the shell command that started the tests. This works fine for Test::Unit,
+RSpec, and Cucumber; if it fails, it falls back to the invoking shell command as the command name.
+
+For a non-standard setup, give SimpleCov a cue with `SimpleCov.command_name` in one test file per suite (you only need
+it once per suite — even with 200 unit test files, setting it in one is enough):
+
+```ruby
+# test/unit/some_test.rb
+SimpleCov.command_name 'test:units'
+
+# test/functionals/some_controller_test.rb
+SimpleCov.command_name "test:functionals"
+
+# test/integration/some_integration_test.rb
+SimpleCov.command_name "test:integration"
+
+# features/support/env.rb
+SimpleCov.command_name "features"
+```
+
+**If multiple suites resolve to the same `command_name`, their results clobber each other instead of merging.**
+SimpleCov detects unique names for the most common setups, but if you have more than one suite that doesn't follow a
+common pattern, ensure each gets a unique `command_name`.
+
+When running tests in parallel, each process can clobber the others' results. With the default `command_name`,
+SimpleCov detects and avoids collisions based on `ENV['PARALLEL_TEST_GROUPS']` and `ENV['TEST_ENV_NUMBER']`. If your
+runner sets neither, *you must* set a `command_name` that's unique per process (e.g. `command_name "Unit Tests PID #{$$}"`).
+With parallel_tests specifically, incorporate `TEST_ENV_NUMBER` into the name yourself so results merge correctly:
+
+```ruby
+# spec/spec_helper.rb
+SimpleCov.command_name "features" + (ENV['TEST_ENV_NUMBER'] || '')
+```
+
+The HTML report prints the test suites it used in its footer.
+
+### Merging within one execution environment
+
+Results are automatically merged with previous runs in the same execution environment when the report is generated, so
+once coverage is set up for Cucumber and your unit / functional / integration tests, all of those suites feed into one
+report.
+
+Cached coverage data eventually goes stale, so result sets older than `SimpleCov.merge_timeout` are dropped from the
+merge. The default is 600 seconds (10 minutes); raise or lower it with `SimpleCov.merge_timeout 3600` (1 hour), or
+`merge_timeout 3600` inside a configure/start block. Deactivate automatic merging entirely with `SimpleCov.merging false`.
+
+In a parallel run, the process that writes the final report waits for the other workers to finish and write their
+result sets before merging. It gives up after `SimpleCov.parallel_wait_timeout` seconds (default 60) and reports
+whatever has arrived, skipping the minimum / maximum coverage checks against that partial total. If one worker runs
+much heavier test files and routinely finishes a minute or more after the others, raise it with
+`SimpleCov.parallel_wait_timeout 180` so its coverage is included.
+
+### Merge finalization ownership
+
+`SimpleCov.merging true` stores each process' resultset so it can be merged with other suites or workers. By default,
+SimpleCov also owns **finalizing** that merge: waiting for sibling workers, building the merged result, formatting the
+report, enforcing minimum / maximum coverage, and writing `.last_run.json`.
+
+Some parallel runners intentionally write each worker's resultset to a separate coverage directory and then run an
+explicit cleanup step with `SimpleCov.collate`. In that setup, workers should still store their resultsets, but the
+cleanup task owns finalization:
+
+```ruby
+# spec/spec_helper.rb
+SimpleCov.start do
+  if ENV["TEST_ENV_NUMBER"]
+    merging true
+    coverage_dir "coverage/turbo_tests/#{ENV["TEST_ENV_NUMBER"]}"
+    command_name "rspec-#{ENV["TEST_ENV_NUMBER"]}"
+    finalize_merge false
+  end
+end
+```
+
+```ruby
+# Rakefile
+task "coverage:collate" do
+  require "simplecov"
+
+  SimpleCov.collate Dir["coverage/turbo_tests/*/.resultset.json"] do
+    coverage(:line) { minimum 100 }
+    coverage(:branch) { minimum 100 }
+  end
+end
+```
+
+When `finalize_merge false`, the worker writes its `.resultset.json` and exits without waiting for siblings, formatting,
+checking thresholds, or writing `.last_run.json`. The `SimpleCov.collate` process is the finalizer and performs those
+steps for the merged result.
+
+For compatibility, SimpleCov infers `finalize_merge false` and prints a configuration warning only when all of these are
+true: a recognized parallel adapter is active, more than one worker is expected, merging is enabled, the coverage
+destination was explicitly changed from the default, and the process has parallel-worker environment variables. Set
+`SimpleCov.finalize_merge false` to keep external collation ownership without the warning, or
+`SimpleCov.finalize_merge true` if the selected worker should own the built-in wait / merge / report flow even with a
+custom coverage destination.
+
+### Merging across execution environments
+
+If your tests run in parallel across multiple build machines, download each run's `.resultset.json` and merge them into
+a single result set with `SimpleCov.collate`:
+
+```ruby
+# lib/tasks/coverage_report.rake
+namespace :coverage do
+  desc "Collates all result sets generated by the different test runners"
+  task :report do
+    require 'simplecov'
+
+    SimpleCov.collate Dir["simplecov-resultset-*/.resultset.json"]
+  end
+end
+```
+
+`SimpleCov.collate` also takes an optional profile and an optional configuration block, just like `SimpleCov.start` or
+`SimpleCov.configure`. This means you can configure a separate formatter for the collated output — for instance, use the
+plain `SimpleCov::Formatter::SimpleFormatter` in each worker's `SimpleCov.start` and reserve heavier formatters for the
+final `SimpleCov.collate` run:
+
+```ruby
+# spec/spec_helper.rb
+require 'simplecov'
+
+SimpleCov.start 'rails' do
+  # Disambiguates individual test runs
+  command_name "Job #{ENV["TEST_ENV_NUMBER"]}" if ENV["TEST_ENV_NUMBER"]
+
+  if ENV['CI']
+    formatter SimpleCov::Formatter::SimpleFormatter
+  else
+    formatter SimpleCov::Formatter::MultiFormatter.new([
+      SimpleCov::Formatter::SimpleFormatter,
+      SimpleCov::Formatter::HTMLFormatter
+    ])
+  end
+
+  cover "{app,lib}/**/*.rb"
+end
+```
+
+```ruby
+# lib/tasks/coverage_report.rake
+namespace :coverage do
+  task :report do
+    require 'simplecov'
+
+    SimpleCov.collate Dir["simplecov-resultset-*/.resultset.json"], 'rails' do
+      formatter SimpleCov::Formatter::MultiFormatter.new([
+        SimpleCov::Formatter::SimpleFormatter,
+        SimpleCov::Formatter::HTMLFormatter
+      ])
+    end
+  end
+end
+```
+
+### Forked subprocesses
+
+`SimpleCov.merge_subprocesses true` lets SimpleCov observe subprocesses started with `Process.fork`. It wraps Ruby's
+`Process.fork` so SimpleCov can see into the child, appending `" (subprocess #{pid})"` to the `command_name`, with
+results that merge back together. Configure the child with `.at_fork`:
+
+```ruby
+SimpleCov.merge_subprocesses true
+SimpleCov.at_fork do |pid|
+  # This needs a unique name so it won't be overwritten
+  SimpleCov.command_name "#{SimpleCov.command_name} (subprocess: #{pid})"
+  # be quiet, the parent process will be in charge of output and checking coverage totals
+  SimpleCov.print_errors false
+  SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter
+  SimpleCov.minimum_coverage 0
+  # start
+  SimpleCov.start
+end
+```
+
+SimpleCov must already be started before `Process.fork` is called.
+
+> [!NOTE]
+> The bundled `rails` profile turns this on automatically, so `ActiveSupport::TestCase.parallelize(workers: ...)`
+> worker forks contribute to the merged report instead of being silently dropped.
+
+#### Spawned subprocesses
+
+You can also cover a Ruby script you launch with `PTY.spawn`, `Open3.popen`, `Process.spawn`, and the like. Add a
+`.simplecov_spawn.rb` file to your project root:
+
+```ruby
+# .simplecov_spawn.rb
+require 'simplecov' # this will also pick up whatever config is in .simplecov,
+                    # so ensure it just contains configuration and doesn't call SimpleCov.start.
+SimpleCov.command_name 'spawn' # As this isn't for a test runner directly, the script has no pre-defined base command_name
+SimpleCov.at_fork.call(Process.pid) # Use the per-process setup described above
+SimpleCov.start # only now can we start
+```
+
+Then, instead of spawning your script directly:
+
+```ruby
+PTY.spawn('my_script.rb') do # ...
+```
+
+use `ruby -r` to require the spawn file first:
+
+```ruby
+PTY.spawn('ruby -r./.simplecov_spawn my_script.rb') do # ...
+```
+
+### Parallel-test-runner adapters
+
+SimpleCov coordinates with parallel test runners through a small pluggable adapter interface
+(`SimpleCov::ParallelAdapters`). Two adapters ship out of the box:
+
+- **`ParallelTestsAdapter`** — wraps the [grosser/parallel_tests](https://github.com/grosser/parallel_tests) gem and
+  uses its `ParallelTests.first_process?` / `ParallelTests.wait_for_other_processes_to_finish` APIs for precise worker
+  coordination. Activates only when the native `parallel_tests` pid-file contract is present.
+- **`GenericAdapter`** — catch-all for any runner that follows the `TEST_ENV_NUMBER` / `PARALLEL_TEST_GROUPS` env-var
+  convention but doesn't ship a Ruby API (parallel_rspec, knapsack-style splitters, custom CI sharding scripts).
+  Activates when `TEST_ENV_NUMBER` is set and no more-specific adapter is.
+
+Adapters are tried in registration order; the first whose `active?` returns `true` is chosen. With both built-ins, this
+means parallel_tests users get the precise gem-based path and parallel_rspec (or any env-var-only runner) gets the
+polling-based fallback without any configuration change. See [#1065](https://github.com/simplecov-ruby/simplecov/issues/1065).
+
+#### Registering a custom adapter
+
+If you use a parallel runner with different env vars or its own synchronization API, define a class that inherits from
+`SimpleCov::ParallelAdapters::Base` and register it:
+
+```ruby
+# In your spec_helper.rb / test_helper.rb (before SimpleCov.start)
+class MyRunnerAdapter < SimpleCov::ParallelAdapters::Base
+  def self.active?
+    !ENV["MY_RUNNER_PID"].nil?
+  end
+
+  def self.first_worker?
+    ENV["MY_RUNNER_PID"].to_i == 1
+  end
+
+  def self.wait_for_siblings
+    MyRunner.barrier!   # if your runner provides a sync primitive
+  end
+
+  def self.expected_worker_count
+    ENV["MY_RUNNER_WORKERS"].to_i
+  end
+end
+
+SimpleCov::ParallelAdapters.register MyRunnerAdapter
+```
+
+Custom adapters are inserted at the front of the selection chain, so they take precedence over the built-ins. `Base`
+provides safe no-op defaults for any method you don't override (single-process semantics: `active?` returns `false`,
+`first_worker?` returns `true`, etc.).
+
+## Coverage thresholds and exit behavior
+
+Define what SimpleCov does when your test suite finishes by customizing the `at_exit` hook. The default is shown below;
+do whatever you like instead:
+
+```ruby
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+end
+```
+
+The threshold settings below make SimpleCov exit non-zero when coverage doesn't meet your expectations, so they double
+as CI gates.
+
+### Per-criterion thresholds with `coverage`
+
+The `coverage` block configures each criterion (line, branch, method) the same way: because the criterion is fixed by
+the enclosing block, every threshold value is a plain percentage, so line, branch, and method coverage read identically.
+Naming a criterion also enables it (line is enabled by default).
+
+```ruby
+SimpleCov.start do
+  coverage :line do
+    minimum           90    # suite-wide minimum; SimpleCov exits non-zero if unmet
+    minimum_per_file  80    # per-file minimum
+    minimum_per_file  100, only: "app/mailers/request_mailer.rb"  # per-path override (String path or Regexp)
+    minimum_per_group 95, only: "Models"                          # minimum for a named group
+    maximum_drop      5     # exit non-zero if coverage drops more than 5% between runs
+  end
+
+  coverage :branch, minimum: 80    # one-liner form for a single setting
+  coverage :method, minimum: 100
+end
+```
+
+| Verb | Effect |
+|------|--------|
+| `minimum N` | Suite-wide minimum for this criterion. |
+| `maximum N` | Suite-wide maximum: fails if coverage rises above N. Pairs with `minimum` to pin coverage so an unexpected jump fails instead of being silently absorbed. |
+| `exact N` | Pins coverage by setting both `minimum` and `maximum` to N. |
+| `maximum_drop N` | Maximum allowed drop between runs (`maximum_drop 0` refuses any drop). |
+| `minimum_per_file N` | Per-file minimum. Add `only: "path"` / `only: %r{regexp}` to override it for matching files (later, more specific overrides win). |
+| `minimum_per_group N, only: "Name"` | Minimum for a named [group](#groups). |
+
+Every verb is also a keyword on the one-liner form (`coverage :branch, minimum: 80, maximum_drop: 5`). Two more options:
+`coverage :line, oneshot: true` selects the faster [oneshot-lines mode](#oneshot-lines-coverage), and
+`coverage :branch, primary: true` makes branch the report's leading criterion (the one a bare `minimum_coverage 90`
+targets). `coverage :eval` enables [eval coverage](#eval-coverage).
+
+### Suite-wide shortcuts
+
+For the common case of a single suite-wide threshold, the flat helpers are convenient sugar over the block above. A bare
+number targets the primary criterion (line by default); a Hash sets per-criterion values:
+
+```ruby
+SimpleCov.minimum_coverage 90                      # primary criterion (line)
+SimpleCov.minimum_coverage line: 90, branch: 80
+SimpleCov.maximum_coverage line: 90
+SimpleCov.maximum_coverage_drop line: 5, branch: 10
+SimpleCov.expected_coverage 95.42                  # pins minimum == maximum
+SimpleCov.refuse_coverage_drop :line, :branch      # maximum drop of 0
+```
+
+`expected_coverage` floors the actual percentage to two decimal places, so an actual of 95.4287 still passes at
+`expected_coverage 95.42`.
+
+> [!NOTE]
+> `minimum_coverage_by_file` and `minimum_coverage_by_group` are **deprecated** in favor of the `coverage` block's
+> `minimum_per_file` / `minimum_per_group`. They still work but emit a deprecation warning. For example, replace
+> `minimum_coverage_by_file line: 70, 'app/x.rb' => 100` with:
+>
+> ```ruby
+> coverage :line do
+>   minimum_per_file 70
+>   minimum_per_file 100, only: "app/x.rb"
+> end
+> ```
+
+## Formatters
+
+### Using your own formatter
+
+```ruby
+SimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter
+```
+
+`SimpleCov.result.format!` then invokes `SimpleCov::Formatter::YourFormatter.new.format(result)`, where `result` is a
+`SimpleCov::Result`. Do whatever you wish with it.
+
+### Using multiple formatters
+
+As of SimpleCov 0.9 you can specify multiple result formats. The HTML and JSON formatters are built in; other
+formatters ship as separate gems you'll need to add and require — for example,
+[simplecov-cobertura](https://github.com/dashingrocket/simplecov-cobertura) for the Cobertura XML that many CI services
+consume.
+
+```ruby
+require "simplecov-cobertura"
+
+SimpleCov.formatters = [
+  SimpleCov::Formatter::HTMLFormatter,
+  SimpleCov::Formatter::CoberturaFormatter,
+]
+```
+
+### JSON formatter
+
+`SimpleCov::Formatter::JSONFormatter` emits JSON — useful for CI consumption or reporting to external services.
+
+```ruby
+SimpleCov.formatter = SimpleCov::Formatter::JSONFormatter
+```
+
+By default `coverage.json` carries the full source-text array for every file, which makes the payload self-contained
+but dominates the file size on larger projects. Tools that read the project's source files directly from disk can opt
+out of that field with:
+
+```ruby
+SimpleCov.start do
+  source_in_json false
+end
+```
+
+The HTML report's `coverage_data.js` always retains the source array — the client-side viewer renders source from
+there. The setting only affects the side-file `coverage.json`. When the source is omitted, `meta.commit` (the git
+commit SHA the report was generated against) lets tools recover the exact source lines from repository history.
+
+> The JSON formatter was originally a separate gem,
+> [simplecov_json_formatter](https://github.com/codeclimate-community/simplecov_json_formatter). It is now built in and
+> loaded by default; existing code that does `require "simplecov_json_formatter"` will continue to work.
+
+### JSON Schema for `coverage.json`
+
+`coverage.json` is a public contract, described by a JSON Schema (2020-12) so downstream tools can validate it,
+generate types, or pin to a known shape. Every emitted document carries a top-level `$schema` URL pointing at the
+versioned canonical, plus a human-readable `meta.schema_version` (`"major.minor"`).
+
+The **versioned canonical** lives at [`schemas/coverage-v1.0.schema.json`](schemas/coverage-v1.0.schema.json) and
+long-lived integrations should pin to it. Once a SimpleCov release ships with a given versioned schema file, that file
+is immutable: bug fixes, additions, or shape changes ship as a new versioned file (a minor or major bump), never as a
+silent rewrite of an already-released one. Schemas may still be corrected in-place between gem releases — i.e., the
+schema file as it currently exists on `main` may change before the next gem release, but the schema for any published
+gem version stays frozen. A convenience alias at [`schemas/coverage.schema.json`](schemas/coverage.schema.json) always
+tracks the latest and may shift when a new SimpleCov release bumps the schema.
+
+The schema version is independent of the gem version:
+
+- Additive changes (new fields) bump the **minor** segment. Existing consumers keep working.
+- Removals or shape changes bump the **major** segment, and ship as a new `schemas/coverage-vX.0.schema.json` file so
+  v1.x consumers stay valid.
+
+The current version is **1.0**. Top-level structure:
+
+```jsonc
+{
+  "$schema":  "https://raw.githubusercontent.com/simplecov-ruby/simplecov/main/schemas/coverage-v1.0.schema.json",
+  "meta":     { /* schema_version, simplecov_version, command_name, project_name, timestamp, root, commit, line_coverage, branch_coverage, method_coverage */ },
+  "total":    { /* aggregate stats for lines (and branches / methods when enabled) */ },
+  "coverage": { "<project-relative path>": { /* per-file lines, source, branches, methods, etc. */ } },
+  "groups":   { "<group name>": { /* per-group stats + files */ } },
+  "errors":   { /* minimum_coverage, minimum_coverage_by_file, minimum_coverage_by_group, maximum_coverage, maximum_coverage_drop violations */ }
+}
+```
+
+The `.resultset.json` file is **not** schema'd — it's SimpleCov-internal and may change shape across releases. Build
+integrations on top of `coverage.json`.
+
+### More formatters, editor integrations, and hosted services
+
+  * [Open Source formatter and integration plugins for SimpleCov](doc/alternate-formatters.md)
+  * [Editor Integration](doc/editor-integration.md)
+  * [Hosted (commercial) services](doc/commercial-services.md)
+
+## Output and diagnostics
+
+### Errors and exit statuses
+
+If an error is raised, SimpleCov prints a message to `STDERR` with the exit status, to aid debugging:
+
+```
+SimpleCov failed with exit 1
+```
+
+Disable this message with:
+
+```ruby
+SimpleCov.print_errors false
+```
+
+### Color output
+
+When color is enabled, SimpleCov highlights coverage percentages in its `STDERR` diagnostics by band (green for
+`>= 90%`, yellow for `>= 75%`, red below) and prints the "SimpleCov failed with exit ..." summary in red. By default,
+color is on only when `STDERR` is a TTY. Two environment variables override that:
+
+- `NO_COLOR=1` (any non-empty value) disables color even when stderr is a TTY. Honors the
+  [no-color.org](https://no-color.org) convention.
+- `FORCE_COLOR=1` (any non-empty value) enables color even when stderr is not a TTY. Useful when stderr is piped through
+  a wrapper that itself renders ANSI in a terminal (`parallel_tests --combine-stderr`, log multiplexers, some CI runners).
+
+`NO_COLOR` wins if both are set.
+
+For programmatic control, use `SimpleCov.color`. An explicit `true` or `false` wins over the env vars and TTY detection:
+
+```ruby
+SimpleCov.color true   # always on
+SimpleCov.color false  # always off
+SimpleCov.color :auto  # default behavior: NO_COLOR/FORCE_COLOR/TTY
+```
+
+## Command-line interface
+
+The bundled `simplecov` CLI provides a set of subcommands. The read-only reporting commands consume the JSONFormatter's
+`coverage.json` output, so you don't need to re-run your suite — any prior run that emitted JSON suffices. Paths default
+to `SimpleCov.coverage_dir` from your project's `.simplecov` when one is present.
+
+| Command            | Description                                                         |
+|--------------------|---------------------------------------------------------------------|
+| `run <command…>`   | Execute `<command>` with simplecov pre-loaded (no `test_helper` hook needed) |
+| `coverage <path>`  | Print coverage stats for a single file                              |
+| `report`           | Print the overall summary and per-group totals                      |
+| `uncovered`        | List the lowest-coverage files                                      |
+| `merge <files…>`   | Merge multiple `.resultset.json` files                              |
+| `diff <baseline>`  | Show per-file coverage delta vs a baseline                          |
+| `open`             | Open the HTML report in the default browser                         |
+| `serve`            | Serve the coverage report over HTTP                                 |
+| `clean`            | Remove the coverage report directory                                |
+
+Run `simplecov help` for the full option listing.
+
+### `run` — run a suite with coverage
+
+If your project has no `test_helper.rb` hook that calls `SimpleCov.start` (or you don't want to add one), `simplecov run`
+execs your test command with simplecov pre-loaded so a report drops into `coverage/` at the end:
+
+```sh
+$ simplecov run bundle exec rspec
+$ simplecov run -- bundle exec rake test
+$ simplecov run ruby my_test.rb
+```
+
+Internally this just sets `RUBYOPT=-rsimplecov/autostart` for the child process, so any spawned subprocess (parallel
+test workers, integration test forks, etc.) also picks up the autostart shim. If your project already has a `.simplecov`
+config that calls `SimpleCov.start`, the autostart shim defers to it and won't double-start Coverage.
+
+### `coverage` — per-file lookup
+
+For editor / TDD inner-loop integrations and tools that want one file's coverage without re-parsing the full report:
+
+```sh
+$ simplecov coverage app/models/user.rb
+/abs/path/app/models/user.rb
+  Line:   100.00% (12 / 12)
+  Branch: 100.00% (4 / 4)
+  Method: 100.00% (3 / 3)
+
+$ simplecov coverage --json app/models/user.rb        # raw JSON entry
+$ simplecov coverage --input path/to/coverage.json …  # non-default location
+```
+
+The same lookup is available in Ruby, with paths resolved relative to `SimpleCov.root` (absolute or project-relative):
+
+```ruby
+result = SimpleCov.result   # or SimpleCov::Result.from_hash(...).first
+result.coverage_for("app/models/user.rb")
+# => {line: <CoverageStatistics>, branch: <CoverageStatistics>, method: <CoverageStatistics>}
+
+result.source_file_for("app/models/user.rb")
+# => <SimpleCov::SourceFile>
+```
+
+### `report` — quick terminal report
+
+For CI logs, ssh sessions, or any terminal-only workflow, `simplecov report` prints the same totals row the HTML report
+renders at the top, plus per-group totals:
+
+```sh
+$ simplecov report
+All Files
+  Line:    99.75% (1638 / 1642)
+  Branch:  98.50% (396 / 402)
+  Method:  99.73% (372 / 373)
+```
+
+Pass `--input PATH` to read a non-default `coverage.json`. `--json` emits the totals as a JSON object keyed by section
+name (`"All Files"` plus each group), useful when a CI step needs to act on the numbers rather than display them.
+
+### `uncovered` — list lowest-coverage files
+
+`simplecov uncovered` prints the lowest-coverage files (by line coverage, worst-first) so you can find where to add
+tests next without opening the HTML report:
+
+```sh
+$ simplecov uncovered
+ 50.00%  5/10    lib/foo.rb
+ 80.00%  8/10    lib/bar.rb
+
+$ simplecov uncovered --threshold 90 --top 5
+$ simplecov uncovered --criterion branch
+```
+
+`--threshold N` filters to files below N% coverage (default `100`); `--top N` caps the list at N entries (default
+`10`); `--criterion line|branch|method` chooses which coverage to rank by (default `line`). `--json` emits the rows as
+a JSON array (empty when nothing is below the threshold), useful for piping into a CI gate.
+
+### `merge` — combine resultsets from parallel CI workers
+
+CI matrices that produce one `.resultset.json` per worker can stitch them together with `simplecov merge` instead of
+hand-rolling a Rake task in every project:
+
+```sh
+$ simplecov merge worker-*/coverage/.resultset.json --output coverage/.resultset.json
+```
+
+By default `simplecov merge` ignores `merge_timeout`; pass `--honor-timeout` to drop entries older than the configured
+timeout. Pass `--dry-run` to preview the output path without writing, or `-q` / `--quiet` to suppress the success status
+line for cleaner CI logs. After merging, run `simplecov report` against the combined data.
+
+### `diff` — coverage delta vs a baseline
+
+`simplecov diff <baseline>` reads two `coverage.json` files (current plus a baseline checked into the repo, or produced
+by a previous CI run) and prints the files whose coverage moved on any enabled criterion. When branch or method coverage
+is enabled, those deltas appear alongside the line delta on the same row:
+
+```sh
+$ simplecov diff coverage/baseline.json
+  -20.00% lines  -10.00% branches  lib/foo.rb
+  + 5.00% lines  lib/bar.rb
+  +60.00% lines  lib/new.rb  (new file)
+  -95.00% lines  lib/gone.rb  (removed)
+```
+
+Regressions are listed first. Pass `--fail-on-drop` to exit non-zero when any file's line coverage slipped, so this
+composes with CI as a "coverage of this PR didn't drop" gate even when overall thresholds are still satisfied.
+`--threshold N` filters out deltas below N% in absolute value, useful when a baseline is noisy. `--json` emits the rows
+as a JSON array for programmatic consumption:
+
+```sh
+$ simplecov diff --json coverage/baseline.json
+[
+  {"file":"lib/foo.rb","status":"changed","line_delta":-20.0,"branch_delta":-10.0,"method_delta":0.0},
+  {"file":"lib/bar.rb","status":"changed","line_delta":5.0,"branch_delta":0.0,"method_delta":0.0}
+]
+```
+
+Coverage keys with a leading `/` (from `coverage.json` files emitted before the `SourceFile#project_filename` change)
+are normalized, so a baseline from an older SimpleCov still diffs cleanly against newer reports.
+
+### `serve` and `clean`
+
+`simplecov serve` serves the coverage report over HTTP — handy on a remote box where you can't open files directly.
+`--port N` binds to a specific port (default: a random open port) and `--host HOST` to a specific host (default
+`127.0.0.1`).
+
+`simplecov clean` removes the coverage report directory. `--dry-run` prints what would be removed without deleting
+anything; `-q` / `--quiet` suppresses status lines.
+
+## Compatibility and troubleshooting
+
+### Ruby version compatibility
+
+SimpleCov is built in [Continuous Integration] on Ruby 3.2+ and JRuby 10+. On CRuby, every coverage criterion
+described above is available on the supported versions, with one exception: [eval coverage](#eval-coverage) requires
+CRuby 3.2+.
+
+### JRuby
+
+On JRuby, only **line coverage** is available — branch, method, oneshot-line, and eval coverage rely on features of
+CRuby's `Coverage` library that JRuby doesn't implement. SimpleCov detects this automatically: the bundled `strict`
+profile, for instance, enforces only line coverage at 100% on JRuby instead of failing to load.
+
+To get accurate line numbers in coverage results, JRuby needs its full backtrace enabled. Pass `JRUBY_OPTS="--debug"`,
+or create a `.jrubyrc` with `debug.fullTrace=true`.
+
+### Notes on specific frameworks and test utilities
+
+Some frameworks and tools have quirks worth knowing about when using SimpleCov:
+
+<table>
+  <tr><th>Framework</th><th>Notes</th><th>Issue</th></tr>
+  <tr>
+    <th>
+      parallel_tests
+    </th>
+    <td>
+      As of 0.8.0, SimpleCov should correctly recognize parallel_tests and
+      supplement your test suite names with their corresponding test env
+      numbers. SimpleCov locks the resultset cache while merging, ensuring no
+      race conditions occur when results are merged.
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/64">#64</a> &amp;
+      <a href="https://github.com/simplecov-ruby/simplecov/pull/185">#185</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      knapsack_pro
+    </th>
+    <td>
+      To make SimpleCov work with Knapsack Pro Queue Mode to split tests in parallel on CI jobs you need to provide CI node index number to the <code>SimpleCov.command_name</code> in <code>KnapsackPro::Hooks::Queue.before_queue</code> hook.
+    </td>
+    <td>
+      <a href="https://knapsackpro.com/faq/question/how-to-use-simplecov-in-queue-mode">Tip</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      RubyMine
+    </th>
+    <td>
+      The <a href="https://www.jetbrains.com/ruby/">RubyMine IDE</a> has
+      built-in support for SimpleCov's coverage reports, though you might need
+      to explicitly set the output root using `SimpleCov.root('foo/bar/baz')`
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/95">#95</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      Spork
+    </th>
+    <td>
+      Because of how Spork works internally (using preforking), there used to
+      be trouble when using SimpleCov with it, but that has apparently been
+      resolved with a specific configuration strategy. See <a
+      href="https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284">this</a>
+      comment.
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/42#issuecomment-4440284">#42</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      Spring
+    </th>
+    <td>
+      <a href="#using-spring-with-simplecov">See section below.</a>
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/381">#381</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      Test/Unit
+    </th>
+    <td>
+      Test Unit 2 used to mess with ARGV, leading to a failure to detect the
+      test process name in SimpleCov. <code>test-unit</code> releases 2.4.3+
+      (Dec 11th, 2011) should have this problem resolved.
+    </td>
+    <td>
+      <a href="https://github.com/simplecov-ruby/simplecov/issues/45">#45</a> &amp;
+      <a href="https://github.com/test-unit/test-unit/pull/12">test-unit/test-unit#12</a>
+    </td>
+  </tr>
+</table>
+
+### Using Spring with SimpleCov
+
+If you use [Spring](https://github.com/rails/spring) to speed up test runs, SimpleCov often misreports coverage with the
+default config due to an eager-loading issue. There are a few fixes.
+
+One solution is to [explicitly call eager
+load](https://github.com/simplecov-ruby/simplecov/issues/381#issuecomment-347651728) in your `test_helper.rb` /
+`spec_helper.rb` after calling `SimpleCov.start`:
+
+```ruby
+require 'simplecov'
+SimpleCov.start 'rails'
+Rails.application.eager_load!
+```
+
+Alternatively, disable Spring while running SimpleCov:
+
+```sh
+DISABLE_SPRING=1 rake test
+```
+
+Or remove `gem 'spring'` from your `Gemfile`.
+
+### Different coverage between local and CI
+
+Rails generates `config/environments/test.rb` with `config.eager_load = ENV["CI"].present?` (Rails 7+), so **CI eagerly
+loads every file in `app/` while your local run does not**. The two environments then report different file sets and
+different totals from the same suite. Two ways to make the report deterministic:
+
+- Set `config.eager_load = true` everywhere in `test.rb` (slower locally, but matches CI — and matches what users
+  actually see in production).
+- Stick with the `rails` profile, which folds `{app,lib}/**/*.rb` into the report at 0% on every run regardless of
+  `eager_load`. (The profile resolves the glob relative to `SimpleCov.root`, not the test runner's cwd.) Outside the
+  profile, the equivalent is `cover "{app,lib}/**/*.rb"` — see the
+  [legacy-API migration table](#migrating-from-the-legacy-configuration-api) for the relationship with the older
+  `track_files`.
+
+### Missing coverage
+
+The **most common problem is that SimpleCov isn't required and started before everything else**. To track coverage for
+your whole application, **SimpleCov must come first** so that it (and the underlying Coverage library) can track files
+as they're loaded and used.
+
+If coverage is missing for some code, a simple trick is to add a `puts` inside that file and another right after
+`SimpleCov.start`, then check the order they print in:
+
+```ruby
+# my_code.rb
+class MyCode
+
+  puts "MyCode is being loaded!"
+
+  def my_method
+    # ...
+  end
+end
+
+# spec_helper.rb / rails_helper.rb / test_helper.rb / .simplecov — whatever
+SimpleCov.start
+puts "SimpleCov started successfully!"
+```
+
+If you see this order, you're good:
+
+```
+SimpleCov started successfully!
+MyCode is being loaded!
+```
+
+If `MyCode is being loaded!` prints first, the file was loaded before SimpleCov started — that's your problem.
+
+### Upgrading from 0.x
+
+Four methods that had been deprecated for a decade or more were removed in 1.0. Each had a one-to-one rename:
+
+| Removed                                  | Use instead                                |
+| ---------------------------------------- | ------------------------------------------ |
+| `SimpleCov::Filter#passes?`              | `SimpleCov::Filter#matches?`               |
+| `SimpleCov.adapters`                     | `SimpleCov.profiles`                       |
+| `SimpleCov.load_adapter('rails')`        | `SimpleCov.load_profile('rails')`          |
+| `SimpleCov::Formatter::MultiFormatter[]` | `SimpleCov::Formatter::MultiFormatter.new` |
+
+If a custom filter still defines `passes?`, rename the method to `matches?` — the signature and semantics are identical.
+
+## Related projects
+
+Want to find dead code in production? Try [Coverband](https://github.com/danmayer/coverband).
+
+## Contributing
+
+* [Issue Tracker](https://github.com/simplecov-ruby/simplecov/issues) — for code and bug reports. See
+  [CONTRIBUTING](https://github.com/simplecov-ruby/simplecov/blob/main/CONTRIBUTING.md) for how to contribute, along
+  with common problems to check before creating an issue.
+* [Mailing List](https://groups.google.com/forum/#!forum/simplecov) — open list for discussion and announcements on
+  Google Groups.
+
+## Code of Conduct
+
+Everyone participating in this project's development, issue trackers, and other channels is expected to follow our
+[Code of Conduct](./CODE_OF_CONDUCT.md).
+
+## Kudos
+
+Thanks to Aaron Patterson for the original idea for this!
+
+## Copyright
+
+Copyright (c) 2010-2026 Erik Berlin, Benjamin Fleischer, Akira Matsuda, Christoph Olszowka, Tobias Pfeiffer, David Rodríguez, and Xavier Shay. See MIT-LICENSE for details.