rubocop-rspec_parity 1.7.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70e06a85873dc993a895443df9bab8892de60d0cc75573ffdc6487245c09dcf
-  data.tar.gz: 7d8baed7d58b13d98fb7b7e14084c3c81dcb1905df3bacfc52772dcb65ba7dbd
+  metadata.gz: 2bda6248c84f44ce1e039baac11b9e6b3075c3feb13bb4e06a9e804ff26436a6
+  data.tar.gz: ebc0e696c427bd033637609d7f1ad4aaa66c603a9ca1ed82adb09d2857c99161
 SHA512:
-  metadata.gz: 66ae9ef49f40f4323af10a733c9c1eb6bbc7a49883b3f00619fda6610c22b035ca53aa9e6b259259df8c7a5cb49aded12d56e8b96082074036f4fd9dc960baf3
-  data.tar.gz: 18635158b5155856049fdbfd33aaeb732b013d729467f1aefd8751873f997411b78a4d1489fa692ef64b0030691a6141b8ab6c6ca28e95398ea5d87201d0b3e7
+  metadata.gz: 102aceedd06b6db82be97c0a45d95a57e22cb1b1ab7427875c6137f98dcfcc87b862cd2cc26dfc14d8f5604a24702166db12b6f94c1835f7e0395fd98082d556
+  data.tar.gz: ca83d65bb73322941c49160de66943b2e1c6c93f35db372ef8cb559e5ea2cf3bdf1d3cc31151e654c8d19b620ceb1f4ee2f6dbf5ef8a8213277bd243c7104111

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [2.0.0] - 2026-06-18
+
+Added: `SufficientContexts` now pinpoints which branch is untested — its message names one uncovered branch and the `# rspec_parity:covers <branch>` annotation to add, and the bundled `rspec-parity-cover` executable lists all of a method's gaps as paste-ready context stubs. Annotations are opt-in (new `CoversAnnotations` config key, default `true`).
+
 ## [1.7.0] - 2026-06-11
 
 Fixed: `SufficientContexts` no longer over-counts chains of guard clauses (`return`/`raise`/`next ... if/unless`). A sequence of guards shares a single "all guards pass" fall-through, so that happy path is counted once for the whole method instead of once per guard. Each `&&`/`||` inside a guard condition is still counted as a distinct way for the guard to fire (one scenario per operand).

data/README.md

@@ -230,6 +230,59 @@ end
 **Configuration options:**
 
 - `IgnoreMemoization` (default: `true`) - When enabled, common memoization patterns like `@var ||=` and `return @var if defined?(@var)` are not counted as branches. Set to `false` if you want to count these as branches.
