yard-rspec-coverage 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4579697cc4b66cd8e8f2542925a108797ed295a4ef8c1584a669f9d6a5e0a79
-  data.tar.gz: 04766fba38fc646ad5682f4c7e5d2a797059074e5b83bda4812743d2fa1f186f
+  metadata.gz: 92e79bd5a908db3cedd4c50b47932d17429ee4ea97be3bf4fc9051925f07214e
+  data.tar.gz: 456788b68888517279dc5aa9362d4512cc147499fba916e0ba2a3dc45d2ee723
 SHA512:
-  metadata.gz: 786fe926ae8c6260b343c25b918fd2f9b568fac0a9fe2e508a8fedb2c9dbae578a4a7303ddc34ed2bcd1942837c58f16d83704b1203a0b64b95b16c88eb4b623
-  data.tar.gz: c99f4df51422c71ddec7c5931662c6ad375c7a9f53b5dd9359956a69bb4096a0ff499f4d083373c48591676992fdf43aae5950cf5119b0c925afcf24c2fb3fd5
+  metadata.gz: c70ce69ec8af7fcd6490acbd4f135be002a87241b6ef66da05caebd5ce8d4c7aa44ee52c8a75949dc35abc405b1419a44e3a46f6cc3f5e688f86a84b2aa6e09d
+  data.tar.gz: 78ad8e219a770c7c8aeecf1b7ef8771e4222bc893764f0e8c67bc2c669af4936095bcb52886ddf1345df83ebb16686de75a56afeb527bc2ac5573563b26cef3e

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.2.0
+
+Changed (these can change the coverage result of a project):
+
+- `yard:rspec_coverage` parses only `YardRspec::Config.files`. The options in `.yardopts`, such
+  as `--exclude`, still apply, but the files listed there are no longer added.
+- Classes, modules and methods that spec files define outside describe blocks, such as helpers
+  in `spec/support`, are left out of the documentation and of `yard stats`.
+- Files ending in `_helper.rb` outside a spec directory, such as Rails view helpers, count for
+  RSpec coverage again. Spec files are the files in a `spec/` directory and files ending in
+  `_spec.rb`.
+- An example without a block (`it 'spins twice'`) is pending, as in RSpec: it is labelled
+  "pending" and does not count as coverage.
+- A description that is not a string literal, such as `it format('runs %s', 1)`, is shown as
+  `example`. A description with interpolation is shown as written.
+
+Added:
+
+- Descriptions split over several lines (`it 'spins ' \ 'twice'`) are joined, as in RSpec.
+- `describe '.new'` and `describe '#new'` document `#initialize`, unless the class defines a
+  class method `new` itself.
+
+Fixed:
+
+- An exact coverage percentage failed an equal minimum, for example 57 of 100 methods against a
+  minimum of 57.
+- A describe of a class defined as a constant (`Widget = Class.new`), a spec file that reopens a
+  class of another gem, and describes or contexts without a block or without arguments no
+  longer stop the processing of a describe.
+- The plugin no longer keeps the syntax tree of every spec file in memory until the end of the
+  parse. In a project with about 600 spec files, peak memory dropped from 247 MB to 72 MB.
+- Looking up the described method is faster, especially in large projects.
+
 ## 0.1.3
 
 First public release as `yard-rspec-coverage`.

data/README.md

@@ -38,6 +38,10 @@ yard doc --plugin rspec-coverage 'lib/**/*.rb' 'spec/**/*.rb'
 List the spec files explicitly: without file arguments (or files in `.yardopts`) YARD only parses
 `lib/` and `app/`, so it finds no examples.
 
+The spec files are parsed for their examples only. Classes, modules and methods they define
+outside describe blocks, such as helpers in `spec/support`, are left out of the documentation and
+of `yard stats`. Spec files are the files in a `spec/` directory and files ending in `_spec.rb`.
+
 ### Rake tasks
 
 Declare the gem with `require: false` in your Gemfile, so you choose which YARD runs use the
@@ -56,9 +60,10 @@ This defines two tasks:
 - `rake yard:doc` generates the documentation with the `rspec-coverage` plugin. It writes to `doc/`, like
   other YARD tasks such as `yard:coverage`, so run it last.
 - `rake yard:rspec_coverage` lists the public methods without RSpec examples and fails when the
-  coverage is below `minimum_rspec_coverage`. Attribute readers/writers and aliases are not
-  counted. It also lists describe blocks that name a class or method that cannot be found, such
-  as a typo, without failing.
+  coverage is below `minimum_rspec_coverage`. Attribute readers/writers, aliases and code in
+  spec files are not counted. It also lists describe blocks that name a class or method that cannot be found, such
+  as a typo, without failing. It parses only `YardRspec::Config.files`: the options in
+  `.yardopts`, such as `--exclude`, apply, but the files listed there do not.
 
 The plugin never logs YARD warnings, so it is safe in YARD runs with `--fail-on-warning`.
 
@@ -113,11 +118,14 @@ The plugin supports the following RSpec syntax:
 
 - `describe ClassName, '#method_name'` for instance methods
 - `describe ClassName, '.method_name'` for class methods
-- `it "description"` blocks within describe blocks
+- `describe ClassName, '.new'` (or `'#new'`) for the constructor, documented as `#initialize`,
+  unless the class defines a class method `new` itself
+- `it "description"` blocks within describe blocks, also with a description split over several
+  lines as adjacent strings (`'spins ' \ 'twice'`)
 - `specify "description"` and `example "description"` blocks (aliases for `it`)
