yard-rspec-coverage 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4579697cc4b66cd8e8f2542925a108797ed295a4ef8c1584a669f9d6a5e0a79
+  data.tar.gz: 04766fba38fc646ad5682f4c7e5d2a797059074e5b83bda4812743d2fa1f186f
+SHA512:
+  metadata.gz: 786fe926ae8c6260b343c25b918fd2f9b568fac0a9fe2e508a8fedb2c9dbae578a4a7303ddc34ed2bcd1942837c58f16d83704b1203a0b64b95b16c88eb4b623
+  data.tar.gz: c99f4df51422c71ddec7c5931662c6ad375c7a9f53b5dd9359956a69bb4096a0ff499f4d083373c48591676992fdf43aae5950cf5119b0c925afcf24c2fb3fd5

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.3
+
+First public release as `yard-rspec-coverage`.
+
+- The RSpec examples in the documentation have a new look:
+  - Example code is syntax-highlighted, like the method source.
+  - The heading shows the number of examples, with an "expand all" link when there is more
+    than one.
+  - Pending examples (`xit`, `xspecify`, `xexample`) get a "pending" label.
+  - Contexts are grouped with a line along their examples.
+  - A public method without specs gets a red "no specs" label.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vdbijl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,185 @@
+# yard-rspec-coverage
+
+A YARD plugin that embeds RSpec examples alongside method documentation in the generated YARD
+documentation.
+
+## Overview
+
+This plugin allows you to see RSpec test examples directly in your YARD-generated documentation.
+When you document a method and have corresponding RSpec tests, those tests will automatically appear
+in a "RSpec Examples" section in the method's documentation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yard-rspec-coverage'
+```
+
+Or install it yourself:
+
+```bash
+gem install yard-rspec-coverage
+```
+
+## Usage
+
+### Basic Usage
+
+1. Write your Ruby code with YARD documentation comments
+2. Write RSpec tests using `describe` and `it` blocks
+3. Generate documentation with the plugin loaded:
+
+```bash
+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.
+
+### Rake tasks
+
+Declare the gem with `require: false` in your Gemfile, so you choose which YARD runs use the
+plugin; `Bundler.require` would load it into every YARD run in the process. Then require the tasks
+from your project's `Rakefile`:
+
+```ruby
+require 'yard_rspec/rake_tasks'
+
+YardRspec::Config.minimum_rspec_coverage = 80.0 # default: 100.0
+YardRspec::Config.files = ['{lib,spec}/**/*.rb'] # default
+```
+
+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.
+
+The plugin never logs YARD warnings, so it is safe in YARD runs with `--fail-on-warning`.
+
+Or use the provided build script:
+
+```bash
+./build.sh
+```
+
+### Example
+
+Given this code:
+
+```ruby
+class String
+  # Converts a string to pig latin
+  # 
+  # @return [String] the pig latin version of the string
+  def pig_latin
+    self[1..-1] + self[0] + "ay"
+  end
+end
+
+describe String, '#pig_latin' do
+  it "converts 'hello' to pig latin" do
+    "hello".pig_latin.should == "ellohay"
+  end
+
+  it "works with single character strings" do
+    "a".pig_latin.should == "aay"
+  end
+end
+```
+
+The generated documentation for `String#pig_latin` will include an "RSpec Examples" section showing both test cases.
+
+## How It Works
+
+The plugin consists of four main components:
+
+1. **Handler** (`lib/yard_rspec/handler.rb`): Parses RSpec `describe` blocks and extracts `it` examples
+2. **Template** (`templates/default/method_details/html/rspec_specs.erb`): Displays the examples in the documentation
+3. **Setup** (`templates/default/method_details/html/setup.rb`): Integrates the template into YARD's rendering pipeline
+4. **Assets** (`templates/default/fulldoc/html/`): A stylesheet and a script for the "expand all" link
+
+Each example shows its description and its syntax-highlighted code. Pending
+examples are labelled "pending", and a public method without specs gets a red "no specs" label.
+
+## RSpec Format Support
+
+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
+- `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.
+- nested `context "..."` and `describe "..."` blocks, shown as groups of examples
+
+### Not supported
+
+These RSpec constructs are not recognized. Examples written with them do not appear in the
+documentation and do not count towards RSpec coverage.
+
+- Examples that are not written as a command without parentheses followed by a block: `it('x') {}`
+  the one-liner `it {is_expected.to be_ok}` and `it do ... end` without a description.
+- Focused examples: `fit`, `fspecify` and `fexample`. A focused example makes RSpec skip the rest
+  of the suite, so it should not be committed; the plugin does not document it.
+- The `pending` and `skip` keywords.
+- Capybara's `scenario` (and `feature` as a group), and the `its` method of rspec-its.
+- Shared examples: `it_behaves_like`, `it_should_behave_like`, `include_examples` and
+  `include_context` are ignored, so the examples of a `shared_examples` group are not attributed to
+  the methods that use it. The examples inside a `shared_examples` block are attributed to the
+  enclosing method, as if they were written directly in the describe block.
+- Focused and excluded groups: `fdescribe`, `xdescribe`, `fcontext`, `xcontext` and `example_group`
+  are not recognized as groups. Their examples are still collected, but without the group, so the
+  group's description is lost. A `describe '#method'` written with one of these keywords is not
+  linked to the method.
+
+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`.
+
+## Development
+
+To test the plugin with the example code:
+
+```bash
+bundle install
+./build.sh
+```
+
+Then open `doc/index.html` in your browser to see the generated documentation.
+
+Run all checks (RuboCop, a dependency vulnerability audit, the specs with SimpleCov, YARD
+documentation coverage and RSpec coverage) with:
+
+```bash
+bundle exec rake
+```
+
+### Releasing
+
+Update the version in `yard-rspec-coverage.gemspec` and `CHANGELOG.md`, then push a matching tag:
+
+```bash
+git tag v0.1.3
+git push origin v0.1.3
+```
+
+The release workflow runs all checks and publishes the gem to rubygems.org with
+[Trusted Publishing](https://guides.rubygems.org/trusted-publishing/), so no API key is stored.
+
+## License
+
+MIT License
+
+## Credits
+
+Inspired by the [yard-spec-plugin](https://github.com/lsegal/yard-spec-plugin) by Loren Segal.

data/lib/tasks/yard_rspec.rake

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# 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
+
+namespace :yard do
+  desc 'Generate YARD documentation with the yard-rspec-coverage plugin'
+  task :doc do
+    # YARD ignores --plugin in-process.
+    require_relative '../yard-rspec-coverage'
+    YARD::CLI::Yardoc.run(*YardRspec::Config.files)
+  end
+
+  desc 'Verify RSpec coverage of public methods (without attributes and aliases)'
+  task :rspec_coverage do
+    require_relative '../yard-rspec-coverage'
+    YARD::Registry.clear
+    yardoc = 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)
+    minimum = YardRspec::Config.minimum_rspec_coverage
+
+    if coverage < minimum
+      warn format("\nRSpec coverage too low: %<coverage>.2f%% (minimum is %<minimum>.2f%%)",
+                  coverage:, minimum:)
+      exit 1
+    end
+  end
+end

data/lib/yard-rspec-coverage.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'yard'
+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/handler'
+require_relative 'yard_rspec/stats'
+
+YARD::Templates::Engine.register_template_path File.expand_path('../templates', __dir__)

data/lib/yard_rspec/config.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# The yard-rspec-coverage plugin.
+module YardRspec
+  # Set in a project's Rakefile, e.g. `YardRspec::Config.minimum_rspec_coverage = 80.0`.
+  module Config
+    class << self
+      attr_writer :minimum_rspec_coverage, :files
+
+      # @return [Float] A percentage.
+      def minimum_rspec_coverage
+        @minimum_rspec_coverage || DEFAULT_MINIMUM_RSPEC_COVERAGE
+      end
+
+      # @return [<String>] Glob patterns of the source and spec files.
+      def files
+        @files || DEFAULT_FILES
+      end
+    end
+
+    # @return [Float]
+    DEFAULT_MINIMUM_RSPEC_COVERAGE = 100.0
+
+    # @return [<String>]
+    DEFAULT_FILES = ['{lib,spec}/**/*.rb'].freeze
+  end
+end

data/lib/yard_rspec/coverage.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+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 [<YARD::CodeObjects::MethodObject>]
+    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]
+    def self.countable?(method)
+      method.visibility == :public &&
+        !method.file.to_s.match?(SPEC_FILE_PATTERN) &&
+        !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]
+    def self.covered?(method)
+      examples(method[:rspec_examples] || []).any? {|example| !example[:pending]}
+    end
+
+    # @param [<Hash>] nodes Example and context nodes, see `method[:rspec_examples]`.
+    # @return [<Hash>] The examples at any depth.
+    def self.examples(nodes)
+      nodes.flat_map {|node| node[:children] ? examples(node[:children]) : [node]}
+    end
+  end
+end

data/lib/yard_rspec/describe_problems.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module YardRspec
+  # Describe blocks naming a class or method that cannot be found. Not logged as YARD warnings,
+  # which would fail `yard --fail-on-warning`; `yard:rspec_coverage` lists them instead.
+  # Kept on the registry root, so YARD::Registry.clear also clears them.
+  module DescribeProblems
+    # @return [Symbol]
+    REGISTRY_KEY = :rspec_describe_problems
+
+    # @param [String] problem The location and description of the problem, for example
+    #   "spec/widget_spec.rb:4: could not find method '#wobble' on 'Widget'".
+    def self.add(problem)
+      root = YARD::Registry.root
+      root[REGISTRY_KEY] ||= []
+      root[REGISTRY_KEY] << problem
+    end
+
+    # @return [<String>] Sorted by location.
+    def self.all
+      (YARD::Registry.root[REGISTRY_KEY] || []).sort
+    end
+  end
+end

data/lib/yard_rspec/example_extractor.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+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
+
+    # @return [<String>] The keywords of examples that RSpec excludes from the run.
+    PENDING_KEYWORDS = %w[xit xspecify xexample].freeze
+
+    # @param [YARD::Parser::Ruby::AstNode, nil] block_node The body of a describe block.
+    def initialize(block_node)
+      @block_node = block_node
+    end
+
+    # @return [<Hash>] The example and context nodes.
+    def extract
+      return [] if @block_node.nil?
+
+      examples = []
+      traverse(@block_node, examples)
+      examples
+    end
+
+    private
+
+    def traverse(node, nodes)
+      return if !ast_node?(node)
+
+      if example_call?(node)
+        nodes << build_example(node)
+      elsif context_call?(node)
+        add_context(node, nodes)
+      else
+        node.children.each {|child| traverse(child, nodes)}
+      end
+    end
+
+    # A context without examples is left out.
+    def add_context(node, nodes)
+      children = []
+      traverse(node.last&.last, children)
+      return if children.empty?
+
+      nodes << { description: extract_context_description(node), children: children }
+    end
+
+    # Includes the `x` variants.
+    # @return [Boolean]
+    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)
+    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)
+    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.
+    def build_example(node)
+      example = {
+        description: extract_description(node.children[1]) || 'example',
+        code: extract_code(node.children[2])
+      }
+      example[:pending] = true if PENDING_KEYWORDS.include?(node.children[0].source)
+      example
+    end
+
+    # @return [String, nil]
+    def extract_description(args_node)
+      return nil if !ast_node?(args_node)
+
+      find_string_literal(args_node)
+    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
+    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
+      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)
+
+      # The source starts at the first token; restore its indentation before dedenting.
+      dedent((' ' * column_of(body)) + body.source.strip)
+    end
+
+    # @return [Integer] 0 if unknown.
+    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)
+      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)
+      min_indent = lines.reject(&:empty?).map {|line| line[/^\s*/].length}.min || 0
+      lines.map {|line| line[min_indent..] || line}.join("\n").strip
+    end
+  end
+end