+- `CoversAnnotations` (default: `true`) - Enables the `# rspec_parity:covers` annotations described below. Set to `false` to revert to the plain numeric message.
+
+#### Pinpointing the missing branch with `# rspec_parity:covers`
+
+Instead of a bare count, the violation names one uncovered branch and gives the exact context to add:
+
+```
+Missing coverage for `user.staff?` (line 4) — 2 of 3 branches untested.
+Add `context '...' do # rspec_parity:covers user.staff?` to mark it covered.
+```
+
+Tag a context with the branch it covers (trailing, or on its own line inside the block):
+
+```ruby
+context 'when staff' do # rspec_parity:covers user.staff?
+  it { is_expected.to eq('staff') }
+end
+```
+
+Re-run and the message advances to the next uncovered branch. Annotations are opt-in and only ever raise coverage — they never create a new violation, and each one covers exactly one branch. A mistyped label is reported with a did-you-mean suggestion.
+
+Long conditions can push the comment past `Layout/LineLength`; exempt these comments rather than editing the label:
+
+```yaml
+Layout/LineLength:
+  AllowedPatterns:
+    - 'rspec_parity:covers'
+```
+
+##### Listing every uncovered branch (`rspec-parity-cover`)
+
+To get all the gaps for a method at once as ready-to-paste stubs:
+
+```
+$ bundle exec rspec-parity-cover app/services/classifier.rb
+
+# classify — 2 uncovered branches:
+context '...' do
+  # rspec_parity:covers user.staff?
+
+  it '...' do
+  end
+end
+
+context '...' do
+  # rspec_parity:covers else of user.admin?
+
+  it '...' do
+  end
+end
+```
+
+It derives the spec path (or take a second argument), and accepts `app/foo.rb:42` to report only the method at that line. When a method has many untested branches, the cop's message points you straight at this command.
 
 ## Assumptions
 

data/config/default.yml

@@ -33,5 +33,6 @@ RSpecParity/SufficientContexts:
   Enabled: true
   IgnoreMemoization: true
   TraceSingleUsePrivateMethods: true
+  CoversAnnotations: true
   SkipMethodDescribeFor: []
   DescribeAliases: {}

data/docs/superpowers/specs/2026-06-15-covers-branch-annotations-design.md

@@ -0,0 +1,224 @@
+# Pinpoint missing branches with `# rspec_parity:covers` annotations
+
+## Problem
+
+`RSpecParity/SufficientContexts` reports a bare numeric gap: "method has 21
+branches but the spec covers only 20 scenarios." When the gap is 1 out of 21,
+there is no way to tell *which* branch is uncovered. Both sides of the
+comparison are pure counts — branches are tallied as integers from the AST, and
+scenarios are tallied as integers from spec text — so there is no axis along
+which a specific branch maps to a specific context.
+
+## Goal
+
+1. Make the offense name the branches it counted, so a human can reconcile the
+   gap by eye instead of guessing.
+2. Let authors *opt in* to precise per-branch tracking by tagging contexts with
+   a `# rspec_parity:covers <label>` magic comment. Annotations are purely additive —
+   they can only ever *help* (raise coverage / narrow the reported gap), never
+   create a new violation and never make a passing method fail.
+3. Report annotations that match no known branch (typos / renamed branches),
+   with a did-you-mean suggestion.
+
+## Configuration
+
+```yaml
+RSpecParity/SufficientContexts:
+  CoversAnnotations: true   # default
+```
+
+Set to `false` to restore the prior numeric-only message and skip all
+annotation handling.
+
+## Concepts
+
+### Branch descriptors
+
+`branch_tally` stops returning integer counters and instead collects a list of
+**branch descriptors**, one per counted branch:
+
+```
+Branch = Struct.new(:kind, :label, :line, :origin)
+#   kind   — :guard or :regular (preserves the guard fall-through logic)
+#   label  — the normalized condition/operator source (what you annotate with)
+#   line   — source line of the branch
+#   origin — nil for the method's own branches; the helper method name when the
+#            branch was inlined from a single-use private method
+```
+
+`BranchTally` becomes a thin wrapper over an array of `Branch`, still exposing
+`guard`, `regular`, `total`, and `+` so `branches_from` and
+`PrivateMethodCallGraph` keep working unchanged. A new `with_origin(name)`
+returns a copy with each not-yet-tagged descriptor's `origin` set — the call
+graph tags descriptors as it inlines each helper.
+
+### Labels
+
+A label is the branch's source, whitespace-collapsed (`source.gsub(/\s+/, " ")
+.strip`), case-sensitive. No truncation — the displayed label is exactly the
+string you type into the annotation, so it is always copy-pasteable.
+
+Per branch kind:
+
+| AST | descriptors |
+|-----|-------------|
+| `if`/`elsif`/`else` (non-guard) | one per condition (`if`, each `elsif`) + `else of <if condition>` |
+| guard `if`/`unless` | one, label = guard condition source, kind `:guard` |
+| `case`/`when` | one per `when` + `else of case <subject>` (only if present) |
+| `&&` / `\|\|` | one, label = operator source; carries `detail` `<rhs> decides` |
+| `\|\|=` / `&&=` | two, label = `<src>`; carry `detail` `already set` / `assigns` |
+| `&` / `\|` send | one, label = node source |
+
+**Every branch ends up with a unique token, so one annotation covers exactly one
+branch.** `#disambiguate` enforces this in two passes: branches whose plain token
+still collides get their `detail` applied (`a && b` → `a && b (b decides)`,
+`||=` → `… (assigns)`/`… (already set)`); anything still identical (e.g. two
+`if`s with the same condition) gets a positional `(1)`, `(2)`. Non-colliding
+labels (including standalone `&&`/`||` expressions) keep their plain source, so
+they stay naturally typeable.
+
+When a branch was inlined from a private helper, its annotation token is
+prefixed with the origin: `admin_role?: role == 'admin'`. The prefix is
+**optional when unambiguous** — typing just `role == 'admin'` matches when
+exactly one branch has that condition; the prefix is only required to
+disambiguate identical conditions in different helpers.
+
+### Annotations
+
+A trailing magic comment on a `context`/`describe`/`it`/`example`/`specify`
+line:
+
+```ruby
+context 'when admin by role' do # rspec_parity:covers admin_role?: role == 'admin'
+  it 'returns true'
+end
+```
+
+- An annotated **context** collapses its inner examples: the whole block counts
+  as the branch(es) it declares, *not* as N example scenarios. This overrides
+  the "multiple `it`s = multiple scenarios" heuristic for that block — the
+  author has explicitly said "this block is one branch."
+- An annotated **example** counts as its own branch.
+- One annotation may list several labels separated by `;` (semicolon — commas
+  appear inside conditions). Or repeat the comment.
+- The annotation may also be a **standalone comment line inside the context**
+  (handy when a trailing comment would overflow the line length); it is
+  attributed to the enclosing context. Place it before the context's examples.
+
+## Coverage rule
+
+```
+covered = distinct_matched_annotations
+        + numeric_scenarios(from the un-annotated parts only)
+
+offense fires when  covered < branches      # same trigger as before
+```
+
+Annotations only raise `covered`. With zero annotations this reduces exactly to
+today's `scenario_count` over the whole block.
+
+## Messages (single line — RuboCop offense constraint)
+
+Rather than listing every branch (unreadable for branchy methods), the message
+names **one** still-uncovered branch and gives the exact context to add. Each
+re-run advances to the next gap as branches get annotated.
+
+**With annotations on** (the default):
+
+```
+Missing coverage for `user.staff?` (line 4) — 2 of 3 branches untested.
+Add `context '...' do # rspec_parity:covers user.staff?` to mark it covered.
+```
+
+The showcased branch is the first uncovered one, preferring a real condition
+over `else`/guard fall-through so the example reads clearly. A branch traced
+from a helper shows its origin in the location (`helper line N`) and token
+(`helper: condition`). The existing `(including branches from: …)` suffix still
+appends when branches were inlined.
+
+**With annotations off** — just the count, no annotation guidance:
+
+```
+Method `classify` is missing coverage for 9 of 10 branches.
+```
+
+**Orphan annotations** (appended when the method offends):
+
+```
+… `rspec_parity:covers` annotation `params[:admni]` matches no branch — did you
+mean `params[:admin]`?
+```
+
+Nearest match via `DidYouMean::SpellChecker`; omit the "did you mean" clause
+when nothing is close. An orphan annotation alone never triggers an offense
+(opt-in): orphans are only reported when the method is already offending.
+
+## Architecture
+
+### `SufficientContexts`
+
+- `initialize`: `@covers_annotations = cop_config.fetch("CoversAnnotations", true)`.
+- `BranchTally` rewritten over `Branch` descriptors (`guard`/`regular`/`total`/
+  `+`/`with_origin`/`branches`).
+- `branch_tally`, `count_if_branches`→`if_branch_descriptors`,
+  `count_case_branches`→`case_branch_descriptors`, `send_node_branch_count`,
+  `or_asgn`/`and_asgn` handling all push descriptors.
+- `branches_from` unchanged (operates on `guard`/`regular`/`total`).
+- Spec parsing (`parse_spec_content`, `count_top_level_contexts`): collect
+  trailing `# rspec_parity:covers` labels, suppress example counting inside annotated
+  contexts, return labels + un-annotated numeric scenario count.
+- `check_method`: compute `matched`/`unannotated`/`orphans` by intersecting
+  annotation labels with the descriptor inventory; `covered = matched.size +
+  unannotated_scenarios`; build the enriched message.
+- New helpers: `match_annotations`, `nearest_label` (DidYouMean), message
+  builders.
+
+### `PrivateMethodCallGraph`
+
+`visit_callee` tags the inlined tally: `tally = tally.with_origin(name) if
+tally.respond_to?(:with_origin)`. No other change; the `Result`/traverse logic
+is untouched.
+
+### `config/default.yml`
+
+Add `CoversAnnotations: true` under `RSpecParity/SufficientContexts`.
+
+## Edge cases
+
+- **`CoversAnnotations: false`** — message reverts to today's exact
+  string; annotation comments are ignored entirely.
+- **No spec annotations** — `matched` is empty, `unannotated_scenarios` equals
+  today's `scenario_count`; coverage and trigger are identical to today. Only
+  the message gains the inventory suffix.
+- **Duplicate identical labels** (two branches, same source, same origin) — a
+  single annotation covers both; acceptable for "good enough" precision and
+  logged via the inventory line.
+- **Annotated context with nested contexts** — the whole subtree collapses to
+  the declared label(s).
+- **Multi-line / very long condition** — collapsed to one line; long but exact
+  and matchable.
+
+## Testing
+
+Extend `spec/rubocop/cop/rspec_parity/sufficient_contexts_spec.rb`:
+
+- inventory appears in the message when no annotations exist
+- a matching annotation removes a branch from the uncovered list / satisfies the
+  count
+- annotated context with several `it`s counts as one branch (collapse)
+- optional origin prefix: bare condition matches when unambiguous
+- orphan annotation reported with did-you-mean
+- `CoversAnnotations: false` reproduces the legacy message
+- interaction with `TraceSingleUsePrivateMethods` (origin-prefixed labels)
+
+Existing message assertions are updated to the new output (captured from an
+actual run).
+
+## Open questions resolved
+
+- **Default** — `true` (opt-out), consistent with `TraceSingleUsePrivateMethods`.
+  The richer message is strictly more informative; annotations are additive.
+- **Message is single-line** — RuboCop offense messages are single-line; the
+  inventory is joined with `; ` rather than rendered as a list.
+- **Annotations never trigger** — opt-in means an annotation can only narrow or
+  satisfy; it never creates an offense.