-- `xit`, `xspecify` and `xexample` blocks (excluded examples), shown with a "(pending)" suffix.
-  They do not count as coverage: a method with only pending examples is reported as without
-  specs.
+- `xit`, `xspecify` and `xexample` blocks (excluded examples) and examples without a block
+  (`it 'spins twice'`, which RSpec reports as "Not yet implemented"), labelled "pending". They do
+  not count as coverage: a method with only pending examples is reported as without specs.
 - nested `context "..."` and `describe "..."` blocks, shown as groups of examples
 
 ### Not supported
@@ -142,20 +150,21 @@ documentation and do not count towards RSpec coverage.
 
 Limitations of the supported constructs:
 
-- Only the text before the first interpolation of a description is kept: `it "loop #{index}"`
-  is shown as `loop `. Examples generated in a loop are listed once.
-- Examples whose description is not a string literal are shown as `example`.
+- A description is shown as written in the spec. So interpolation stays visible
+  (`it "loop #{index}"` is shown as `loop #{index}`) and so do escape sequences (`it "a\tb"` is
+  shown as `a\tb`, where RSpec shows a tab). Examples generated in a loop are listed once.
+- Examples whose description is not a string literal, or is empty, are shown as `example`. That
+  includes a heredoc (`it <<~DESC do`).
 
 ## Development
 
-To test the plugin with the example code:
+To build the plugin's own documentation, with its specs embedded:
 
 ```bash
-bundle install
 ./build.sh
 ```
 
-Then open `doc/index.html` in your browser to see the generated documentation.
+Then open `doc/index.html` in your browser. `build.sh` also runs all the checks below.
 
 Run all checks (RuboCop, a dependency vulnerability audit, the specs with SimpleCov, YARD
 documentation coverage and RSpec coverage) with:
@@ -166,11 +175,20 @@ bundle exec rake
 
 ### Releasing
 
-Update the version in `yard-rspec-coverage.gemspec` and `CHANGELOG.md`, then push a matching tag:
+Update the version in `yard-rspec-coverage.gemspec` and `CHANGELOG.md` (a `## <version>` heading
+instead of `## Unreleased`), commit, and run the checks for a release:
+
+```bash
+bundle exec rake prerelease
+```
+
+It checks the commit, runs `rake` and `yard:doc`, builds and tests the gem, and runs mutation
+testing. Set `COMPARE_PROJECT` (and `COMPARE_RSPEC`) to also compare the plugin with
+`rspec --dry-run` in a real project, see `AGENTS.md`. Then push a matching tag:
 
 ```bash
-git tag v0.1.3
-git push origin v0.1.3
+git tag v0.2.0
+git push origin v0.2.0
 ```
 
 The release workflow runs all checks and publishes the gem to rubygems.org with

data/lib/tasks/yard_rspec.rake

@@ -3,49 +3,7 @@
 # The tasks load the plugin when they run; loading it here would affect every YARD run in Rake.
 require 'yard'
 require_relative '../yard_rspec/config'
-
-# @param [<YARD::CodeObjects::MethodObject>] uncovered
-def uncovered_methods_report(uncovered)
-  return if uncovered.empty?
-
-  puts "\nMethods without RSpec specs:"
-  uncovered.sort_by(&:path).each do |method|
-    puts "  #{method.file}:#{method.line}: #{method.path}"
-  end
-end
-
-# @param [<YARD::CodeObjects::MethodObject>] public_lib_methods
-# @return [Float] The coverage percentage.
-def rspec_coverage_report(public_lib_methods)
-  total     = public_lib_methods.size
-  uncovered = public_lib_methods.reject {|method| YardRspec::Coverage.covered?(method)}
-  covered   = total - uncovered.size
-  coverage  = total.positive? ? (covered.to_f / total * 100).round(2) : 100.0
-
-  puts format('RSpec coverage: %<covered>d/%<total>d (%<coverage>.2f%%)',
-              covered:, total:, coverage:)
-  uncovered_methods_report(uncovered)
-
-  coverage
-end
-
-# Applies .yardopts like `yard doc` does, so --exclude works. --no-output skips the markup check.
-# @param [<String>] files Glob patterns; they replace the files in .yardopts.
-# @return [YARD::CLI::Yardoc]
-def yardoc_with_yardopts(files)
-  yardoc = YARD::CLI::Yardoc.new
-  yardoc.parse_arguments('--no-output', *files)
-  yardoc
-end
-
-# These do not fail the coverage check.
-# @param [<String>] describe_problems
-def describe_problems_report(describe_problems)
-  return if describe_problems.empty?
-
-  puts "\nDescribe blocks without a matching class or method:"
-  describe_problems.each {|describe_problem| puts "  #{describe_problem}"}
-end
+require_relative '../yard_rspec/task_reports'
 
 namespace :yard do
   desc 'Generate YARD documentation with the yard-rspec-coverage plugin'
@@ -59,16 +17,16 @@ namespace :yard do
   task :rspec_coverage do
     require_relative '../yard-rspec-coverage'
     YARD::Registry.clear
-    yardoc = yardoc_with_yardopts(YardRspec::Config.files)
+    yardoc = YardRspec::TaskReports.yardoc_with_yardopts(YardRspec::Config.files)
     YARD.parse(yardoc.files, yardoc.excluded, YARD::Logger::ERROR)
 
-    coverage = rspec_coverage_report(YardRspec::Coverage.countable_methods)
-    describe_problems_report(YardRspec::DescribeProblems.all)
+    coverage = YardRspec::TaskReports.rspec_coverage(YardRspec::Coverage.countable_methods)
+    YardRspec::TaskReports.describe_problems(YardRspec::DescribeProblems.all)
     minimum = YardRspec::Config.minimum_rspec_coverage
 
     if coverage < minimum
       warn format("\nRSpec coverage too low: %<coverage>.2f%% (minimum is %<minimum>.2f%%)",
-                  coverage:, minimum:)
+                  coverage: coverage.floor(2), minimum:)
       exit 1
     end
   end

data/lib/yard-rspec-coverage.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 require 'yard'
+require_relative 'yard_rspec/ast_helpers'
 require_relative 'yard_rspec/config'
 require_relative 'yard_rspec/coverage'
 require_relative 'yard_rspec/describe_problems'
 require_relative 'yard_rspec/example_extractor'
 require_relative 'yard_rspec/method_description'
+require_relative 'yard_rspec/nested_method_describes'
+require_relative 'yard_rspec/parsed_describe'
 require_relative 'yard_rspec/handler'
+require_relative 'yard_rspec/spec_objects'
 require_relative 'yard_rspec/stats'
+require_relative 'yard_rspec/unquote'
 
 YARD::Templates::Engine.register_template_path File.expand_path('../templates', __dir__)

data/lib/yard_rspec/ast_helpers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module YardRspec
+  # Checks on YARD's Ruby AST that the handler, the example extractor and the nested describe
+  # scanner share, so that they agree on which calls are describes.
+  module AstHelpers
+    private
+
+    # @return [Boolean]
+    def ast_node?(node)
+      node.is_a?(YARD::Parser::Ruby::AstNode)
+    end
+
+    # @param [YARD::Parser::Ruby::MethodCallNode] call_node A command such as `describe Widget`.
+    # @return [Boolean]
+    def describe_or_context_call?(call_node)
+      %i[describe context].include?(call_node.method_name(true))
+    end
+
+    # @param [YARD::Parser::Ruby::MethodCallNode] call_node A command such as `it 'spins' do end`.
+    # @return [YARD::Parser::Ruby::AstNode, nil] The statements in the block, nil without a block.
+    def block_body_of(call_node)
+      call_node.block&.last
+    end
+  end
+end

data/lib/yard_rspec/coverage.rb

@@ -3,27 +3,33 @@
 module YardRspec
   # Which methods count for RSpec coverage.
   module Coverage
-    # @return [Regexp] Spec and helper files, whose methods need no specs.
-    SPEC_FILE_PATTERN = %r{(?:^|/)spec/|_spec\.rb$|_helper\.rb$}
+    # @return [Regexp] Files in a spec directory or ending in _spec.rb. Not any _helper.rb, which
+    #   would include Rails view helpers.
+    SPEC_FILE_PATTERN = %r{(?:^|/)spec/|_spec\.rb$}
 
-    # @return [<YARD::CodeObjects::MethodObject>]
+    # @param [String] file
+    # @return [Boolean] Whether the file is spec code, which needs no specs and no documentation.
+    def self.spec_file?(file)
+      file.match?(SPEC_FILE_PATTERN)
+    end
+
+    # @return [<YARD::CodeObjects::MethodObject>] The methods that need specs, see {countable?}.
     def self.countable_methods
       YARD::Registry.all(:method).select {|method| countable?(method)}
     end
 
-    # Attributes and aliases have no behaviour of their own to spec.
     # @param [YARD::CodeObjects::MethodObject] method
-    # @return [Boolean]
+    # @return [Boolean] True for a public method outside spec files. Attributes and aliases are
+    #   left out: they have no behaviour of their own.
     def self.countable?(method)
       method.visibility == :public &&
-        !method.file.to_s.match?(SPEC_FILE_PATTERN) &&
+        !spec_file?(method.file.to_s) &&
         !method.is_attribute? &&
         !method.is_alias?
     end
 
-    # Pending examples (`xit`) do not run, so they do not count.
     # @param [YARD::CodeObjects::MethodObject] method
-    # @return [Boolean]
+    # @return [Boolean] Whether it has an example that is not pending: `xit` does not run.
     def self.covered?(method)
       examples(method[:rspec_examples] || []).any? {|example| !example[:pending]}
     end

data/lib/yard_rspec/describe_problems.rb

@@ -20,5 +20,13 @@ module YardRspec
     def self.all
       (YARD::Registry.root[REGISTRY_KEY] || []).sort
     end
+
+    # Records an error as a problem instead of letting YARD log it, so the parse goes on.
+    # @param [String] location 'file:line' of the describe.
+    def self.recording_failure(location)
+      yield
+    rescue StandardError => e
+      add("#{location}: could not process the describe: #{e.class}: #{e.message}")
+    end
   end
 end

data/lib/yard_rspec/example_extractor.rb

@@ -4,11 +4,13 @@ module YardRspec
   # Extracts the RSpec examples of a describe block as a tree of example and context nodes.
   # Excluded examples (xit/xspecify/xexample) get `pending: true`.
   class ExampleExtractor
-    # @return [<String>] The keywords of examples that RSpec runs.
-    EXAMPLE_KEYWORDS = %w[it specify example].freeze
+    include AstHelpers
 
-    # @return [<String>] The keywords of examples that RSpec excludes from the run.
-    PENDING_KEYWORDS = %w[xit xspecify xexample].freeze
+    # @return [<Symbol>] The keywords of examples that RSpec excludes from the run.
+    PENDING_KEYWORDS = %i[xit xspecify xexample].freeze
+
+    # @return [<Symbol>] The keywords of all examples, including the pending ones.
+    KEYWORDS = (%i[it specify example] + PENDING_KEYWORDS).freeze
 
     # @param [YARD::Parser::Ruby::AstNode, nil] block_node The body of a describe block.
     def initialize(block_node)
@@ -27,8 +29,6 @@ module YardRspec
     private
 
     def traverse(node, nodes)
-      return if !ast_node?(node)
-
       if example_call?(node)
         nodes << build_example(node)
       elsif context_call?(node)
@@ -38,106 +38,77 @@ module YardRspec
       end
     end
 
-    # A context without examples is left out.
+    # A context without a block or without examples is left out.
     def add_context(node, nodes)
+      block_body = block_body_of(node) or return
       children = []
-      traverse(node.last&.last, children)
+      traverse(block_body, children)
       return if children.empty?
 
-      nodes << { description: extract_context_description(node), children: children }
+      nodes << { description: string_literal_text(node.parameters.first), children: children }
     end
 
-    # Includes the `x` variants.
-    # @return [Boolean]
+    # @return [Boolean] Includes the `x` variants.
     def example_call?(node)
-      return false if node.type != :command
-
-      name_node = node.children[0]
-      name_node&.type == :ident && (EXAMPLE_KEYWORDS + PENDING_KEYWORDS).include?(name_node.source)
+      node.type == :command && KEYWORDS.include?(node.method_name(true))
     end
 
     # @return [Boolean]
     def context_call?(node)
-      return false if node.type != :command
-
-      name_node = node.children[0]
-      name_node&.type == :ident && %w[context describe].include?(name_node.source)
+      node.type == :command && describe_or_context_call?(node)
     end
 
-    # @return [String, nil]
-    def extract_context_description(node)
-      find_string_literal(node.parameters.first)
-    end
-
-    # @return [Hash] With `pending: true` only for the `x` variants.
+    # @return [Hash] With `pending: true` only for the `x` variants and examples without a block,
+    #   which RSpec reports as pending.
     def build_example(node)
       example = {
-        description: extract_description(node.children[1]) || 'example',
-        code: extract_code(node.children[2])
+        description: string_literal_text(node.parameters.first) || 'example',
+        code: extract_code(block_body_of(node))
       }
-      example[:pending] = true if PENDING_KEYWORDS.include?(node.children[0].source)
+      example[:pending] = true if pending_example?(node)
       example
     end
 
-    # @return [String, nil]
-    def extract_description(args_node)
-      return nil if !ast_node?(args_node)
-
-      find_string_literal(args_node)
+    # @return [Boolean]
+    def pending_example?(node)
+      PENDING_KEYWORDS.include?(node.method_name(true)) || block_body_of(node).nil?
     end
 
-    # @return [String, nil] The first one at any depth.
-    def find_string_literal(node)
-      return nil if !ast_node?(node)
-      return extract_string_content(node) if node.type == :string_literal
-
-      node.children.each do |child|
-        result = find_string_literal(child)
-        return result if result
-      end
-      nil
+    # @param [YARD::Parser::Ruby::AstNode] argument The first argument of a call.
+    # @return [String, nil] The text as written, so with interpolations such as `#{count}`; nil if
+    #   empty or not a string literal, such as `format('runs %s', count)`.
+    def string_literal_text(argument)
+      text = string_text(argument)
+      text if text && !text.empty?
     end
 
-    # @return [String, nil]
-    def extract_string_content(string_literal_node)
-      string_literal_node.children.each do |child|
-        next if !ast_node?(child) || child.type != :string_content
-
-        child.children.each do |grandchild|
-          return grandchild.source if grandchild.is_a?(YARD::Parser::Ruby::AstNode) &&
-                                      grandchild.type == :tstring_content
-        end
+    # @return [String, nil] Nil when the node is not a string literal. Adjacent literals
+    #   (`'runs ' \ 'twice'`) are joined, as RSpec sees them.
+    def string_text(node)
+      case node.type
+      when :string_literal
+        node.children.find {|child| child.type == :string_content}.children.map(&:source).join
+      when :string_concat
+        node.children.map {|child| string_text(child)}.join
       end
-      nil
     end
 
-    # @return [String]
-    def extract_code(block_node)
-      return '' if !ast_node?(block_node)
-      return '' if !%i[do_block brace_block].include?(block_node.type)
-
-      body = block_node.children.first
-      return '' if !ast_node?(body)
+    # @param [YARD::Parser::Ruby::AstNode, nil] block_body
+    # @return [String] Empty without a block.
+    def extract_code(block_body)
+      return '' if block_body.nil?
 
       # The source starts at the first token; restore its indentation before dedenting.
-      dedent((' ' * column_of(body)) + body.source.strip)
+      dedent((' ' * column_of(block_body)) + block_body.source)
     end
 
-    # @return [Integer] 0 if unknown.
+    # @return [Integer]
     def column_of(node)
-      file_source = node.full_source
-      start = node.source_range&.first
-      return 0 if file_source.nil? || start.nil? || start.zero?
-
-      newline_before = file_source.rindex("\n", start - 1)
+      start = node.source_range.first
+      newline_before = node.full_source.rindex("\n", start - 1)
       newline_before.nil? ? start : start - newline_before - 1
     end
 
-    # @return [Boolean]
-    def ast_node?(node)
-      node.is_a?(YARD::Parser::Ruby::AstNode)
-    end
-
     # @return [String]
     def dedent(source)
       lines = source.lines.map(&:rstrip)

data/lib/yard_rspec/handler.rb

@@ -2,39 +2,54 @@
 
 module YardRspec
   # Attaches the examples of RSpec describe blocks to the described methods, as :rspec_examples.
-  # When parsing a file list, describes are processed after all files: YARD postpones files with
-  # unknown namespaces, so a spec may be parsed before its class.
+  # When parsing a file list, the examples are attached after all files: YARD postpones files with
+  # unknown namespaces, so a spec may be parsed before its class. The syntax tree is read right
+  # away, so that a waiting describe (a ParsedDescribe) does not keep it alive.
   class DescribeHandler < YARD::Handlers::Ruby::Base
+    include AstHelpers
+
     handles method_call(:describe)
     handles method_call(:context)
     namespace_only
 
-    # Deferred while parsing a file list, see the callbacks at the end of this file.
+    # @return [Regexp] A class name such as 'Widget' or 'Shop::Widget', not a topic such as
+    #   'Spinning semantics'.
+    CLASS_NAME = /\A[A-Z][A-Za-z0-9_:]*\z/
+
+    # Deferred while parsing a file list, see the callbacks at the end of this file. There a
+    # failure is recorded as a describe problem, so it does not abort the parse.
     def process
-      @describe_namespace = namespace
-      if globals.yard_rspec_deferred_describes
-        globals.yard_rspec_deferred_describes << -> {process_describe}
-      else
-        process_describe
+      deferred = globals.yard_rspec_deferred_describes
+      return parse_describe&.attach if deferred.nil?
+
+      DescribeProblems.recording_failure(location_of) do
+        parsed = parse_describe
+        deferred << parsed if parsed
       end
     end
 
     private
 
-    def process_describe
-      obj_name = unquote(statement.parameters.first.source)
-
-      # Method-only describes (describe '#eql?') are handled by their outer describe.
-      target_namespace = resolve_namespace(obj_name)
-      return if target_namespace.nil?
+    # Method-only describes (describe '#eql?') are handled by their outer describe.
+    # @return [ParsedDescribe, nil] Nil for a describe without a class name.
+    def parse_describe
+      class_name = described_name
+      return nil if class_name.nil? || !class_name.match?(CLASS_NAME)
 
       description = extract_method_description
-      if description
-        document_method(target_namespace, obj_name, description, statement.last&.last,
-                        location_of)
-      else
-        process_nested_describes(target_namespace, obj_name)
-      end
+      entries = if description
+                  [entry(description, block_body_of(statement), statement.line)]
+                else
+                  nested_entries
+                end
+      ParsedDescribe.new(namespace: namespace, class_name: class_name, location: location_of,
+                         entries: entries)
+    end
+
+    # @return [String, nil] The first describe parameter; nil for `describe do`.
+    def described_name
+      first_parameter = statement.parameters.first
+      Unquote.call(first_parameter.source) if ast_node?(first_parameter)
     end
 
     # @return [MethodDescription, nil] From the second describe parameter.
@@ -42,108 +57,30 @@ module YardRspec
       second_param = statement.parameters[1]
       return nil if !ast_node?(second_param)
 
-      MethodDescription.parse(unquote(second_param.source))
-    end
-
-    # Records a describe problem for an unknown class, unless it is loaded at runtime: a class
-    # from another gem (e.g. YARD::CLI::Stats) is not a typo.
-    # @return [YARD::CodeObjects::Base, nil]
-    def resolve_namespace(obj_name)
-      # Not a constant, e.g. describe 'Partial Order Reduction semantics'.
-      return nil if !obj_name.match?(/\A[A-Z][A-Za-z0-9_:]*\z/)
-
-      return @describe_namespace if obj_name == @describe_namespace.name.to_s
-
-      resolved = YARD::Registry.resolve(@describe_namespace, obj_name, true)
-      if resolved.nil? && !loaded_constant?(obj_name)
-        DescribeProblems.add("#{location_of}: could not resolve class '#{obj_name}'")
-      end
-      resolved
+      MethodDescription.parse(Unquote.call(second_param.source))
     end
 
-    # @return [Boolean]
-    def loaded_constant?(obj_name)
-      Object.const_defined?(obj_name)
-    rescue NameError
-      false
-    end
+    # @return [<ParsedDescribe::Entry>] The nested '#method' describes.
+    def nested_entries
+      block_body = block_body_of(statement)
+      return [] if block_body.nil?
 
-    # A missing method is a describe problem, unless the description is imprecise.
-    def document_method(target_namespace, obj_name, description, block_body, location)
-      method_obj = description.find_in(target_namespace)
-      if method_obj
-        attach_examples_to(method_obj, block_body)
-      elsif !description.imprecise?
-        add_missing_method_problem(description, obj_name, location)
+      NestedMethodDescribes.new(block_body).map do |description, nested_block_body, line|
+        entry(description, nested_block_body, line)
       end
     end
 
-    def add_missing_method_problem(description, obj_name, location)
-      DescribeProblems.add("#{location}: could not find method '#{description}' " \
-                           "on '#{obj_name}'")
-    end
-
-    def attach_examples_to(method_obj, block_body)
-      examples = ExampleExtractor.new(block_body).extract
-      method_obj[:rspec_examples] ||= []
-      method_obj[:rspec_examples].concat(examples)
-    end
-
-    def process_nested_describes(target_namespace, obj_name)
-      block_body = statement.last&.last
-      return if block_body.nil?
-
-      each_method_describe(block_body) do |description, nested_block_body, node_line|
-        document_method(target_namespace, obj_name, description, nested_block_body,
-                        location_of(node_line))
-      end
-    end
-
-    # Yields the description, block body and line of each nested method describe.
-    def each_method_describe(node, &)
-      return if !ast_node?(node)
-
-      if method_describe_node?(node)
-        description = MethodDescription.parse(unquote(node.parameters.first.source))
-        yield(description, node.last&.last, node.line)
-      else
-        node.children.each {|child| each_method_describe(child, &)}
-      end
-    end
-
-    # @return [Boolean]
-    def method_describe_node?(node)
-      return false if node.type != :command
-
-      name_node = node.children[0]
-      return false if !describe_or_context_call?(name_node)
-
-      first_param = node.parameters.first
-      return false if !ast_node?(first_param)
-
-      unquote(first_param.source).start_with?('#', '.')
-    rescue StandardError
-      false
-    end
-
-    # @return [Boolean]
-    def describe_or_context_call?(name_node)
-      name_node&.type == :ident && %w[describe context].include?(name_node.source)
-    end
-
-    # @return [Boolean]
-    def ast_node?(node)
-      node.is_a?(YARD::Parser::Ruby::AstNode)
-    end
-
-    # @return [String]
-    def unquote(source)
-      source.gsub(/['"]/, '')
+    # @param [MethodDescription, nil] description
+    # @param [YARD::Parser::Ruby::AstNode, nil] block_body
+    # @return [ParsedDescribe::Entry]
+    def entry(description, block_body, line)
+      ParsedDescribe::Entry.new(description, ExampleExtractor.new(block_body).extract,
+                                location_of(line))
     end
 
     # @return [String] 'file:line', by default the line of the statement.
-    def location_of(line = statement.line || '?')
-      "#{statement.file || '(unknown)'}:#{line}"
+    def location_of(line = statement.line)
+      "#{statement.file}:#{line}"
     end
   end
 end
@@ -153,6 +90,10 @@ YARD::Parser::SourceParser.before_parse_list do |_files, global_state|
   nil # Returning false would cancel the parse.
 end
 
+# Spec objects are removed only after the examples have been attached.
 YARD::Parser::SourceParser.after_parse_list do |_files, global_state|
-  global_state.yard_rspec_deferred_describes.each(&:call)
+  global_state.yard_rspec_deferred_describes.each do |parsed_describe|
+    YardRspec::DescribeProblems.recording_failure(parsed_describe.location) {parsed_describe.attach}
+  end
+  YardRspec::SpecObjects.remove
 end

data/lib/yard_rspec/method_description.rb

@@ -4,7 +4,7 @@ module YardRspec
   # The method named by a describe string such as '#run', '.build' or '#initialize via Factory'.
   class MethodDescription
     # @return [Regexp] '#' (instance) or '.' (class), followed by the method name.
-    PATTERN = /^([#.])(\S+)/
+    PATTERN = /\A([#.])(\S+)/
 
     # @return [String]
     attr_reader :name
@@ -31,9 +31,8 @@ module YardRspec
       @imprecise = imprecise
     end
 
-    # Whether text follows the method name, as in '#initialize via SomeFactory'. A missing method
-    # is then not reported.
-    # @return [Boolean]
+    # @return [Boolean] Whether text follows the method name, as in '#initialize via SomeFactory'.
+    #   A missing method is then not reported.
     def imprecise?
       @imprecise
     end
@@ -43,20 +42,23 @@ module YardRspec
       "#{@scope == :instance ? '#' : '.'}#{name}"
     end
 
-    # Falls back to the other scope, because specs sometimes write '#' for class methods.
     # @param [YARD::CodeObjects::NamespaceObject] namespace
-    # @return [YARD::CodeObjects::MethodObject, nil] Also searched in superclasses and mixins.
+    # @return [YARD::CodeObjects::MethodObject, nil] Searched in superclasses and mixins too. Falls
+    #   back to the other scope, since specs sometimes write '#' for class methods, and from 'new'
+    #   to #initialize, which YARD documents for the constructor.
     def find_in(namespace)
-      find_with_scope(namespace, @scope) || find_with_scope(namespace, other_scope)
+      find_with_scope(namespace, @scope, name) || find_with_scope(namespace, other_scope, name) ||
+        (find_with_scope(namespace, :instance, 'initialize') if name == 'new')
     end
 
     private
 
-    # Includes mixins, so examples end up on the module's method. Own methods come first.
-    def find_with_scope(namespace, scope)
-      namespace
-        .meths(scope: scope, visibility: %i[public protected private], included: true)
-        .find {|method| method.name.to_s == name}
+    # Includes superclasses and mixins, so examples end up on the module's method. Own methods
+    # come first, found directly: the full list takes time quadratic in the number of methods.
+    def find_with_scope(namespace, scope, method_name)
+      namespace.child(name: method_name.to_sym, scope: scope, type: :method) ||
+        namespace.meths(scope: scope, visibility: %i[public protected private], included: true)
+                 .find {|method| method.name.to_s == method_name}
     end
 
     def other_scope

data/lib/yard_rspec/nested_method_describes.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module YardRspec
+  # The `describe '#method'` and `describe '.method'` blocks nested in a describe block.
+  class NestedMethodDescribes
+    include Enumerable
+    include AstHelpers
+
+    # @param [YARD::Parser::Ruby::AstNode] block_body The body of the outer describe block.
+    def initialize(block_body)
+      @block_body = block_body
+    end
+
+    # @yieldparam [MethodDescription, nil] description Nil if the string names no method, as in
+    #   `describe '#'`.
+    # @yieldparam [YARD::Parser::Ruby::AstNode, nil] block_body The body of the nested block, nil
+    #   without a block.
+    # @yieldparam [Integer] line
+    def each(&)
+      return enum_for(:each) if !block_given?
+
+      walk(@block_body, &)
+    end
+
+    private
+
+    # Does not look inside a method describe.
+    def walk(node, &)
+      if method_describe_node?(node)
+        description = MethodDescription.parse(source_of(node.parameters.first))
+        yield(description, block_body_of(node), node.line)
+      else
+        node.children.each {|child| walk(child, &)}
+      end
+    end
+
+    # @return [Boolean]
+    def method_describe_node?(node)
+      node.type == :command && describe_or_context_call?(node) &&
+        source_of(node.parameters.first).start_with?('#', '.')
+    end
+
+    # @return [String] Without quotes.
+    def source_of(node)
+      Unquote.call(node.source)
+    end
+  end
+end

data/lib/yard_rspec/parsed_describe.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module YardRspec
+  # What DescribeHandler takes from a describe block's syntax tree: the class name and, per
+  # described method, its examples. It keeps no syntax tree, so a describe that waits for the end
+  # of a file list parse does not keep its spec file's tree alive (about 0.25 MB per spec file).
+  class ParsedDescribe
+    # One described method, with its examples.
+    # @attr [MethodDescription, nil] description Nil if the describe string names no method, as in
+    #   `describe '#'`.
+    # @attr [<Hash>] examples See ExampleExtractor#extract.
+    # @attr [String] location 'file:line' of the describe of the method.
+    Entry = Struct.new(:description, :examples, :location)
+
+    # @return [String] 'file:line' of the describe.
+    attr_reader :location
+
+    # @param [YARD::CodeObjects::NamespaceObject] namespace Where the describe is; the class name
+    #   is resolved from there.
+    # @param [String] class_name As written, such as 'Widget' or 'Shop::Widget'.
+    # @param [String] location 'file:line' of the describe.
+    # @param [<Entry>] entries
+    def initialize(namespace:, class_name:, location:, entries:)
+      @namespace = namespace
+      @class_name = class_name
+      @location = location
+      @entries = entries
+    end
+
+    # Attaches the examples to the described methods, or records describe problems. Call it once
+    # the described classes are in the registry.
+    def attach
+      target = resolve_namespace or return
+      @entries.each {|entry| attach_entry(target, entry)}
+    end
+
+    private
+
+    # @return [YARD::CodeObjects::NamespaceObject, nil] Nil for an unknown class, recorded as a
+    #   problem unless it is loaded at runtime (a class of another gem is no typo), and for a
+    #   constant such as `Widget = Class.new`, whose methods YARD does not know.
+    def resolve_namespace
+      resolved = YARD::Registry.resolve(@namespace, @class_name, true)
+      if resolved.nil? && !loaded_constant?
+        DescribeProblems.add("#{@location}: could not resolve class '#{@class_name}'")
+      end
+      resolved if resolved.is_a?(YARD::CodeObjects::NamespaceObject)
+    end
+
+    # @return [Boolean]
+    def loaded_constant?
+      Object.const_defined?(@class_name)
+    rescue NameError
+      false
+    end
+
+    # A missing method is a describe problem, unless the description is imprecise.
+    def attach_entry(target, entry)
+      description = entry.description
+      if description.nil?
+        DescribeProblems.add("#{entry.location}: could not parse the method name of the describe")
+      elsif (method_obj = description.find_in(target))
+        (method_obj[:rspec_examples] ||= []).concat(entry.examples)
+      elsif !description.imprecise?
+        DescribeProblems.add("#{entry.location}: could not find method '#{description}' "\
+                             "on '#{@class_name}'")
+      end
+    end
+  end
+end

data/lib/yard_rspec/spec_objects.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module YardRspec
+  # The classes, modules and methods that spec files define outside describe blocks, such as
+  # helpers in spec/support. YARD parses the spec files for their examples, but their own code is
+  # no part of the documentation, nor of `yard stats`.
+  module SpecObjects
+    # Removes objects defined only in spec files, and the spec files from the files of the others,
+    # such as a class that a spec reopens.
+    def self.remove
+      YARD::Registry.all.each do |object|
+        own_files = object.files.reject {|file, _line| Coverage.spec_file?(file)}
+        next if own_files == object.files
+
+        own_files.empty? ? delete(object) : object.files.replace(own_files)
+      end
+    end
+
+    # A namespace from another gem (`class Rack::Static::Middleware`) is a proxy without children.
+    # @param [YARD::CodeObjects::Base] object
+    def self.delete(object)
+      namespace = object.namespace
+      namespace.children.delete(object) if !namespace.is_a?(YARD::CodeObjects::Proxy)
+      YARD::Registry.delete(object)
+    end
+    private_class_method :delete
+  end
+end

data/lib/yard_rspec/task_reports.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module YardRspec
+  # The output and options of the `yard:rspec_coverage` task. Not loaded into the global namespace
+  # by the rake file, since that would add the methods to every Rakefile that uses the plugin.
+  module TaskReports
+    # @param [<YARD::CodeObjects::MethodObject>] uncovered
+    def self.uncovered_methods(uncovered)
+      return if uncovered.empty?
+
+      puts "\nMethods without RSpec specs:"
+      uncovered.sort_by(&:path).each do |method|
+        puts "  #{method.file}:#{method.line}: #{method.path}"
+      end
+    end
+    private_class_method :uncovered_methods
+
+    # @param [<YARD::CodeObjects::MethodObject>] public_lib_methods
+    # @return [Float] The unrounded coverage percentage: rounding could pass a minimum of 100. It
+    #   is printed rounded down, so below 100 never shows as 100.00%.
+    def self.rspec_coverage(public_lib_methods)
+      total     = public_lib_methods.size
+      uncovered = public_lib_methods.reject {|method| YardRspec::Coverage.covered?(method)}
+      covered   = total - uncovered.size
+      coverage  = total.positive? ? covered * 100.0 / total : 100.0
+
+      puts format('RSpec coverage: %<covered>d/%<total>d (%<coverage>.2f%%)',
+                  covered:, total:, coverage: coverage.floor(2))
+      uncovered_methods(uncovered)
+
+      coverage
+    end
+
+    # @param [<String>] files Glob patterns; they replace the files in .yardopts, which YARD would
+    #   otherwise add them to.
+    # @return [YARD::CLI::Yardoc] With the options of .yardopts (so --exclude works) and no output.
+    def self.yardoc_with_yardopts(files)
+      yardoc = YARD::CLI::Yardoc.new
+      yardoc.parse_arguments('--no-output')
+      yardoc.files = files
+      yardoc
+    end
+
+    # @param [<String>] describe_problems Reported only; they do not fail the check.
+    def self.describe_problems(describe_problems)
+      return if describe_problems.empty?
+
+      puts "\nDescribe blocks without a matching class or method:"
+      describe_problems.each {|describe_problem| puts "  #{describe_problem}"}
+    end
+  end
+end

data/lib/yard_rspec/unquote.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module YardRspec
+  # Removes the quotes around the source of a string literal.
+  module Unquote
+    # @param [String] source For example `"'#run'"`.
+    # @return [String] Without the surrounding quotes only: `"it's"` stays `it's`.
+    def self.call(source)
+      source.sub(/\A(['"])(.*)\1\z/m, '\\2')
+    end
+  end
+end

data/templates/default/method_details/html/setup.rb

@@ -21,15 +21,15 @@ end
 # @return [String]
 def rspec_example_html(example)
   pending = example[:pending] ? ' <span class="rspec_label rspec_pending">pending</span>' : ''
-  "<li><details><summary>#{h(example[:description])}#{pending}</summary>" \
-    "<pre class=\"example code\">#{html_syntax_highlight(example[:code], :ruby)}</pre>" \
+  "<li><details><summary>#{h(example[:description])}#{pending}</summary>"\
+    "<pre class=\"example code\">#{html_syntax_highlight(example[:code], :ruby)}</pre>"\
     '</details></li>'
 end
 
 # @param [{description: String, children: [<Hash>]}] group
 # @return [String]
 def rspec_group_html(group)
-  '<li class="rspec_context">' \
-    "<span class=\"rspec_context_name\">#{h(group[:description])}</span>" \
+  '<li class="rspec_context">'\
+    "<span class=\"rspec_context_name\">#{h(group[:description])}</span>"\
     "<ul class=\"rspec\">#{rspec_nodes_html(group[:children])}</ul></li>"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-rspec-coverage
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - vdbijl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-31 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -36,14 +36,20 @@ files:
 - README.md
 - lib/tasks/yard_rspec.rake
 - lib/yard-rspec-coverage.rb
+- lib/yard_rspec/ast_helpers.rb
 - lib/yard_rspec/config.rb
 - lib/yard_rspec/coverage.rb
 - lib/yard_rspec/describe_problems.rb
 - lib/yard_rspec/example_extractor.rb
 - lib/yard_rspec/handler.rb
 - lib/yard_rspec/method_description.rb
+- lib/yard_rspec/nested_method_describes.rb
+- lib/yard_rspec/parsed_describe.rb
 - lib/yard_rspec/rake_tasks.rb
+- lib/yard_rspec/spec_objects.rb
 - lib/yard_rspec/stats.rb
+- lib/yard_rspec/task_reports.rb
+- lib/yard_rspec/unquote.rb
 - templates/default/fulldoc/html/css/rspec.css
 - templates/default/fulldoc/html/js/rspec.js
 - templates/default/layout/html/setup.rb
@@ -72,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: YARD plugin to display RSpec examples in documentation and report RSpec coverage