data/lib/yard_rspec/handler.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+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.
+  class DescribeHandler < YARD::Handlers::Ruby::Base
+    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.
+    def process
+      @describe_namespace = namespace
+      if globals.yard_rspec_deferred_describes
+        globals.yard_rspec_deferred_describes << -> {process_describe}
+      else
+        process_describe
+      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?
+
+      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
+    end
+
+    # @return [MethodDescription, nil] From the second describe parameter.
+    def extract_method_description
+      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
+    end
+
+    # @return [Boolean]
+    def loaded_constant?(obj_name)
+      Object.const_defined?(obj_name)
+    rescue NameError
+      false
+    end
+
+    # 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)
+      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(/['"]/, '')
+    end
+
+    # @return [String] 'file:line', by default the line of the statement.
+    def location_of(line = statement.line || '?')
+      "#{statement.file || '(unknown)'}:#{line}"
+    end
+  end
+end
+
+YARD::Parser::SourceParser.before_parse_list do |_files, global_state|
+  global_state.yard_rspec_deferred_describes = []
+  nil # Returning false would cancel the parse.
+end
+
+YARD::Parser::SourceParser.after_parse_list do |_files, global_state|
+  global_state.yard_rspec_deferred_describes.each(&:call)
+end

data/lib/yard_rspec/method_description.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+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+)/
+
+    # @return [String]
+    attr_reader :name
+
+    # @return [:instance, :class]
+    attr_reader :scope
+
+    # @param [String] text The describe string, without quotes.
+    # @return [MethodDescription, nil] Nil if the text names no method.
+    def self.parse(text)
+      match = text.match(PATTERN)
+      return nil if match.nil?
+
+      new(name: match[2], scope: match[1] == '#' ? :instance : :class,
+          imprecise: text.length > match[0].length)
+    end
+
+    # @param [String] name
+    # @param [:instance, :class] scope
+    # @param [Boolean] imprecise
+    def initialize(name:, scope:, imprecise:)
+      @name = name
+      @scope = scope
+      @imprecise = imprecise
+    end
+
+    # Whether text follows the method name, as in '#initialize via SomeFactory'. A missing method
+    # is then not reported.
+    # @return [Boolean]
+    def imprecise?
+      @imprecise
+    end
+
+    # @return [String] '#name' or '.name'.
+    def to_s
+      "#{@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.
+    def find_in(namespace)
+      find_with_scope(namespace, @scope) || find_with_scope(namespace, other_scope)
+    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}
+    end
+
+    def other_scope
+      @scope == :instance ? :class : :instance
+    end
+  end
+end