data/exe/rspec-parity-cover

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rubocop/rspec_parity/coverage_reporter"
+
+target = ARGV[0]
+
+if target.nil? || %w[-h --help].include?(target)
+  warn "Usage: rspec-parity-cover SOURCE_FILE[:LINE] [SPEC_FILE]"
+  warn ""
+  warn "Lists a method's uncovered branches as paste-ready"
+  warn "`context '...' do # rspec_parity:covers <branch>` stubs."
+  warn "Append :LINE (e.g. app/foo.rb:20) to report only the method at that line."
+  warn "The spec file is derived from SOURCE_FILE (app/ -> spec/, *.rb -> *_spec.rb)"
+  warn "unless SPEC_FILE is given."
+  exit(target.nil? ? 1 : 0)
+end
+
+source, line = target.match(/\A(?<path>.+):(?<line>\d+)\z/)&.named_captures&.values_at("path", "line") || [target, nil]
+
+abort "rspec-parity-cover: no such file: #{source}" unless File.file?(source)
+
+reporter = RuboCop::RSpecParity::CoverageReporter.new(source, spec_path: ARGV[1], line: line&.to_i)
+output = reporter.render
+puts output.empty? ? "# No uncovered branches found for #{target}." : output

data/lib/rubocop/cop/rspec_parity/private_method_call_graph.rb

@@ -65,10 +65,18 @@ module RuboCop
           tally = branch_counter.call(@methods[key][:node])
           return unless tally.total.positive?
 
-          state[:tally] = state[:tally] ? state[:tally] + tally : tally
+          state[:tally] = combine_tally(state[:tally], tally, @methods[key][:name])
           state[:traced] << key
         end
 
+        # Attribute the inlined branches to the helper they came from so the cop
+        # can show "label (helper, line N)" and accept origin-prefixed
+        # `# rspec_parity:covers` annotations. Duck-typed: a plain count would skip.
+        def combine_tally(existing, tally, name)
+          tally = tally.with_origin(name) if tally.respond_to?(:with_origin)
+          existing ? existing + tally : tally
+        end
+
         def inlinable?(key, visited)
           return false if visited.include?(key)
           return false unless @methods.key?(key)

data/lib/rubocop/cop/rspec_parity/sufficient_contexts.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
+
 require_relative "spec_file_finder"
 require_relative "private_method_call_graph"
 
@@ -42,12 +44,31 @@ module RuboCop
         include DepartmentConfig
         include SpecFileFinder
 
-        MSG = "Method `%<method_name>s` has %<branches>d %<branch_word>s but the spec covers only " \
-              "%<contexts>d %<scenario_word>s. Add %<missing>d more %<missing_word>s " \
-              "(one `context` or `it` per branch; compound conditions like `a && b` need a scenario per operand)."
+        # Used when CoversAnnotations is on: names one still-uncovered branch and
+        # gives the exact context to add. Re-running advances to the next gap as
+        # branches get annotated, so the message stays short instead of listing all.
+        COVERAGE_MSG = "Missing coverage for `%<token>s` (%<location>s) — " \
+                       "%<missing>d of %<branches>d %<branch_word>s untested. " \
+                       "Add `context '...' do # rspec_parity:covers %<token>s` to mark it covered."
+
+        # Used when many branches are missing: too many to walk one at a time, so
+        # point at the CLI that lists them all instead.
+        MANY_MSG = "%<missing>d of %<branches>d %<branch_word>s untested. " \
+                   "Run `bundle exec rspec-parity-cover %<location>s` for the full list."
+
+        # Above this many missing branches, switch from the per-branch message to
+        # the CLI pointer.
+        MANY_UNCOVERED_BRANCHES = 3
+
+        # Used when CoversAnnotations is off (no annotation guidance to give).
+        COUNT_MSG = "Method `%<method_name>s` is missing coverage for %<missing>d of %<branches>d %<branch_word>s."
 
         TRACED_SUFFIX = " (including branches from: %<traced>s)"
 
+        ORPHAN_SUFFIX = " `rspec_parity:covers` annotation `%<label>s` matches no branch%<hint>s"
+
+        ANNOTATION_PATTERN = /#\s*rspec_parity:covers\s+(.+?)\s*\z/
+
         APP_DIR_PATTERN = %r{/app/}
 
         EXCLUDED_METHODS = %w[initialize].freeze
@@ -61,20 +82,180 @@ module RuboCop
         ].freeze
 
         # Tallies extracted from a spec's text for a single method describe block.
