rubocop-rspec_parity 1.6.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fc4286fcc69b46b490ae21db9ce9681ca7dd25577521e329d0bc3d89b33940a
-  data.tar.gz: da7872a16a143f8d44a178c7b1912996c8d5213fb1538a8f4231e9ceedf361dc
+  metadata.gz: 2bda6248c84f44ce1e039baac11b9e6b3075c3feb13bb4e06a9e804ff26436a6
+  data.tar.gz: ebc0e696c427bd033637609d7f1ad4aaa66c603a9ca1ed82adb09d2857c99161
 SHA512:
-  metadata.gz: 3d9f782158d6c053256401c6b687eb8b22dd1780f444b42783609b428ea0f82898a33e5c502818df86be8e56847a7be8012a99ead9c3aaffe91e5420d7be5a66
-  data.tar.gz: 44b7a03a46444bcacbec096e659fd435dc288278ba1f14d72d87311d1bca1b4feb32643c68c6fcb3ff2fbb5be1118adddddb8e4ec164b4d710cc00efbb287bc5
+  metadata.gz: 102aceedd06b6db82be97c0a45d95a57e22cb1b1ab7427875c6137f98dcfcc87b862cd2cc26dfc14d8f5604a24702166db12b6f94c1835f7e0395fd98082d556
+  data.tar.gz: ca83d65bb73322941c49160de66943b2e1c6c93f35db372ef8cb559e5ea2cf3bdf1d3cc31151e654c8d19b620ceb1f4ee2f6dbf5ef8a8213277bd243c7104111

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [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).
+
 ## [1.6.0] - 2026-06-11
 
 Fixed: `SufficientContexts` now counts each `it`/`example` within a single context as a separate scenario, so specs that cover branches with multiple examples (instead of separate contexts) no longer trigger false violations

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

@@ -8,7 +8,9 @@ module RuboCop
       # private/protected helpers that are called from exactly one place in
       # the same container.
       class PrivateMethodCallGraph # rubocop:disable Metrics/ClassLength
-        Result = Struct.new(:branches, :traced_methods)
+        # `branch_tally` is whatever the branch_counter returns (a BranchTally),
+        # or nil when nothing was inlined. It must respond to `+` and `total`.
+        Result = Struct.new(:branch_tally, :traced_methods)
 
         DYNAMIC_DISPATCH_SENDS = %i[send public_send __send__].freeze
         EVAL_METHODS = %i[class_eval instance_eval module_eval].freeze
@@ -28,13 +30,13 @@ module RuboCop
         end
 
         def inlinable_from(method_node, branch_counter)
-          return Result.new(0, []) unless @container
-          return Result.new(0, []) if dynamic_dispatch?
+          return Result.new(nil, []) unless @container
+          return Result.new(nil, []) if dynamic_dispatch?
 
           build! unless @built
 
           key = key_for(method_node)
-          return Result.new(0, []) unless @methods.key?(key)
+          return Result.new(nil, []) unless @methods.key?(key)
 
           traverse(key, branch_counter)
         end
@@ -42,7 +44,7 @@ module RuboCop
         private
 
         def traverse(start_key, branch_counter)
-          state = { visited: Set.new([start_key]), total: 0, traced: [] }
+          state = { visited: Set.new([start_key]), tally: nil, traced: [] }
           stack = callees_of(start_key)
           until stack.empty?
             key = stack.shift
@@ -51,7 +53,7 @@ module RuboCop
             visit_callee(key, branch_counter, state)
             stack.concat(callees_of(key))
           end
-          Result.new(state[:total], sorted_names(state[:traced]))
+          Result.new(state[:tally], sorted_names(state[:traced]))
         end
 
         def callees_of(key)
@@ -60,13 +62,21 @@ module RuboCop
 
         def visit_callee(key, branch_counter, state)
           state[:visited] << key
-          count = branch_counter.call(@methods[key][:node])
-          return unless count.positive?
+          tally = branch_counter.call(@methods[key][:node])
+          return unless tally.total.positive?
 
-          state[:total] += count
+          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)