data/lib/yard_rspec/rake_tasks.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Defines the yard:doc and yard:rspec_coverage Rake tasks. Usage in a Rakefile:
+#
+#   require 'yard_rspec/rake_tasks'
+#   YardRspec::Config.minimum_rspec_coverage = 80.0
+require 'rake'
+
+load File.expand_path('../tasks/yard_rspec.rake', __dir__)

data/lib/yard_rspec/stats.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+YARD::CLI::Stats.class_eval do
+  # Prints the RSpec specs row. Leaves @total/@undocumented alone, so "% documented" is unaffected.
+  def stats_for_rspec
+    public_lib_methods = YardRspec::Coverage.countable_methods
+
+    total   = public_lib_methods.size
+    covered = public_lib_methods.count {|method| YardRspec::Coverage.covered?(method)}
+
+    log.puts "RSpec specs: #{rspec_specs_data(covered, total - covered)}"
+  end
+
+  private
+
+  # @return [String]
+  def rspec_specs_data(covered, uncovered)
+    if uncovered.positive?
+      format('%<covered>5d (%<uncovered>5d without specs)', covered:, uncovered:)
+    else
+      format('%<covered>5d', covered:)
+    end
+  end
+end

data/templates/default/fulldoc/html/css/rspec.css

@@ -0,0 +1,33 @@
+.rspec_examples ul.rspec {
+  list-style: none;
+  padding-left: 0;
+}
+.rspec_context > ul.rspec {
+  margin: 3px 0 6px 4px;
+  padding-left: 12px;
+  border-left: 2px solid #e1e1e8;
+}
+.rspec_examples summary {
+  cursor: pointer;
+}
+.rspec_context_name {
+  font-style: italic;
+  color: #555;
+}
+.rspec_toggle {
+  margin-left: 6px;
+  font-size: 11px;
+  font-weight: normal;
+}
+.rspec_label {
+  padding: 1px 4px;
+  font-size: 11px;
+  font-weight: normal;
+}
+.rspec_pending {
+  background: #d5d5d5;
+}
+.rspec_missing {
+  color: #fff;
+  background: #cc0000;
+}

data/templates/default/fulldoc/html/js/rspec.js

@@ -0,0 +1,11 @@
+// Opens or closes all examples of a method at once.
+document.addEventListener('click', function(event) {
+  const toggle = event.target.closest('.rspec_toggle');
+  if (!toggle) return;
+
+  event.preventDefault();
+  const all_details = toggle.closest('.rspec_examples').querySelectorAll('details');
+  const open = !Array.from(all_details).every(details => details.open);
+  all_details.forEach(details => { details.open = open; });
+  toggle.textContent = open ? 'collapse all' : 'expand all';
+});

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# @return [<String>]
+def stylesheets
+  super + %w[css/rspec.css]
+end
+
+# @return [<String>]
+def javascripts
+  super + %w[js/rspec.js]
+end

data/templates/default/method_details/html/rspec_specs.erb

@@ -0,0 +1,14 @@
+<% examples = object[:rspec_examples].to_a %>
+<% if examples.any? || YardRspec::Coverage.countable?(object) %>
+  <div class="tags rspec_examples">
+    <% if examples.any? %>
+      <% count = YardRspec::Coverage.examples(examples).size %>
+      <p class="tag_title">RSpec Examples (<%= count %>):<% if count > 1 %> <a href="#" class="rspec_toggle">expand all</a><% end %></p>
+      <ul class="rspec">
+        <%= rspec_nodes_html(examples) %>
+      </ul>
+    <% else %>
+      <p class="tag_title">RSpec Examples: <span class="rspec_label rspec_missing">no specs</span></p>
+    <% end %>
+  </div>
+<% end %>

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Shows the examples before the source.
+def init
+  super
+  sections.place(:rspec_specs).before(:source, true)
+end
+
+# @return [String]
+def rspec_specs
+  erb(:rspec_specs)
+end
+
+# @param [<Hash>] nodes Example and context nodes, see `method[:rspec_examples]`.
+# @return [String] HTML list items.
+def rspec_nodes_html(nodes)
+  nodes.map {|node| node[:children] ? rspec_group_html(node) : rspec_example_html(node)}.join
+end
+
+# @param [{description: String, code: String, pending: Boolean}] example
+# @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>" \
+    '</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>" \
+    "<ul class=\"rspec\">#{rspec_nodes_html(group[:children])}</ul></li>"
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: yard-rspec-coverage
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- vdbijl
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A YARD plugin that embeds RSpec examples alongside method documentation,
+  and reports public methods without specs
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/tasks/yard_rspec.rake
+- lib/yard-rspec-coverage.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/rake_tasks.rb
+- lib/yard_rspec/stats.rb
+- templates/default/fulldoc/html/css/rspec.css
+- templates/default/fulldoc/html/js/rspec.js
+- templates/default/layout/html/setup.rb
+- templates/default/method_details/html/rspec_specs.erb
+- templates/default/method_details/html/setup.rb
+homepage: https://github.com/vdbijl/yard-rspec-coverage
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/vdbijl/yard-rspec-coverage
+  changelog_uri: https://github.com/vdbijl/yard-rspec-coverage/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/vdbijl/yard-rspec-coverage/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key:
+specification_version: 4
+summary: YARD plugin to display RSpec examples in documentation and report RSpec coverage
+test_files: []