-        ParsedSpec = Struct.new(:context_count, :example_count, :has_examples, :has_direct_examples)
-
-        # Branch tally split into guard-clause "fire" branches vs. every other
-        # branch. A sequence of guard clauses (`return/raise/next ... if/unless`)
-        # shares a single "all guards pass" fall-through, so that happy path is
-        # counted once for the whole method (see #branches_from) rather than once
-        # per guard — which previously inflated guard-heavy methods.
-        BranchTally = Struct.new(:guard, :regular) do
+        # `annotations` holds raw `# rspec_parity:covers` label strings found in the
+        # block (empty unless CoversAnnotations is on).
+        ParsedSpec = Struct.new(:context_count, :example_count, :has_examples, :has_direct_examples, :annotations)
+
+        # A spec's contribution to coverage: scenarios counted from un-annotated
+        # contexts/examples, plus the raw annotation labels gathered from it.
+        SpecCoverage = Struct.new(:scenarios, :annotations)
+
+        # Line-by-line scanner state shared by both spec-counting paths. Tracks
+        # the scenario tallies (mirroring the prior behaviour) and, when
+        # CoversAnnotations is on, gathers `# rspec_parity:covers` labels and
+        # collapses an annotated context's body so its examples count as the one
+        # annotated branch rather than as separate scenarios.
+        class ScanState
+          def initialize(annotations_enabled)
+            @annotations_enabled = annotations_enabled
+            @context_count = 0
+            @example_count = 0
+            @has_examples = false
+            @has_direct_examples = false
+            @child_indent = nil
+            @annotations = []
+            @annotated_indent = nil
+            @last_context_indent = nil
+            @last_context_counted = false
+          end
+
+          def reset_child_indent
+            @child_indent = nil
+          end
+
+          def inside_annotated_context?
+            !@annotated_indent.nil?
+          end
+
+          def exit_annotated_context(indent)
+            @annotated_indent = nil if @annotated_indent && indent <= @annotated_indent
+          end
+
+          def count_context(line, indent)
+            @last_context_indent = indent
+            labels = annotation_labels(line)
+            return annotate_context_line(indent, labels) if labels.any?
+
+            @child_indent ||= indent
+            @context_count += 1
+            @last_context_counted = true
+          end
+
+          # A comment-only annotation line, typically placed just inside a context
+          # block when a trailing comment would overflow the line length. It is
+          # attributed to the enclosing context, which then collapses like a
+          # context annotated on its opening line. Returns the labels (truthy)
+          # when it consumes the line, else nil. Place it before the context's
+          # examples; an annotation after an example only collapses what follows.
+          def collect_standalone_annotation(line)
+            return unless @annotations_enabled
+            return unless line.lstrip.start_with?("#")
+
+            labels = annotation_labels(line)
+            return if labels.empty?
+
+            @annotations.concat(labels)
+            annotate_enclosing_context
+            labels
+          end
+
+          # Coarse path for method-named context lines (e.g. `context '.call'`):
+          # count the block and gather any annotation, but don't collapse — this
+          # path doesn't track the block's interior.
+          def count_named_context(line)
+            @context_count += 1
+            @annotations.concat(annotation_labels(line))
+          end
+
+          def count_example(line, indent)
+            labels = annotation_labels(line)
+            if labels.any?
+              @annotations.concat(labels)
+            else
+              @has_examples = true
+              @example_count += 1
+              @child_indent ||= indent
+              @has_direct_examples = true if indent == @child_indent
+            end
+          end
+
+          def to_parsed_spec
+            ParsedSpec.new(@context_count, @example_count, @has_examples, @has_direct_examples, @annotations)
+          end
+
+          private
+
+          # Annotation found on a context's own opening line: record the labels
+          # and collapse the block from this indent. Nothing was counted yet.
+          def annotate_context_line(indent, labels)
+            @annotations.concat(labels)
+            @annotated_indent = indent
+            @last_context_counted = false
+          end
+
+          # Mark the most-recently-opened context as annotated: undo its generic
+          # scenario count (it now counts as its labels) and collapse the rest of
+          # its body. No-op if that context is already annotated.
+          def annotate_enclosing_context
+            return if @annotated_indent && @annotated_indent == @last_context_indent
+
+            if @last_context_counted
+              @context_count -= 1
+              @last_context_counted = false
+            end
+            @annotated_indent = @last_context_indent
+          end
+
+          def annotation_labels(line)
+            return [] unless @annotations_enabled
+
+            match = line.match(ANNOTATION_PATTERN)
+            return [] unless match
+
+            match[1].split(";").map(&:strip).reject(&:empty?)
+          end
+        end
+
+        # A single counted branch. `kind` is :guard or :regular (preserving the
+        # guard fall-through accounting in #branches_from). `label` is the
+        # normalized condition/operator source used both for display and for
+        # matching `# rspec_parity:covers` annotations. `origin` is nil for the
+        # method's own branches, or the helper method name when inlined from a
+        # single-use private method. `detail` is an optional semantic qualifier
+        # (e.g. "b decides", "assigns") applied only when the plain label collides
+        # with another branch — see #disambiguate.
+        Branch = Struct.new(:kind, :label, :line, :origin, :detail) do
+          # The string an author types after `# rspec_parity:covers` to claim this
+          # branch. The origin prefix disambiguates identical conditions in
+          # different helpers; it is optional when the condition is unique.
+          def annotation_token
+            origin ? "#{origin}: #{label}" : label
+          end
+        end
+
+        # Collection of Branch descriptors. Exposes the guard/regular/total/+
+        # interface the rest of the cop (and PrivateMethodCallGraph) relies on —
+        # a sequence of guard clauses (`return/raise/next ... if/unless`) shares
+        # a single "all guards pass" fall-through counted once per method (see
+        # #branches_from) rather than once per guard. `with_origin` tags inlined
+        # branches as the call graph descends into single-use helpers.
+        class BranchTally
+          attr_reader :branches
+
+          def initialize(branches = [])
+            @branches = branches
+          end
+
           def +(other)
-            BranchTally.new(guard + other.guard, regular + other.regular)
+            BranchTally.new(branches + other.branches)
+          end
+
+          def guard
+            branches.count { |branch| branch.kind == :guard }
+          end
+
+          def regular
+            branches.count { |branch| branch.kind == :regular }
           end
 
           def total
-            guard + regular
+            branches.size
+          end
+
+          def with_origin(name)
+            BranchTally.new(branches.map do |branch|
+              branch.origin ? branch : Branch.new(branch.kind, branch.label, branch.line, name, branch.detail)
+            end)
           end
         end
 
@@ -85,6 +266,7 @@ module RuboCop
           super
           @ignore_memoization = cop_config.fetch("IgnoreMemoization", true)
           @trace_single_use_private = cop_config.fetch("TraceSingleUsePrivateMethods", true)
+          @covers_annotations = cop_config.fetch("CoversAnnotations", true)
           @call_graphs = {}.compare_by_identity
         end
 
@@ -96,6 +278,50 @@ module RuboCop
           check_method(node)
         end
 
+        # ---- Tooling API (used by CoverageReporter / the rspec-parity-cover CLI) ----
+
+        # Every counted branch for a method node, including those traced from
+        # single-use private helpers. Empty when the method has fewer than two
+        # branches or is excluded. Also aliased as +all_branches+ for callers that
+        # want the full set regardless of spec coverage.
+        def branch_inventory_for(method_node)
+          return [] if excluded_method?(method_name(method_node))
+
+          tally = branch_tally(method_node)
+          if @trace_single_use_private
+            extra = inlined_branches(method_node)
+            tally += extra.branch_tally if extra.branch_tally
+          end
+          return [] if branches_from(tally) < 2
+
+          branch_inventory(tally, method_node)
+        end
+        alias all_branches branch_inventory_for
+
+        # What's left to cover for a method, given the spec text:
+        #   uncovered          — branches with no covering annotation
+        #   annotated          — branches an annotation already claims (known-covered)
+        #   unannotated_specs  — count of plain (un-annotated) examples/contexts whose
+        #                        branch we can't determine
+        # Nil when the method has no spec describe block or is already fully covered.
+        CoverageGap = Struct.new(:uncovered, :annotated, :unannotated_specs, keyword_init: true)
+
+        def coverage_gap(method_node, spec_content)
+          inventory = branch_inventory_for(method_node)
+          return nil if inventory.empty?
+
+          build_gap(inventory, count_contexts_for_method(spec_content.to_s, method_name(method_node)))
+        end
+
+        def build_gap(inventory, coverage)
+          matched, = match_annotations(inventory, coverage.annotations)
+          covered = coverage.scenarios + matched.size
+          return nil if covered.zero? || covered >= inventory.size
+
+          CoverageGap.new(uncovered: inventory.reject { |branch| matched.include?(branch) },
+                          annotated: matched, unannotated_specs: coverage.scenarios)
+        end
+
         private
 
         def check_method(node) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -120,35 +346,179 @@ module RuboCop
 
           dual_access = node.def_type? && module_with_dual_access?(node)
 
-          # Aggregate contexts from all valid spec files
-          contexts = if matches_skip_path? && count_public_methods(node) == 1
-                       # For single-method classes, count top-level contexts instead
-                       spec_files.sum { |spec_file| count_top_level_contexts(File.read(spec_file), class_name) }
-                     else
-                       # Normal path: look for method describes
-                       spec_files.sum do |spec_file|
-                         count_method_contexts(File.read(spec_file), method_name(node), dual_access: dual_access)
-                       end
-                     end
+          coverage = gather_coverage(node, class_name, spec_files, dual_access)
+          inventory = branch_inventory(tally, node)
+          matched, orphans = match_annotations(inventory, coverage.annotations)
+          # Annotations only ever raise coverage: matched branches + un-annotated
+          # scenarios + orphan claims (counted so a typo'd annotation never lowers
+          # coverage below the un-annotated baseline).
+          covered = coverage.scenarios + matched.size + orphans.size
+
+          return if covered.zero? # Method has no specs at all - PublicMethodHasSpec handles this
+          return if covered >= branches
+
+          missing = branches - covered
+          add_offense(node, message: build_message(
+            node: node, branches: branches, missing: missing,
+            traced_methods: traced_methods, inventory: inventory, matched: matched, orphans: orphans
+          ))
+        end
+
+        def gather_coverage(node, class_name, spec_files, dual_access)
+          if matches_skip_path? && count_public_methods(node) == 1
+            # For single-method classes, count top-level contexts instead
+            aggregate_coverage(spec_files) { |file| count_top_level_contexts(File.read(file), class_name) }
+          else
+            # Normal path: look for method describes
+            aggregate_coverage(spec_files) do |file|
+              count_method_contexts(File.read(file), method_name(node), dual_access: dual_access)
+            end
+          end
+        end
+
+        def aggregate_coverage(spec_files)
+          spec_files.reduce(SpecCoverage.new(0, [])) do |acc, file|
+            merge_coverage(acc, yield(file))
+          end
+        end
+
+        def merge_coverage(first, second)
+          SpecCoverage.new(first.scenarios + second.scenarios, first.annotations + second.annotations)
+        end
+
+        # The branches counted, sorted for stable output. Adds the synthetic
+        # "all guards pass" fall-through so the inventory size matches the count,
+        # then makes every token unique so one annotation covers exactly one branch.
+        def branch_inventory(tally, node)
+          inventory = tally.branches.dup
+          if tally.guard.positive? && tally.regular.zero?
+            inventory << Branch.new(:guard, "all guards pass", node.first_line, nil)
+          end
+          disambiguate(inventory.sort_by { |branch| [branch.line, branch.label] })
+        end
+
+        # Makes every token unique so one annotation covers exactly one branch.
+        # First qualifies colliding branches that carry a semantic `detail` (e.g.
+        # the operator vs. the whole condition, or `||=`'s two cases); then appends
+        # a positional `(N)` to anything still identical (e.g. two `if`s with the
+        # same condition). Plain, non-colliding labels are left untouched.
+        def disambiguate(inventory)
+          inventory = requalify(inventory) { |branch| branch.detail && "#{branch.label} (#{branch.detail})" }
+          counter = Hash.new(0)
+          requalify(inventory) do |branch|
+            counter[branch.annotation_token] += 1
+            "#{branch.label} (#{counter[branch.annotation_token]})"
+          end
+        end
+
+        # Rewrites the label of each branch whose token still collides, using the
+        # block's result (skips the rewrite when the block returns nil).
+        def requalify(inventory)
+          totals = inventory.group_by(&:annotation_token).transform_values(&:size)
+          inventory.map do |branch|
+            next branch if totals[branch.annotation_token] == 1
+
+            new_label = yield(branch)
+            new_label ? Branch.new(branch.kind, new_label, branch.line, branch.origin, branch.detail) : branch
+          end
+        end
+
+        # Splits the spec's raw annotation labels into the inventory branches they
+        # cover and orphans that match nothing. A bare condition matches a traced
+        # branch when its label is unambiguous; otherwise the `origin:` prefix is
+        # needed. One annotation covers *every* branch sharing that token — a
+        # compound condition like `a && b` is counted as several MC/DC branches
+        # but reads as a single thing to annotate.
+        def match_annotations(inventory, raw_annotations)
+          tokens = inventory.map(&:annotation_token).uniq
+          label_tokens = inventory.group_by(&:label).transform_values do |branches|
+            branches.map(&:annotation_token).uniq
+          end
+          matched_tokens, orphans = partition_annotations(raw_annotations, tokens, label_tokens)
+          [inventory.select { |branch| matched_tokens.include?(branch.annotation_token) }, orphans]
+        end
 
-          return if contexts.zero? # Method has no specs at all - PublicMethodHasSpec handles this
-          return if contexts >= branches
+        def partition_annotations(raw_annotations, tokens, label_tokens)
+          matched_tokens = Set.new
+          orphans = []
+          raw_annotations.each do |raw|
+            label = normalize_label(raw)
+            token = resolve_annotation(label, tokens, label_tokens)
+            token ? matched_tokens << token : orphans << label
+          end
+          [matched_tokens, orphans]
+        end
+
+        # The inventory token an annotation label refers to: an exact token match,
+        # or a bare condition whose origin is unambiguous. Nil when it matches none.
+        def resolve_annotation(label, tokens, label_tokens)
+          return label if tokens.include?(label)
+          return label_tokens[label].first if label_tokens[label]&.one?
+
+          nil
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def build_message(node:, branches:, missing:, traced_methods:, inventory:, matched:, orphans:)
+          uncovered = @covers_annotations ? inventory.reject { |branch| matched.include?(branch) } : []
+          return count_message(node, branches, missing) + traced_suffix(traced_methods) if uncovered.empty?
+
+          if missing > MANY_UNCOVERED_BRANCHES
+            return many_message(node, branches, missing) + orphan_suffix(orphans, inventory)
+          end
+
+          coverage_message(preferred_example(uncovered), branches, missing) +
+            traced_suffix(traced_methods) + orphan_suffix(orphans, inventory)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def traced_suffix(traced_methods)
+          traced_methods.any? ? format(TRACED_SUFFIX, traced: traced_methods.join(", ")) : ""
+        end
+
+        def count_message(node, branches, missing)
+          format(COUNT_MSG, method_name: method_name(node), missing: missing,
+                            branches: branches, branch_word: pluralize("branch", branches))
+        end
+
+        def many_message(node, branches, missing)
+          format(MANY_MSG, missing: missing, branches: branches,
+                           branch_word: pluralize("branch", missing),
+                           location: "#{source_file_path}:#{node.first_line}")
+        end
+
+        def coverage_message(branch, branches, missing)
+          format(COVERAGE_MSG, token: branch.annotation_token, location: branch_location(branch),
+                               missing: missing, branches: branches, branch_word: pluralize("branch", branches))
+        end
 
-          missing = branches - contexts
-          add_offense(node, message: build_message(node, branches, contexts, missing, traced_methods))
+        # Prefer a branch with a real condition label over an `else`/guard
+        # fall-through so the showcased annotation reads clearly; fall back to the
+        # first.
+        def preferred_example(branches)
+          branches.find { |branch| !unhelpful_example?(branch.label) } || branches.first
         end
 
-        def build_message(node, branches, contexts, missing, traced_methods)
-          message = format(MSG,
-                           method_name: method_name(node),
-                           branches: branches,
-                           branch_word: pluralize("branch", branches),
-                           contexts: contexts,
-                           scenario_word: pluralize("scenario", contexts),
-                           missing: missing,
-                           missing_word: pluralize("scenario", missing))
-          message += format(TRACED_SUFFIX, traced: traced_methods.join(", ")) if traced_methods.any?
-          message
+        def unhelpful_example?(label)
+          label == "all guards pass" || label.start_with?("else")
+        end
+
+        def branch_location(branch)
+          branch.origin ? "#{branch.origin} line #{branch.line}" : "line #{branch.line}"
+        end
+
+        def orphan_suffix(orphans, inventory)
+          orphans.uniq.map do |label|
+            nearest = nearest_label(label, inventory)
+            hint = nearest ? " — did you mean `#{nearest}`?" : "."
+            format(ORPHAN_SUFFIX, label: label, hint: hint)
+          end.join
+        end
+
+        def nearest_label(label, inventory)
+          return nil if inventory.empty?
+
+          DidYouMean::SpellChecker.new(dictionary: inventory.map(&:annotation_token)).correct(label).first
         end
 
         def inlined_branches(node)
@@ -192,27 +562,49 @@ module RuboCop
           total
         end
 
-        def branch_tally(node) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
-          guard = 0
-          regular = 0
+        def branch_tally(node)
           elsif_nodes = collect_elsif_nodes(node)
           guard_operators = collect_guard_condition_operators(node)
 
+          branches = []
           node.each_descendant do |descendant|
             next if elsif_nodes.include?(descendant)
             next if should_skip_node?(descendant)
 
-            case descendant.type
-            when :if
-              guard_clause?(descendant) ? guard += 1 : regular += count_if_branches(descendant)
-            when :case then regular += count_case_branches(descendant)
-            when :and, :or then guard_operators.include?(descendant) ? guard += 1 : regular += 1
-            when :or_asgn, :and_asgn then regular += 2 # ||= and &&= create 2 branches (set vs already set)
-            when :send then regular += send_node_branch_count(descendant)
-            end
+            branches.concat(branches_for(descendant, guard_operators))
+          end
+
+          BranchTally.new(branches)
+        end
+
+        # Descriptors contributed by a single AST node. Counts match the prior
+        # integer tally exactly — each `+= N` became N descriptors — so existing
+        # branch totals are unchanged; the descriptors just carry labels/lines.
+        def branches_for(descendant, guard_operators)
+          case descendant.type
+          when :if then if_node_descriptors(descendant)
+          when :case then case_branch_descriptors(descendant)
+          when :and, :or then [boolean_operator_branch(descendant, guard_operators)]
+          when :or_asgn, :and_asgn then asgn_branch_descriptors(descendant)
+          when :send then send_branch_descriptors(descendant)
+          else []
           end
+        end
 
-          BranchTally.new(guard, regular)
+        def if_node_descriptors(node)
+          if guard_clause?(node)
+            [Branch.new(:guard, branch_label(node.condition), node.condition.first_line, nil)]
+          else
+            if_branch_descriptors(node)
+          end
+        end
+
+        # An `&&`/`||` operator's own branch is the MC/DC scenario where its right
+        # operand is decisive. Kept as the plain expression unless it collides with
+        # the whole-condition branch, in which case `detail` qualifies it.
+        def boolean_operator_branch(node, guard_operators)
+          kind = guard_operators.include?(node) ? :guard : :regular
+          Branch.new(kind, branch_label(node), node.first_line, nil, "#{branch_label(node.rhs)} decides")
         end
 
         # A guard clause is a one-armed `if`/`unless` whose single body exits the
@@ -265,48 +657,87 @@ module RuboCop
           @ignore_memoization && memoization_pattern?(node)
         end
 
-        def send_node_branch_count(node)
-          node.method?(:&) || node.method?(:|) ? 1 : 0
+        def send_branch_descriptors(node)
+          return [] unless node.method?(:&) || node.method?(:|)
+
+          [Branch.new(:regular, branch_label(node), node.first_line, nil)]
         end
 
-        def count_if_branches(node)
-          # if/else is 2 branches, each elsif adds 1
-          branches = 2
+        # if/else is 2 branches (the `if` condition + the trailing `else`
+        # fall-through), each `elsif` adds one more.
+        def if_branch_descriptors(node)
+          descriptors = [condition_branch(node)]
           current = node
           while current&.if_type? && current.else_branch&.if_type?
-            branches += 1
             current = current.else_branch
+            descriptors << condition_branch(current)
           end
-          branches
+          # Tie the else to its `if` condition so two separate if/else blocks get
+          # distinct, individually-annotatable labels instead of two bare "else"s.
+          descriptors << Branch.new(:regular, "else of #{branch_label(node.condition)}", node.first_line, nil)
+          descriptors
         end
 
-        def count_case_branches(node)
-          # Each when clause is a branch, plus default/else
-          when_count = node.when_branches.count
-          has_else = !node.else_branch.nil?
-          when_count + (has_else ? 1 : 0)
+        def condition_branch(if_node)
+          Branch.new(:regular, branch_label(if_node.condition), if_node.condition.first_line, nil)
+        end
+
+        # Each `when` clause is a branch, plus a default/else when present.
+        def case_branch_descriptors(node)
+          descriptors = node.when_branches.map do |when_node|
+            label = normalize_label("when #{when_node.conditions.map(&:source).join(", ")}")
+            Branch.new(:regular, label, when_node.first_line, nil)
+          end
+          descriptors << Branch.new(:regular, case_else_label(node), node.first_line, nil) if node.else_branch
+          descriptors
+        end
+
+        def case_else_label(node)
+          node.condition ? "else of case #{branch_label(node.condition)}" : "else of case"
+        end
+
+        # `||=` / `&&=` create 2 branches sharing the expression's source: the
+        # target was already set, or the right-hand side is assigned. `detail`
+        # tells them apart once #disambiguate sees the collision.
+        def asgn_branch_descriptors(node)
+          label = branch_label(node)
+          [
+            Branch.new(:regular, label, node.first_line, nil, "already set"),
+            Branch.new(:regular, label, node.first_line, nil, "assigns")
+          ]
+        end
+
+        def branch_label(node)
+          normalize_label(node.source)
+        end
+
+        def normalize_label(text)
+          text.gsub(/\s+/, " ").strip
         end
 
         def count_method_contexts(spec_content, mname, dual_access: false)
-          count = count_contexts_for_method(spec_content, mname)
-          prefixes = dual_access ? ["#", "."] : ["#"]
-          prefixes.each do |prefix|
-            describe_aliases_for("#{prefix}#{mname}").each do |alias_desc|
-              alias_name = alias_desc.sub(/^[#.]/, "")
-              count += count_contexts_for_method(spec_content, alias_name) if alias_name != mname
-            end
+          base = count_contexts_for_method(spec_content, mname)
+          alias_method_names(mname, dual_access).reduce(base) do |coverage, alias_name|
+            merge_coverage(coverage, count_contexts_for_method(spec_content, alias_name))
           end
-          count
+        end
+
+        def alias_method_names(mname, dual_access)
+          prefixes = dual_access ? ["#", "."] : ["#"]
+          prefixes.flat_map { |prefix| describe_aliases_for("#{prefix}#{mname}") }
+                  .map { |alias_desc| alias_desc.sub(/^[#.]/, "") }
+                  .uniq.reject { |alias_name| alias_name == mname }
         end
 
         def count_contexts_for_method(spec_content, method_name)
           method_pattern = Regexp.escape(method_name)
           result = parse_spec_content(spec_content, method_pattern)
 
-          scenario_count(
+          scenarios = scenario_count(
             result.context_count, result.example_count,
             has_examples: result.has_examples, has_direct_examples: result.has_direct_examples
           )
+          SpecCoverage.new(scenarios, result.annotations)
         end
 
         # A test scenario is the smaller unit between "a context block" and "an
@@ -331,12 +762,8 @@ module RuboCop
         # rubocop:disable Metrics/MethodLength
         def parse_spec_content(spec_content, method_pattern) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           in_method_block = false
-          context_count = 0
-          example_count = 0
-          has_examples = false
-          has_direct_examples = false
+          scan = ScanState.new(@covers_annotations)
           base_indent = 0
-          child_indent = nil
 
           spec_content.each_line do |line|
             current_indent = line[/^\s*/].length
@@ -344,28 +771,28 @@ module RuboCop
             if matches_method_describe?(line, method_pattern)
               in_method_block = true
               base_indent = current_indent
-              child_indent = nil
+              scan.reset_child_indent
               next
             end
 
             if in_method_block
+              scan.exit_annotated_context(current_indent)
+              next if scan.collect_standalone_annotation(line)
+              next if scan.inside_annotated_context? # collapsed: belongs to one annotated branch
+
               if exiting_block?(line, current_indent, base_indent)
                 in_method_block = false
               elsif nested_context?(line)
-                child_indent ||= current_indent
-                context_count += 1
+                scan.count_context(line, current_indent)
               elsif nested_example?(line)
-                has_examples = true
-                example_count += 1
-                child_indent ||= current_indent
-                has_direct_examples = true if current_indent == child_indent
+                scan.count_example(line, current_indent)
               end
             elsif matches_context_pattern?(line, method_pattern)
-              context_count += 1
+              scan.count_named_context(line)
             end
           end
 
-          ParsedSpec.new(context_count, example_count, has_examples, has_direct_examples)
+          scan.to_parsed_spec
         end
         # rubocop:enable Metrics/MethodLength
 
@@ -529,15 +956,11 @@ module RuboCop
 
           lines = spec_content.lines
           describe_line_index = lines.index { |line| line.match?(describe_pattern) }
-          return 0 unless describe_line_index
+          return SpecCoverage.new(0, []) unless describe_line_index
 
           # Count contexts/describes and examples at the top level (under class describe)
           base_indent = lines[describe_line_index].match(/^(\s*)/)[1].length
-          context_count = 0
-          example_count = 0
-          has_examples = false
-          has_direct_examples = false
-          child_indent = nil
+          scan = ScanState.new(@covers_annotations)
 
           lines[(describe_line_index + 1)..].each do |line|
             indent = line.match(/^(\s*)/)[1].length
@@ -545,18 +968,21 @@ module RuboCop
 
             next unless indent > base_indent
 
+            scan.exit_annotated_context(indent)
+            next if scan.collect_standalone_annotation(line)
+            next if scan.inside_annotated_context?
+
             if line.match?(/^\s*(?:context|describe)\s+/)
-              child_indent ||= indent
-              context_count += 1
+              scan.count_context(line, indent)
             elsif line.match?(/^\s*(?:it|example|specify)\s+/)
-              has_examples = true
-              example_count += 1
-              child_indent ||= indent
-              has_direct_examples = true if indent == child_indent
+              scan.count_example(line, indent)
             end
           end
 
-          scenario_count(context_count, example_count, has_examples:, has_direct_examples:)
+          parsed = scan.to_parsed_spec
+          scenarios = scenario_count(parsed.context_count, parsed.example_count,
+                                     has_examples: parsed.has_examples, has_direct_examples: parsed.has_direct_examples)
+          SpecCoverage.new(scenarios, parsed.annotations)
         end
         # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       end

data/lib/rubocop/rspec_parity/coverage_reporter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "rubocop_rspec_parity"
+
+module RuboCop
+  module RSpecParity
+    # Lists the branches a method still needs covered and renders ready-to-paste
+    # `context '...' do # rspec_parity:covers <branch>` stubs. Backs the
+    # `rspec-parity-cover` executable, reusing SufficientContexts' branch analysis.
+    #
+    # When the spec file exists, only branches without a covering annotation are
+    # listed (and only for methods that aren't already fully covered). When it is
+    # missing, every branch is listed so a new spec can be bootstrapped.
+    class CoverageReporter
+      Entry = Struct.new(:method_name, :branches, :spec_exists, :notes, keyword_init: true)
+
+      # +line+ narrows the report to the single method enclosing that source
+      # line, so `rspec-parity-cover file.rb:20` targets one method.
+      def initialize(source_path, spec_path: nil, line: nil)
+        @source_path = source_path
+        @spec_path = spec_path || derive_spec_path(source_path)
+        @line = line
+        @cop = RuboCop::Cop::RSpecParity::SufficientContexts.new
+      end
+
+      def entries
+        ast = parse
+        return [] unless ast
+
+        spec_content = File.read(@spec_path) if File.exist?(@spec_path)
+        method_nodes(ast).filter_map { |node| entry_for(node, spec_content) }
+      end
+
+      def render
+        entries.map { |entry| render_entry(entry) }.join("\n\n")
+      end
+
+      private
+
+      def method_nodes(ast)
+        nodes = ast.each_node(:def, :defs)
+        return nodes unless @line
+
+        # The method enclosing the target line (innermost wins if nested).
+        nodes.select { |node| @line.between?(node.first_line, node.last_line) }
+             .max_by(&:first_line)
+             .then { |node| node ? [node] : [] }
+      end
+
+      def entry_for(node, spec_content)
+        method_name = @cop.send(:method_name, node)
+        return bootstrap_entry(node, method_name) unless spec_content
+
+        gap = @cop.coverage_gap(node, spec_content)
+        return unless gap
+
+        Entry.new(method_name: method_name, branches: gap.uncovered, spec_exists: true, notes: notes_for(gap))
+      end
+
+      def bootstrap_entry(node, method_name)
+        branches = @cop.all_branches(node)
+        return if branches.empty?
+
+        Entry.new(method_name: method_name, branches: branches, spec_exists: false, notes: [])
+      end
+
+      # FYI lines: what we already know is covered, and a caveat when there are
+      # plain examples we can't attribute to a branch.
+      def notes_for(gap)
+        notes = []
+        if gap.annotated.any?
+          notes << "# already annotated as covered: #{gap.annotated.map(&:annotation_token).join(", ")}"
+        end
+        if gap.unannotated_specs.positive?
+          notes << "# note: #{gap.unannotated_specs} example(s)/context(s) here aren't annotated, so we can't tell " \
+                   "which branches they cover — all are listed below; drop or annotate the ones already tested."
+        end
+        notes
+      end
+
+      def render_entry(entry)
+        count = entry.branches.size
+        word = count == 1 ? "branch" : "branches"
+        qualifier = entry.spec_exists ? "uncovered " : ""
+        header = "# #{entry.method_name} — #{count} #{qualifier}#{word}:"
+        # Every branch has a unique label, so one stub per branch (one annotation
+        # covers exactly one branch).
+        stubs = entry.branches.map { |branch| context_stub(branch.annotation_token) }
+        [header, *entry.notes, stubs.join("\n\n")].join("\n")
+      end
+
+      def context_stub(token)
+        ["context '...' do", "  # rspec_parity:covers #{token}", "", "  it '...' do", "  end", "end"].join("\n")
+      end
+
+      def parse
+        RuboCop::ProcessedSource.new(File.read(@source_path), RUBY_VERSION.to_f, @source_path).ast
+      end
+
+      def derive_spec_path(path)
+        path.sub(%r{(^|/)app/}, '\1spec/').sub(/\.rb\z/, "_spec.rb")
+      end
+    end
+  end
+end

data/lib/rubocop/rspec_parity/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module RSpecParity
-    VERSION = "1.7.0"
+    VERSION = "2.0.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-rspec_parity
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Povilas Jurcys
@@ -41,7 +41,8 @@ description: A RuboCop plugin that provides custom cops to ensure RSpec test cov
   parity and enforce RSpec best practices in your Ruby projects.
 email:
 - po.jurcys@gmail.com
-executables: []
+executables:
+- rspec-parity-cover
 extensions: []
 extra_rdoc_files: []
 files:
@@ -54,6 +55,8 @@ files:
 - Rakefile
 - config/default.yml
 - docs/superpowers/specs/2026-05-21-trace-single-use-private-methods-design.md
+- docs/superpowers/specs/2026-06-15-covers-branch-annotations-design.md
+- exe/rspec-parity-cover
 - lib/rubocop-rspec_parity.rb
 - lib/rubocop/cop/rspec_parity/department_config.rb
 - lib/rubocop/cop/rspec_parity/file_has_spec.rb
@@ -62,6 +65,7 @@ files:
 - lib/rubocop/cop/rspec_parity/spec_file_finder.rb
 - lib/rubocop/cop/rspec_parity/sufficient_contexts.rb
 - lib/rubocop/rspec_parity.rb
+- lib/rubocop/rspec_parity/coverage_reporter.rb
 - lib/rubocop/rspec_parity/plugin.rb
 - lib/rubocop/rspec_parity/version.rb
 - lib/rubocop_rspec_parity.rb