simplecov-rspec 0.4.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 484e82254055894678693503184af02dd373567de941c2e23b5171a2b1d43099
-  data.tar.gz: 2b75d02a33e196bb9a8d0e802d88e5ff56cf4b5afccf6518d5d45db49548aee3
+  metadata.gz: fcdb582042f1b21ad1a1bd486c120fd590f143e73cb51b6b693e3d5755396546
+  data.tar.gz: 6a39d87792ea1505b4e0b9af8e4e81ec447541f8e1a0aea8413b49918cfa70d1
 SHA512:
-  metadata.gz: 55816daa25c63ff70efaa2ecd127467384d9cc70bfa6bd0006789dbf4ae731f41a0423a803d8e6d56ec9139c08a98ce72d6577181c8845ae5d85e592e884de42
-  data.tar.gz: f6e35a9fa9fb61073e1881112be2b035955089b65f86ed7c22beda11aef5d67b4c1d943ecd2a67f964220e6c449445fee8b1d32b3b4214891ce3b62595ad3c8b
+  metadata.gz: 27efb22e915daa0cf8a00692a0f65ecdcf659b1badb7cef5210a86aed05a264cb1c4aee1d89aefe39e53515b3d8edf85481d071ef23e31c93f87f616fe4485ec
+  data.tar.gz: 2883aab5cd82ddecbcc46e081cb03048e64dd0297abc0d06da1998cc178b5697e2813bf5cbe4489c4b5d2889425afa39cfc2804ec1e0409bbd857e3142a16422

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.4"
+  ".": "1.1.0"
 }

data/.rubocop.yml

@@ -4,7 +4,13 @@ inherit_gem:
 AllCops:
   # RuboCop enforces rules depending on the oldest version of Ruby which
   # your project supports:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
+
+Metrics/ClassLength:
+  # SimpleCov::RSpec is a configuration surface: every option it accepts costs a reader
+  # method, an ENV-name constant, and an ivar. The default 100 is a smell threshold for
+  # classes that do work, not for one that mostly declares options.
+  Max: 120
 
 Style/StderrPuts:
   Enabled: false

data/CHANGELOG.md

