simplecov-rspec 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66e26ea8073a8373f072d8b58d5a11825fc26798d76b9ecf13b225279edfa06f
-  data.tar.gz: 59759b57e676fa16bbebd8d423dcf9852a3d4550c3b3864211c937003191c755
+  metadata.gz: fcdb582042f1b21ad1a1bd486c120fd590f143e73cb51b6b693e3d5755396546
+  data.tar.gz: 6a39d87792ea1505b4e0b9af8e4e81ec447541f8e1a0aea8413b49918cfa70d1
 SHA512:
-  metadata.gz: 253e3bbfe90ac2bc476f7e81eb9926f2457fb0b9a1cf4a066d116cdad7c2db00f15a33fa9a4622265580b309eead7b30ccadb0ef6ddc37936a9b52ecb9d0f369
-  data.tar.gz: 0b0c8be4624b3f85d3ede8bbb5f64b4a3e71d8287f27fd7a46e102b01318558c1c91b5b59fa2ff1c5505ff65513295da0a6495415b9a056c15fa736f06b63b41
+  metadata.gz: 27efb22e915daa0cf8a00692a0f65ecdcf659b1badb7cef5210a86aed05a264cb1c4aee1d89aefe39e53515b3d8edf85481d071ef23e31c93f87f616fe4485ec
+  data.tar.gz: 2883aab5cd82ddecbcc46e081cb03048e64dd0297abc0d06da1998cc178b5697e2813bf5cbe4489c4b5d2889425afa39cfc2804ec1e0409bbd857e3142a16422

data/.release-please-manifest.json

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

data/.rubocop.yml

@@ -6,6 +6,12 @@ AllCops:
   # your project supports:
   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,14 @@ 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)
 
 

data/README.md

