rubocop-rspec_parity 1.7.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70e06a85873dc993a895443df9bab8892de60d0cc75573ffdc6487245c09dcf
-  data.tar.gz: 7d8baed7d58b13d98fb7b7e14084c3c81dcb1905df3bacfc52772dcb65ba7dbd
+  metadata.gz: c258389ca56666df76d2865c8fee4ecca3dec132d02b7295d6e245747dbc4896
+  data.tar.gz: 02612dbd491de04d9819742f61bcdb47933837a6b3211d9888765e9eea94ef36
 SHA512:
-  metadata.gz: 66ae9ef49f40f4323af10a733c9c1eb6bbc7a49883b3f00619fda6610c22b035ca53aa9e6b259259df8c7a5cb49aded12d56e8b96082074036f4fd9dc960baf3
-  data.tar.gz: 18635158b5155856049fdbfd33aaeb732b013d729467f1aefd8751873f997411b78a4d1489fa692ef64b0030691a6141b8ab6c6ca28e95398ea5d87201d0b3e7
+  metadata.gz: 6fb8521af37136c1449fc5292fcc7658966f42f538197081d5a9ff53985dc4901c70e5e17c7a93c3204c8be0dc179c10c909ec2499ced966251d7ffc124e14e9
+  data.tar.gz: d18fc9c48f6063187c20472ada669bbf374192687dce5ae7e91d5bfceb2dc7b282340e623e72165363ad398d4e8cb43251dc8ef7820306cab73279ef71c92c41

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [2.0.1] - 2026-06-18
+
+Fixed: `PublicMethodHasSpec` relaxed validation for single-public-method classes (e.g. service objects) no longer passes when the spec's only method-style `describe`/`context` covers a different method — if a method describe is present it must describe the actual public method.
+
+## [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,76 @@ 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. A mistyped label is reported with a did-you-mean suggestion.
+
+Each annotation covers exactly one branch, and the normal expectation is one annotation per context — one context, one scenario, one branch. In rare cases a single context genuinely exercises several branches at once; you can then list more than one branch on it, either as separate comments or with a `;`-separated list:
+
+```ruby
+context 'when fully privileged' do
+  # rspec_parity:covers user.admin?
+  # rspec_parity:covers user.staff?
+  it { is_expected.to be_allowed }
+end
+
+# or, equivalently, on one line:
+context 'when fully privileged' do # rspec_parity:covers user.admin?; user.staff?
+  it { is_expected.to be_allowed }
+end
+```
+
+Reach for this only when the branches really are covered together — multiple annotations on a context that only tests one path inflate coverage and defeat the point of the check.
+
+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/public_method_has_spec.rb

@@ -219,8 +219,9 @@ module RuboCop
 
           # Check if relaxed validation applies
           if matches_skip_path? && count_public_methods(node) == 1
-            # For single-method classes in configured paths, just check for examples
-            return if spec_paths.any? { |spec_path| spec_has_examples?(spec_path, class_name) }
+            # For single-method classes in configured paths, the method describe is optional —
+            # but if one is present, it must describe the actual public method, not a private/random one.
+            return if relaxed_spec_valid?(spec_paths, class_name, method_name, instance_method, flexible_prefix)
           elsif spec_paths.any? do |sp|
                   spec_covers_method?(sp, method_name, instance_method, flexible_prefix: flexible_prefix)
                 end
@@ -233,6 +234,25 @@ module RuboCop
         end
         # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
+        # Relaxed validation for single-public-method classes in skip paths.
+        # Passes when the spec describes the class with examples AND either has no
+        # method-style describe/context block at all, or has one that covers the public method.
+        def relaxed_spec_valid?(spec_paths, class_name, method_name, instance_method, flexible_prefix)
+          return false unless spec_paths.any? { |sp| spec_has_examples?(sp, class_name) }
+          return true unless spec_paths.any? { |sp| spec_has_method_describe?(sp) }
+
+          spec_paths.any? do |sp|
+            spec_covers_method?(sp, method_name, instance_method, flexible_prefix: flexible_prefix)
+          end
+        end
+
+        # Detects a method-style block, e.g. describe '#foo' / context '.bar'
+        # (the char right after the quote is a `#` or `.` prefix), as opposed to a
+        # plain descriptive string or a class constant.
+        def spec_has_method_describe?(spec_path)
+          File.read(spec_path).match?(/(?:describe|context)\s+['"][#.][^'"]+['"]/)
+        end
+
         def spec_covers_method?(spec_path, method_name, instance_method, flexible_prefix: false)
           return true if method_tested_in_spec?(spec_path, method_name, instance_method)
           return true if flexible_prefix && method_tested_in_spec?(spec_path, method_name, !instance_method)