@@ -4,6 +4,27 @@ Changes for each release are listed in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 
+## [1.1.0](https://github.com/main-branch/simplecov-rspec/compare/v1.0.0...v1.1.0) (2026-08-06)
+
+
+### Features
+
+* Add :described to scope the listing to the code under test ([71fe0c7](https://github.com/main-branch/simplecov-rspec/commit/71fe0c715063582ff207a6ac15e9a2c6dbe26243))
+* Add list_uncovered_files to scope the uncovered listing ([1981e65](https://github.com/main-branch/simplecov-rspec/commit/1981e6528a418340c4e211ff0b34ed745693151a))
+
+## [1.0.0](https://github.com/main-branch/simplecov-rspec/compare/v0.4.4...v1.0.0) (2026-08-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* `coverage_threshold:` and `list_uncovered_lines:` are removed in favor of `minimum_coverage:` and `list_uncovered:`; the `LIST_UNCOVERED_LINES` env var is removed in favor of `LIST_UNCOVERED`; and `COVERAGE_THRESHOLD` now sets only the line-coverage threshold instead of an overall coverage percentage. Update calls to `SimpleCov::RSpec.start` and any CI environment variables accordingly.
+* drops support for Ruby 3.1 and JRuby 9.4; the minimum is now Ruby 3.2 (or JRuby 10, which reports RUBY_VERSION 3.4).
+
+### Features
+
+* Rely on SimpleCov's own minimum_coverage instead of reimplementing it ([d2fed78](https://github.com/main-branch/simplecov-rspec/commit/d2fed78ff5e5cb2bbf18bc89cb3b301455de0bce))
+* Require Ruby >= 3.2, matching SimpleCov 1.0's own floor ([9452587](https://github.com/main-branch/simplecov-rspec/commit/9452587137e1b698019d4214981f82ed796b9c1d))
+
 ## [0.4.4](https://github.com/main-branch/simplecov-rspec/compare/v0.4.3...v0.4.4) (2026-04-24)
 
 

data/README.md

@@ -8,38 +8,77 @@
 Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
 [![Slack](https://img.shields.io/badge/slack-main--branch/simplecov--rspec-yellow.svg?logo=slack)](https://main-branch.slack.com/archives/C07MCM9J72B)
 
-`simplecov-rspec` is a Ruby gem that integrates SimpleCov with RSpec to ensure your
-tests meet a minimum coverage threshold. It enhances your test suite by automatically
-failing tests when coverage falls below a specified threshold and, optionally,
-listing uncovered lines to help you improve coverage.
+`simplecov-rspec` is a Ruby gem that integrates SimpleCov with RSpec. SimpleCov
+(`>= 1.0`) already enforces `minimum_coverage` for line, branch, and method coverage
+and fails the build when a threshold is missed. This gem layers four things on top
+that SimpleCov doesn't do on its own:
+
+1. Suppresses coverage failures when RSpec is run in dry-run mode (e.g. from an IDE).
+2. Lists (or summarizes) the individual uncovered lines, branches, and methods.
+3. Scopes that listing to the files you name, or to the code the run described.
+4. Lets all of the above be overridden from the environment, for CI.
 
 When `simplecov-rspec` is used, RSpec will report an error if the percent of test
 coverage falls below a defined threshold:
 
 ```text
-Coverage report generated for RSpec to /Projects/example_project/coverage. 284 / 286 LOC (99.3%) covered.
-
-FAIL: RSpec Test coverage fell below 100%
+Coverage report generated for RSpec to coverage/index.html
+Line coverage: 284 / 286 (99.30%)
+Line coverage (99.30%) is below the expected minimum coverage (100.00%).
+  Lowest-coverage files (line):
+     99.30%  lib/example_project.rb
+SimpleCov failed with exit 2 due to a coverage related error
 ```
 
-If configured to list the lines that were not covered by tests, RSpec will additionally output:
+All of that comes from SimpleCov itself. If configured to list the items that were not
+covered by tests, this gem adds its own listing between SimpleCov's summary and its
+failure message:
 
 ```text
+Coverage report generated for RSpec to coverage/index.html
+Line coverage: 284 / 286 (99.30%)
+
 2 lines are not covered by tests:
   ./lib/example_project.rb:74
   ./lib/example_project.rb:75
+Line coverage (99.30%) is below the expected minimum coverage (100.00%).
 ```
 
-* [Installation](#installation)
-* [Getting started](#getting-started)
-    * [Basic setup](#basic-setup)
-    * [Configuration from environment variables](#configuration-from-environment-variables)
-* [Development](#development)
-* [Contributing](#contributing)
-    * [Commit message guidelines](#commit-message-guidelines)
-    * [Pull request guidelines](#pull-request-guidelines)
-* [License](#license)
-* [Code of conduct](#code-of-conduct)
+Scoping the listing to particular files changes its shape again. It is marked off with a
+header saying how much of the result it covers, and each criterion reports what the
+scoped files cover directly above what they miss — see [Scoping the listing to specific
+files](#scoping-the-listing-to-specific-files):
+
+```text
+Coverage report generated for RSpec to coverage/index.html
+Line coverage: 284 / 286 (99.30%)
+Branch coverage: 138 / 150 (92.00%)
+
+-- Reporting uncovered lines and branches for 1 of 12 files --
+
+Scoped line coverage: 73 / 74 (98.64%)
+1 line is not covered by tests:
+  ./lib/example_project/parser.rb:74
+
+Scoped branch coverage: 11 / 12 (91.66%)
+1 branch is not covered by tests:
+  ./lib/example_project/parser.rb:82 (then branch)
+```
+
+- [Installation](#installation)
+- [Getting started](#getting-started)
+  - [Basic setup](#basic-setup)
+  - [Listing uncovered items](#listing-uncovered-items)
+  - [Scoping the listing to specific files](#scoping-the-listing-to-specific-files)
+  - [Scoping to the code under test](#scoping-to-the-code-under-test)
+  - [Configuration block](#configuration-block)
+  - [Configuration from environment variables](#configuration-from-environment-variables)
+- [Development](#development)
+- [Contributing](#contributing)
+  - [Commit message guidelines](#commit-message-guidelines)
+  - [Pull request guidelines](#pull-request-guidelines)
+- [License](#license)
+- [Code of conduct](#code-of-conduct)
 
 ## Installation
 
@@ -48,13 +87,13 @@ To install the gem, add to the following line to your application's gemspec OR G
 gemspec:
 
 ```ruby
-  spec.add_development_dependency "simplecov-rspec", '~> 0.1'
+  spec.add_development_dependency "simplecov-rspec", '~> 1.0'
 ```
 
 Gemfile:
 
 ```ruby
-gem "simplecov-rspec", "~> 0.1", groups: [:development, :test]
+gem "simplecov-rspec", "~> 1.0", groups: [:development, :test]
 ```
 
 and then run `bundle install`
@@ -102,54 +141,236 @@ This is equivalent to starting with the following options:
 
 ```ruby
 SimpleCov::RSpec.start(
-    coverage_threshold: 100,
+    minimum_coverage: { line: 100 },
     fail_on_low_coverage: true,
-    list_uncovered_lines: false
+    list_uncovered: false,
+    list_uncovered_detail: true,
+    list_uncovered_files: nil
 )
 ```
 
-The test coverage threshold is the minimum percent of lines covered by tests as
-tracked by SimpleCov.
+`minimum_coverage` is the minimum percent of lines (and, optionally, branches and
+methods) covered by tests, enforced by SimpleCov itself.
+
+To require less than 100% line coverage:
+
+```ruby
+SimpleCov::RSpec.start(minimum_coverage: 90)
+```
+
+To also require branch (and/or method) coverage, pass a Hash. Any criterion named
+here is automatically enabled via `SimpleCov.enable_coverage`:
+
+```ruby
+SimpleCov::RSpec.start(minimum_coverage: { line: 100, branch: 90 })
+```
+
+### Listing uncovered items
+
+To list the individual lines, branches, and/or methods that are not covered, set
+`list_uncovered`. It accepts `:all`, a single criterion, or an Array of criteria —
+independent of what `minimum_coverage` enforces:
+
+```ruby
+SimpleCov::RSpec.start(minimum_coverage: { line: 100, branch: 90 }, list_uncovered: :all)
+```
+
+```text
+2 lines are not covered by tests:
+  ./lib/example_project.rb:74
+  ./lib/example_project.rb:75
+
+1 branch is not covered by tests:
+  ./lib/example_project.rb:82 (else branch)
+
+1 method is not covered by tests:
+  ./lib/example_project.rb:96 ExampleProject#unused
+```
+
+A criterion with nothing uncovered is left out entirely, so `:all` prints fewer sections
+than this when there is less to say.
+
+For a quieter CI log, set `list_uncovered_detail: false` to print only the count per
+criterion, along with a hint on how to see the details:
+
+```ruby
+SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_detail: false)
+```
+
+```text
+2 lines are not covered by tests.
+1 branch is not covered by tests.
+1 method is not covered by tests.
 
-To initialize SimpleCov with a test coverage threshold less than 100%:
+Run with LIST_UNCOVERED_DETAIL=true to see the uncovered lines, branches and methods.
+```
+
+### Scoping the listing to specific files
+
+By default the uncovered listing covers every file SimpleCov tracked. On a focused run
+— one spec file, or one directory — that listing is mostly noise: `spec_helper`
+requires the whole project, so nearly all of it is legitimately unexercised.
+
+`list_uncovered_files` (available since version 1.1) narrows the listing to the files
+you care about, given as `Dir.glob` patterns resolved against `SimpleCov.root`. An
+absolute path is used as given:
 
 ```ruby
-SimpleCov::RSpec.start(coverage_threshold: 90)
+SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: 'lib/example_project/parser.rb')
 ```
 
+This option scopes the listing that `list_uncovered` asks for; it does not ask for one.
+`list_uncovered` defaults to `false`, which lists nothing, so setting only
+`list_uncovered_files` produces no output at all. Set both.
+
+```text
+-- Reporting uncovered lines, branches and methods for 1 of 218 files --
+
+Scoped line coverage: 73 / 74 (98.64%)
+1 line is not covered by tests:
+  ./lib/example_project/parser.rb:74
+
+Scoped branch coverage: 12 / 12 (100.00%)
+Scoped method coverage: 8 / 8 (100.00%)
+```
+
+Each criterion reports what the scoped files cover directly above what they miss, so a
+count like "1 line is not covered" arrives with the denominator that makes it readable,
+and a blank line always means "next criterion". These are deliberately labelled
+differently from SimpleCov's own project-wide summary, and the report is marked off with
+a header, because SimpleCov prints that summary a few lines earlier on the same stream
+while counting different things.
+
+This narrows **only the listing**. Coverage is still measured, enforced, and formatted
+for the whole project, so the reported percentage and the HTML report mean the same
+thing whether or not this option is set. There is one definition of "the coverage
+number", and this option does not change it.
+
+A scoped report always prints something, and always says how much of the result it
+covered, so it can never be mistaken for a clean run of the whole suite:
+
+```text
+-- Reporting uncovered lines, branches and methods for 1 of 218 files --
+
+Scoped line coverage: 74 / 74 (100.00%)
+Scoped branch coverage: 12 / 12 (100.00%)
+Scoped method coverage: 8 / 8 (100.00%)
+
+No uncovered lines, branches and methods in this file.
+```
+
+When it comes up empty, it says which of the three reasons applies, since only one of
+them means you mistyped a pattern:
+
+```text
+-- Reporting uncovered lines, branches and methods for 0 of 218 files --
+
+No files matched, so no coverage was reported.
+```
+
+```text
+-- Reporting uncovered lines, branches and methods for 0 of 218 files --
+
+1 file matched, but it is not in the coverage result. It may not have been loaded by
+this run, or may be excluded by a SimpleCov filter.
+```
+
+```text
+-- Reporting uncovered lines, branches and methods for 0 of 218 files --
+
+No files were requested, so no coverage was reported.
+```
+
+### Scoping to the code under test
+
+Naming the files by hand is the awkward part of a focused run: the file you want is
+whatever you happen to be testing right now. `:described` resolves to the source files
+defining the classes the run described, so it follows you from run to run:
+
+```ruby
+SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: :described)
+```
+
+```bash
+# Report on lib/example_project/parser.rb, because that is what these specs describe
+bundle exec rspec spec/example_project/parser_spec.rb
+```
+
+It walks nested groups too, so a `describe` of one class inside another contributes
+both. A group describing something that is not a class contributes nothing, as does one
+whose class is anonymous, defined in C, or no longer reachable by name — there is no
+source file to report on in those cases.
+
+The scope is the classes the run *described*, not the ones it exercised. A class that a
+described class delegates to is not included, and a group written as `describe 'the
+parser' do` names no class at all. Where that matters, build the scope yourself:
+`SimpleCov::RSpec.described_source_files` is public, and you can add to what it returns.
+
+```ruby
+SimpleCov::RSpec.start(
+  list_uncovered: :all,
+  list_uncovered_files: -> { SimpleCov::RSpec.described_source_files + ['lib/example_project/lexer.rb'] }
+)
+```
+
+The lambda is doing real work there, and leaving it off is a mistake worth naming.
+`SimpleCov::RSpec.start` runs before any example is defined, so calling
+`described_source_files` at that point returns an empty list and you get a report scoped
+to nothing. Any scope derived from the run has to be passed as a callable and resolved
+afterwards — which is exactly what `:described` does for you.
+
+### Configuration block
+
 A configuration block can be given to the `start` method to further configure
 SimpleCov:
 
 ```ruby
 # Initialize SimpleCov with a specific formatter
-SimpleCov::RSpec.start { formatter = SimpleCov::Formatter::LcovFormatter }
+SimpleCov::RSpec.start { formatter SimpleCov::Formatter::LcovFormatter }
 ```
 
-This block is passed on to `SimpleCov::RSpec.start`. See [Configuring
-SimpleCov](https://github.com/simplecov-ruby/simplecov?tab=readme-ov-file#configuring-simplecov)
+This block is passed on to `SimpleCov.start`. See [Configuring
+SimpleCov](https://github.com/simplecov-ruby/simplecov?tab=readme-ov-file#configuration)
 for details.
 
 ### Configuration from environment variables
 
 Environment variables can be used to configure `simplecov-rspec`. These environment
-variables take presidence over the values passed to `SimpleCov::RSpec.start`.
-
-* **`COVERAGE_THRESHOLD`**: Sets the minimum coverage threshold (0-100). Overrides
-  `coverage_threshold`.
+variables take precedence over the values passed to `SimpleCov::RSpec.start`.
+
+* **`COVERAGE_THRESHOLD`**: Sets the minimum line coverage threshold (0-100). Overrides
+  `minimum_coverage[:line]`.
+* **`COVERAGE_THRESHOLD_BRANCH`**: Sets the minimum branch coverage threshold (0-100), and
+  enables branch coverage. Overrides `minimum_coverage[:branch]`.
+* **`COVERAGE_THRESHOLD_METHOD`**: Sets the minimum method coverage threshold (0-100), and
+  enables method coverage. Overrides `minimum_coverage[:method]`.
 * **`FAIL_ON_LOW_COVERAGE`**: Controls whether tests fail if coverage is below the threshold.
   Set to 'true', 'yes', 'on', or '1' (case insensitive) to enable.
-* **`LIST_UNCOVERED_LINES`**: Determines if uncovered lines are listed. Set to 'true',
-  'yes', 'on', or '1' (case insensitive) to enable.
+* **`LIST_UNCOVERED`**: Controls which criteria to list uncovered items for. Set to 'all',
+  'true', 'yes', 'on', or '1' to report every criterion; 'false', 'no', 'off', or '0' to
+  report none; or a comma-separated list, e.g. `line,branch`.
+* **`LIST_UNCOVERED_DETAIL`**: Controls whether uncovered items are listed individually, or
+  just summarized as a count per criterion. Set to 'true', 'yes', 'on', or '1' (case
+  insensitive) to show individual items.
+* **`LIST_UNCOVERED_FILES`**: Controls which files uncovered items are listed for. Set to a
+  comma-separated list of `Dir.glob` patterns, relative to `SimpleCov.root`; to
+  'described', for the files defining the classes the run described; or to 'all'
+  (or 'false', 'no', 'off', '0', or empty) to list them for every file. Since the
+  separator is a comma, a brace pattern such as `lib/{a,b}.rb` cannot be used here —
+  give the alternatives separately, as `lib/a.rb,lib/b.rb`. Like `list_uncovered_files`,
+  this scopes the listing rather than asking for one: it has no effect unless
+  `LIST_UNCOVERED` (or `list_uncovered:`) names at least one criterion.
 
 For example, here is a bash script to run tests in an infinite loop while writing
 test output to `fail.txt`:
 
 ```bash
-while true; do COV_NO_FAIL=TRUE rspec >> fail.txt; done
+while true; do FAIL_ON_LOW_COVERAGE=false rspec >> fail.txt; done
 ```
 
-In a CI system, you might want to set `LIST_UNCOVERED_LINES=yes` in order to list
-uncovered lines on different platforms than the one you run for local development.
+In a CI system, you might want to set `LIST_UNCOVERED=all` in order to list uncovered
+lines, branches, and methods on a platform other than the one you use for local
+development.
 
 ## Development
 

data/lib/simplecov-rspec/described_source_files.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class RSpec
+    # Finds the source files that define the classes an RSpec run described.
+    #
+    # This is the scope most people want from `list_uncovered_files:` on a focused run:
+    # "report on the code I am actually testing". Deriving it means reaching into
+    # `RSpec.world`, which is not part of RSpec's public API, so it lives here rather
+    # than in each project's `spec_helper.rb`, where it could not be fixed centrally.
+    #
+    # @api private
+    #
+    module DescribedSourceFiles
+      module_function
+
+      # The source files defining the classes the run described
+      #
+      # A group that describes something other than a Module contributes nothing, as
+      # does one whose described class is anonymous, defined in C, or no longer
+      # reachable by name. Such a group has no source file to report on, and saying so
+      # is not useful, so it is skipped silently.
+      #
+      # @param example_groups [Array<Class>] the run's top-level example groups
+      #
+      # @return [Array<String>] absolute paths, without duplicates
+      #
+      # @example
+      #   DescribedSourceFiles.call # => ['/project/lib/parser.rb']
+      #
+      # @api private
+      #
+      def call(example_groups: ::RSpec.world.example_groups)
+        with_nested(example_groups).filter_map { |group| source_file(group) }.uniq
+      end
+
+      # The given example groups, plus every group nested within them
+      #
+      # A nested group can describe a different class than the group containing it, so
+      # the whole tree is walked rather than just the top level.
+      #
+      # @param groups [Array<Class>] the example groups to walk
+      #
+      # @return [Array<Class>]
+      #
+      # @example
+      #   DescribedSourceFiles.with_nested(::RSpec.world.example_groups)
+      #
+      # @api private
+      #
+      def with_nested(groups)
+        groups.flat_map { |group| [group, *with_nested(group.children)] }
+      end
+
+      # The source file defining one group's described class, if it has one
+      #
+      # @param group [Class] the example group
+      #
+      # @return [String, nil] an absolute path, or nil if there is nothing to report on
+      #
+      # @example
+      #   DescribedSourceFiles.source_file(group) # => '/project/lib/parser.rb'
+      #
+      # @api private
+      #
+      def source_file(group)
+        described_class = group.described_class
+        return nil unless described_class.is_a?(Module)
+
+        # A class defined in C answers [], one whose constant is gone answers nil
+        name = described_class.name
+        name && Object.const_source_location(name)&.first
+      end
+    end
+  end
+end

data/lib/simplecov-rspec/list_uncovered_files_option.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  class RSpec
+    # Resolves the `list_uncovered_files:` option (plus its `LIST_UNCOVERED_FILES` ENV
+    # override) into a normalized Array of absolute paths, or nil for "every file".
+    #
+    # The option may be given as a callable so that it can be evaluated after the test
+    # run rather than when `SimpleCov::RSpec.start` is called. `start` runs before any
+    # example is defined, so a caller that wants to scope the report to the code under
+    # test cannot know which files those are yet.
+    #
+    # @api private
+    #
+    module ListUncoveredFilesOption
+      # LIST_UNCOVERED_FILES environment variable values that mean "every file"
+      ALL_ENV_VALUES = %w[all false no off 0].freeze
+
+      # The value that means "the files defining the classes this run described"
+      #
+      # Sugar over passing a callable that does the same thing: the scope is only
+      # knowable after the run, so it resolves to one.
+      #
+      # @see SimpleCov::RSpec.described_source_files
+      DESCRIBED = :described
+
+      module_function
+
+      # Resolve the effective file list, applying the ENV override if present
+      #
+      # @param value [nil, Symbol, String, Array<String>, #call] the `list_uncovered_files:` argument
+      # @param env [Hash] the environment variables
+      # @param env_var [String] the ENV var name that overrides `value`
+      # @param root [String] the directory that relative patterns are resolved against
+      #
+      # @return [Array<String>, nil] absolute paths, or nil to report on every file
+      #
+      # @raise [ArgumentError] if value is not one of the accepted forms
+      #
+      # @example
+      #   ListUncoveredFilesOption.resolve('lib/a.rb', env: {}, env_var: 'X', root: '/p') # => ['/p/lib/a.rb']
+      #
+      def resolve(value, env:, env_var:, root:)
+        value = from_env(env.fetch(env_var)) if env.key?(env_var)
+        value = -> { ::SimpleCov::RSpec.described_source_files } if value == DESCRIBED
+        value = value.call if value.respond_to?(:call)
+        return nil if value.nil?
+
+        expand(normalize(value), root)
+      end
+
+      # Parse a raw LIST_UNCOVERED_FILES environment variable value
+      #
+      # A value that lists no patterns at all — `''`, `'  '`, or separators alone such as
+      # `', ,'` — means "every file". Dropping the empty entries can empty the list even
+      # though the value was not empty to start with, so the check is made after parsing
+      # as well as before it.
+      #
+      # @param raw [String] the raw LIST_UNCOVERED_FILES environment variable value
+      # @return [nil, Symbol, Array<String>] nil for "every file", {DESCRIBED}, or the listed patterns
+      # @example
+      #   ListUncoveredFilesOption.from_env('lib/a.rb,lib/b.rb') # => ['lib/a.rb', 'lib/b.rb']
+      #
+      def from_env(raw)
+        stripped = raw.strip
+        return nil if stripped.empty? || ALL_ENV_VALUES.include?(stripped.downcase)
+        return DESCRIBED if stripped.casecmp?(DESCRIBED.to_s)
+
+        patterns = stripped.split(',').map(&:strip).reject(&:empty?)
+        patterns.empty? ? nil : patterns
+      end
+
+      # Normalize a `list_uncovered_files:`-style value into an Array of Strings
+      #
+      # @param value [String, Array<String>] the pattern or patterns
+      # @return [Array<String>]
+      # @raise [ArgumentError] if value is not a String or an Array of Strings
+      # @example
+      #   ListUncoveredFilesOption.normalize('lib/a.rb') # => ['lib/a.rb']
+      #
+      def normalize(value)
+        case value
+        when String then [value]
+        when Array then validate(value)
+        else
+          raise ArgumentError,
+                'list_uncovered_files must be nil, :described, a String, an Array of Strings, or a callable ' \
+                "returning one of those; got #{value.inspect}"
+        end
+      end
+
+      # Raise unless every element of patterns is a String
+      #
+      # @param patterns [Array<String>]
+      # @return [Array<String>]
+      # @raise [ArgumentError] if patterns contains a non-String
+      # @example
+      #   ListUncoveredFilesOption.validate(['lib/a.rb']) # => ['lib/a.rb']
+      #
+      def validate(patterns)
+        invalid = patterns.grep_v(String)
+        return patterns if invalid.empty?
+
+        raise ArgumentError, "list_uncovered_files entries must be Strings; got #{invalid.inspect}"
+      end
+
+      # Expand patterns to absolute paths, resolving relative patterns against root
+      #
+      # Each pattern is expanded with `Dir.glob`. A pattern that matches nothing on disk
+      # expands to itself, so the literal pattern is kept rather than dropped. No file in
+      # the coverage result can carry that path, so it adds nothing to the listing; it is
+      # kept because the report tests these paths against the file system to tell a
+      # pattern that matched nothing from one whose files SimpleCov never tracked.
+      #
+      # @param patterns [Array<String>] the patterns to expand
+      # @param root [String] the directory that relative patterns are resolved against
+      # @return [Array<String>] absolute paths, without duplicates
+      # @example
+      #   ListUncoveredFilesOption.expand(['lib/*.rb'], '/p') # => ['/p/lib/a.rb', '/p/lib/b.rb']
+      #
+      def expand(patterns, root)
+        patterns.flat_map do |pattern|
+          absolute = File.absolute_path(pattern, root)
+          matches = Dir.glob(absolute)
+          matches.empty? ? [absolute] : matches
+        end.uniq
+      end
+    end
+  end
+end