@@ -10,34 +10,67 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 
 `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 three things on top
+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. Lets all of the above be overridden from the environment, for CI.
+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.
-
-Line coverage (99.3%) is below the expected minimum coverage (100.00%).
+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 items 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%).
+```
+
+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)
@@ -111,7 +144,8 @@ SimpleCov::RSpec.start(
     minimum_coverage: { line: 100 },
     fail_on_low_coverage: true,
     list_uncovered: false,
-    list_uncovered_detail: true
+    list_uncovered_detail: true,
+    list_uncovered_files: nil
 )
 ```
 
@@ -142,13 +176,20 @@ SimpleCov::RSpec.start(minimum_coverage: { line: 100, branch: 90 }, list_uncover
 ```
 
 ```text
-1 line is not covered by tests:
+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:
 
@@ -159,10 +200,125 @@ 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.
+
+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(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.
 
-Run with LIST_UNCOVERED_DETAIL=true to see the uncovered lines and branches.
+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
@@ -196,6 +352,14 @@ variables take precedence over the values passed to `SimpleCov::RSpec.start`.
 * **`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`:

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

data/lib/simplecov-rspec/uncovered_report.rb

@@ -22,18 +22,26 @@ module SimpleCov
       # @param criteria [Array<Symbol>] which criteria (:line, :branch, :method) to report
       # @param detail [Boolean] list individual items, or just a count per criterion
       # @param detail_env_var [String] the ENV var name to suggest for switching to detail
+      # @param files [Array<String>, nil] absolute paths to report on, or nil for every file
       # @example
       #   UncoveredReport.new(result: SimpleCov.result, criteria: [:line], detail: true, detail_env_var: 'X')
-      def initialize(result:, criteria:, detail:, detail_env_var:)
+      def initialize(result:, criteria:, detail:, detail_env_var:, files: nil)
         @result = result
         @criteria = criteria
         @detail = detail
         @detail_env_var = detail_env_var
+        @files = files
       end
 
       # The formatted report text, or an empty string if there is nothing to report
+      #
+      # A scoped report (one where `files` is not nil) always produces text, even when
+      # every file it covers is fully covered. Silence there would be indistinguishable
+      # from a clean run of the whole suite, which is the opposite of what asking for a
+      # scope means.
+      #
       # @return [String]
-      def to_s = detail ? detailed_text : summary_text
+      def to_s = files.nil? ? uncovered_text : scoped_text
 
       private
 
@@ -57,6 +65,161 @@ module SimpleCov
       # @api private
       attr_reader :detail_env_var
 
+      # The absolute paths to report on, or nil to report on every file in the result
+      # @return [Array<String>, nil]
+      # @api private
+      attr_reader :files
+
+      # The result's files, narrowed to `files` when a scope was given
+      # @return [Array<SimpleCov::SourceFile>]
+      def reported_files
+        @reported_files ||= files.nil? ? result.files : result.files.select { |file| files.include?(file.filename) }
+      end
+
+      # The uncovered items or counts, in the requested level of detail
+      # @return [String]
+      def uncovered_text = detail ? detailed_text : summary_text
+
+      # The report for a scope, which is always non-empty
+      #
+      # Names how much of the result the scope covered, then one section per criterion,
+      # then a closing statement.
+      #
+      # @return [String]
+      def scoped_text
+        return "#{scope_text}\n\n#{nothing_reported_text}" if reported_files.empty?
+
+        [scope_text, *criterion_blocks, closing_text].compact.join("\n\n")
+      end
+
+      # Why a scope produced nothing to report on
+      #
+      # Three different mistakes end up here, and only one of them is "your pattern
+      # matched nothing". Saying that when the pattern matched a real file that
+      # SimpleCov never saw sends the reader looking for a typo that isn't there.
+      #
+      # @return [String]
+      def nothing_reported_text
+        return 'No files were requested, so no coverage was reported.' if files.empty?
+        return 'No files matched, so no coverage was reported.' if matched_files.empty?
+
+        untracked_text
+      end
+
+      # The requested paths that name a file on disk
+      #
+      # A pattern that globbed successfully expands to paths that exist; one that
+      # matched nothing is kept as a literal path that does not.
+      #
+      # @return [Array<String>]
+      def matched_files = @matched_files ||= files.select { |path| File.file?(path) }
+
+      # The report for files that exist but are absent from the coverage result
+      # @return [String]
+      def untracked_text
+        count = matched_files.count
+        "#{count} #{pluralize(count, 'file matched, but it is not', 'files matched, but none are')} in the " \
+          "coverage result. #{pluralize(count, 'It', 'They')} may not have been loaded by this run, or may " \
+          'be excluded by a SimpleCov filter.'
+      end
+
+      # The line stating how much of the result the scope covered
+      #
+      # Reported alongside the total so that a scoped report showing nothing uncovered
+      # cannot be misread as the whole suite being fully covered. Marked off as a section
+      # header because SimpleCov prints its own project-wide summary just above, on the
+      # same stream, counting different things.
+      #
+      # @return [String]
+      def scope_text
+        "-- Reporting uncovered #{noun_list(criteria)} for " \
+          "#{reported_files.count} of #{result.files.count} #{pluralize(result.files.count, 'file', 'files')} --"
+      end
+
+      # The body of a scoped report: what the files cover, then what they miss
+      #
+      # A criterion's coverage sits directly above its own listing, and criteria with
+      # nothing to list share a block, so that a blank line always means "next criterion"
+      # and never separates a heading from what it heads.
+      #
+      # @return [Array<String>]
+      def criterion_blocks
+        criteria.map { |criterion| [coverage_text(criterion), missing_text(criterion)] }
+                .chunk_while { |(_, missing), (_, next_missing)| missing.nil? && next_missing.nil? }
+                .map { |block| block.flatten.compact.join("\n") }
+      end
+
+      # A criterion's coverage across the scoped files
+      #
+      # Deliberately not labelled the way SimpleCov labels its own project-wide summary.
+      # The two appear within a few lines of each other and count different things, so
+      # sharing a label would make the narrower number look like a restatement of the
+      # broader one.
+      #
+      # @param criterion [Symbol]
+      # @return [String]
+      def coverage_text(criterion)
+        covered = covered_count(criterion)
+        total = covered + uncovered_count(criterion)
+        "Scoped #{criterion} coverage: #{covered} / #{total} (#{percent_text(covered, total)})"
+      end
+
+      # A covered-of-total ratio, formatted the way SimpleCov formats its own
+      #
+      # Truncated rather than rounded, through SimpleCov's own helper, because its
+      # project-wide summary prints a few lines above this one over the same kind of
+      # ratio. Two percentages differing in the last digit would read as a bug in one of
+      # them. A criterion with nothing to cover is 100%, which is also what SimpleCov says.
+      #
+      # @param covered [Integer] the number of covered items
+      # @param total [Integer] the number of items that could be covered
+      #
+      # @return [String]
+      def percent_text(covered, total)
+        percent = total.zero? ? 100.0 : covered * 100.0 / total
+        "#{format('%.2f', ::SimpleCov.round_coverage(percent))}%"
+      end
+
+      # A criterion's uncovered items or count
+      #
+      # Nil when the scoped files leave nothing uncovered for it.
+      #
+      # @param criterion [Symbol]
+      # @return [String, nil]
+      def missing_text(criterion)
+        return section(criterion) if detail
+
+        count = uncovered_count(criterion)
+        count.positive? ? "#{header(criterion, count)}." : nil
+      end
+
+      # The closing statement: that nothing is uncovered, or how to see what is
+      # @return [String, nil]
+      def closing_text
+        return nothing_uncovered_text if missing_criteria.empty?
+        return nil if detail
+
+        "Run with #{detail_env_var}=true to see the uncovered #{noun_list(missing_criteria)}."
+      end
+
+      # The criteria the scoped files leave something uncovered for
+      # @return [Array<Symbol>]
+      def missing_criteria = criteria.reject { |criterion| uncovered_count(criterion).zero? }
+
+      # The statement that a scope turned up no uncovered items
+      # @return [String]
+      def nothing_uncovered_text
+        "No uncovered #{noun_list(criteria)} in #{pluralize(reported_files.count, 'this file', 'these files')}."
+      end
+
+      # The count of covered items for a single criterion across the reported files
+      # @param criterion [Symbol]
+      # @return [Integer]
+      def covered_count(criterion)
+        plural = CRITERION_LABELS.fetch(criterion).last
+        reported_files.sum { |file| file.public_send(:"covered_#{plural}").count }
+      end
+
       # The full listing, one blank-line-separated section per criterion
       # @return [String]
       def detailed_text
@@ -99,7 +262,7 @@ module SimpleCov
       # @param criterion [Symbol]
       # @return [Array<String>]
       def uncovered_items(criterion)
-        result.files.flat_map { |file| items_for(file, criterion) }
+        reported_files.flat_map { |file| items_for(file, criterion) }
       end
 
       # The count of uncovered items for a single criterion across all files
@@ -107,7 +270,7 @@ module SimpleCov
       # @param criterion [Symbol]
       # @return [Integer]
       def uncovered_count(criterion)
-        result.files.sum { |file| count_for(file, criterion) }
+        reported_files.sum { |file| count_for(file, criterion) }
       end
 
       # The formatted, uncovered items of one criterion within a single file

data/lib/simplecov-rspec/version.rb

@@ -3,6 +3,6 @@
 module Simplecov
   class Rspec
     # This gem's version
-    VERSION = '1.0.0'
+    VERSION = '1.1.0'
   end
 end

data/lib/simplecov-rspec.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'simplecov'
+require_relative 'simplecov-rspec/described_source_files'
+require_relative 'simplecov-rspec/list_uncovered_files_option'
 require_relative 'simplecov-rspec/list_uncovered_option'
 require_relative 'simplecov-rspec/uncovered_report'
 
@@ -11,11 +13,12 @@ module SimpleCov
   #
   # SimpleCov (>= 1.0) can already enforce `minimum_coverage` for line, branch, and
   # method coverage, and will exit with a non-zero status when a threshold is missed.
-  # This gem layers three things SimpleCov doesn't do on its own:
+  # This gem layers four things 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. Lets all of the above be overridden from the environment, for CI.
+  # 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.
   #
   # Simply add the line `SimpleCov::RSpec.start` in place of `SimpleCov.start` in
   # the project's `spec_helper.rb`. This line must appear before the project is
@@ -33,6 +36,9 @@ module SimpleCov
   # @example Report only counts, with a hint on how to see the details
   #   SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_detail: false)
   #
+  # @example Scope the listing to the code the run described
+  #   SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: :described)
+  #
   # @example Pass a configuration block to SimpleCov.start
   #   SimpleCov::RSpec.start { formatter SimpleCov::Formatter::LcovFormatter }
   #
@@ -100,6 +106,27 @@ module SimpleCov
     #     Read from the `LIST_UNCOVERED_DETAIL` environment variable if set: `true`,
     #     `yes`, `on`, or `1` (case-insensitive) shows details; anything else summarizes.
     #
+    #   @param list_uncovered_files [nil, Symbol, String, Array<String>, #call] which files to
+    #     list uncovered items for (default: nil)
+    #
+    #     `nil` reports on every file in the result. A String or Array of Strings names
+    #     the files to report on, as `Dir.glob` patterns resolved against `SimpleCov.root`.
+    #     `:described` reports on the files defining the classes the run described, which
+    #     is the scope a focused run usually wants. A callable returning a String or an
+    #     Array of Strings is resolved after the run rather than at `start`, which is what
+    #     any scope derived from the run needs: `start` runs before any example is defined.
+    #
+    #     This narrows only the uncovered listing. Coverage is still measured, enforced,
+    #     and formatted for the whole project, so the percentage and the HTML report mean
+    #     the same thing whether or not this is set.
+    #
+    #     A scoped report names how many of the result's files it covered, and says so
+    #     explicitly when they are fully covered or when nothing matched.
+    #
+    #     Read from the `LIST_UNCOVERED_FILES` environment variable if set: a
+    #     comma-separated list of patterns, `described`, or `all` (or `false`, `no`,
+    #     `off`, `0`, or empty) for every file.
+    #
     #   @param start_config_block [Proc] a configuration block to pass to `SimpleCov.start` (default: nil)
     #
     #   @param rspec_dry_run [Boolean] whether the rspec run is a dry run
@@ -132,8 +159,45 @@ module SimpleCov
     #     # OR use an environment variable to override the default
     #     LIST_UNCOVERED=all rspec
     #
+    #   @example List uncovered items for one file only
+    #     SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: 'lib/example_project/parser.rb')
+    #
+    #     # OR use an environment variable to override the default
+    #     LIST_UNCOVERED_FILES=lib/example_project/parser.rb rspec
+    #
+    #   @example Scope the listing to the classes the run actually described
+    #     SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: :described)
+    #
+    #     # OR use an environment variable to override the default
+    #     LIST_UNCOVERED_FILES=described rspec
+    #
     def self.start(...) = new(...).send(:start)
 
+    # The source files defining the classes this RSpec run described
+    #
+    # What `list_uncovered_files: :described` scopes to. Call it directly to build a
+    # scope of your own — to add files the run touches but does not describe, say:
+    #
+    #     list_uncovered_files: -> { SimpleCov::RSpec.described_source_files + ['lib/support.rb'] }
+    #
+    # Only meaningful once the run has defined its examples, which is why it is passed
+    # as a callable rather than called at `start`.
+    #
+    # A described class contributes nothing when it is anonymous, defined in C, or no
+    # longer reachable by name, since there is no source file to report on.
+    #
+    # @example Scope the listing to the code under test, plus one more file
+    #   SimpleCov::RSpec.start(
+    #     list_uncovered: :all,
+    #     list_uncovered_files: -> { SimpleCov::RSpec.described_source_files + ['lib/support.rb'] }
+    #   )
+    #
+    # @return [Array<String>] absolute paths, without duplicates
+    #
+    # @api public
+    #
+    def self.described_source_files = DescribedSourceFiles.call
+
     # Environment variable to override minimum_coverage[:line]
     # @api private
     # @private
@@ -164,6 +228,11 @@ module SimpleCov
     # @private
     LIST_UNCOVERED_DETAIL = 'LIST_UNCOVERED_DETAIL'
 
+    # Environment variable to override list_uncovered_files
+    # @api private
+    # @private
+    LIST_UNCOVERED_FILES = 'LIST_UNCOVERED_FILES'
+
     # Maps a coverage criterion to the environment variable that overrides its threshold
     # @api private
     # @private
@@ -245,6 +314,23 @@ module SimpleCov
       @list_uncovered_criteria ||= ListUncoveredOption.resolve(@list_uncovered, env: env, env_var: LIST_UNCOVERED)
     end
 
+    # The files to list uncovered items for, or nil for every file in the result
+    #
+    # Resolved from the `at_exit` hook rather than at `start`: `start` runs before any
+    # example is defined, so a caller scoping the report to the code under test cannot
+    # know which files those are until the run is over.
+    #
+    # @return [Array<String>, nil]
+    #
+    # @api private
+    # @private
+    #
+    def list_uncovered_files
+      ListUncoveredFilesOption.resolve(
+        @list_uncovered_files, env: env, env_var: LIST_UNCOVERED_FILES, root: simplecov_module.root
+      )
+    end
+
     # Whether to list individual uncovered items, or just a count per criterion
     #
     # @return [Boolean]
@@ -281,6 +367,7 @@ module SimpleCov
       fail_on_low_coverage: nil,
       list_uncovered: nil,
       list_uncovered_detail: nil,
+      list_uncovered_files: nil,
       rspec_dry_run: ::RSpec.configuration.dry_run?,
       env: ENV,
       simplecov_module: ::SimpleCov,
@@ -290,6 +377,7 @@ module SimpleCov
       @fail_on_low_coverage = fail_on_low_coverage
       @list_uncovered = list_uncovered
       @list_uncovered_detail = list_uncovered_detail
+      @list_uncovered_files = list_uncovered_files
       @start_config_block = start_config_block
       @rspec_dry_run = rspec_dry_run
       @env = env
@@ -340,10 +428,8 @@ module SimpleCov
       return if list_uncovered_criteria.empty?
 
       report = UncoveredReport.new(
-        result: simplecov_module.result,
-        criteria: list_uncovered_criteria,
-        detail: list_uncovered_detail?,
-        detail_env_var: LIST_UNCOVERED_DETAIL
+        result: simplecov_module.result, criteria: list_uncovered_criteria, detail: list_uncovered_detail?,
+        detail_env_var: LIST_UNCOVERED_DETAIL, files: list_uncovered_files
       ).to_s
       return if report.empty?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simplecov-rspec
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - James Couball
@@ -214,7 +214,8 @@ dependencies:
 description: |
   Configures SimpleCov's line, branch, and method coverage thresholds for RSpec,
   suppresses failures during RSpec dry runs, and (optionally) lists or summarizes
-  the lines, branches, and methods not covered by tests.
+  the lines, branches, and methods not covered by tests, either for the whole
+  project or scoped to the code the run described.
 email:
 - jcouball@yahoo.com
 executables: []
@@ -234,6 +235,8 @@ files:
 - README.md
 - Rakefile
 - lib/simplecov-rspec.rb
+- lib/simplecov-rspec/described_source_files.rb
+- lib/simplecov-rspec/list_uncovered_files_option.rb
 - lib/simplecov-rspec/list_uncovered_option.rb
 - lib/simplecov-rspec/uncovered_report.rb
 - lib/simplecov-rspec/version.rb
@@ -246,8 +249,8 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/main-branch/simplecov-rspec
   source_code_uri: https://github.com/main-branch/simplecov-rspec
-  documentation_uri: https://rubydoc.info/gems/simplecov-rspec/1.0.0
-  changelog_uri: https://rubydoc.info/gems/simplecov-rspec/1.0.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/simplecov-rspec/1.1.0
+  changelog_uri: https://rubydoc.info/gems/simplecov-rspec/1.1.0/file/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: