rubocop-rspec_parity 1.4.6 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce7a1961eafacef8055e79414d28cfd37157f3d56aa8317befaa6e03ec8e1351
-  data.tar.gz: 3dc54f2de9deb5a2b5636d87aa2e0faabf625e62c4ab7540958f85ef92771868
+  metadata.gz: 2fc4286fcc69b46b490ae21db9ce9681ca7dd25577521e329d0bc3d89b33940a
+  data.tar.gz: da7872a16a143f8d44a178c7b1912996c8d5213fb1538a8f4231e9ceedf361dc
 SHA512:
-  metadata.gz: 56b3b3a5dd71d2360779382c0f4e8661c8c84097eacff2a76c9c4c8a53f3d1f1d0487f5e00f391923437c01ee72a7b7092ef8c6ccd74562aa0cf413138ea5498
-  data.tar.gz: 262cf615d136461f78253e2412cfb16f4aa270793c36789d7f4494071d95a0908a58f745983d842cdcb19d9ce1b9f054e3471c76ec919e1f1d7f567f3f08a53f
+  metadata.gz: 3d9f782158d6c053256401c6b687eb8b22dd1780f444b42783609b428ea0f82898a33e5c502818df86be8e56847a7be8012a99ead9c3aaffe91e5420d7be5a66
+  data.tar.gz: 44b7a03a46444bcacbec096e659fd435dc288278ba1f14d72d87311d1bca1b4feb32643c68c6fcb3ff2fbb5be1118adddddb8e4ec164b4d710cc00efbb287bc5

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [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
+Updated: `SufficientContexts` violation message now explains that each branch needs one `context` or `it`, and that compound conditions like `a && b` need a scenario per operand
+
+## [1.5.0] - 2026-05-21
+
+Added: `SufficientContexts` now inlines branches from private/protected helpers that are called from exactly one site in the same class (controlled by the new `TraceSingleUsePrivateMethods` config key, default `true`). Violation messages list the helpers whose branches were counted.
+
 ## [1.4.6] - 2026-04-10
 
 Fixed: Method name matching no longer falsely matches substring occurrences in unrelated context descriptions

data/config/default.yml

@@ -32,5 +32,6 @@ RSpecParity/SufficientContexts:
   Description: 'Ensures specs have at least as many contexts as the method has branches.'
   Enabled: true
   IgnoreMemoization: true
+  TraceSingleUsePrivateMethods: true
   SkipMethodDescribeFor: []
   DescribeAliases: {}

data/docs/superpowers/specs/2026-05-21-trace-single-use-private-methods-design.md

@@ -0,0 +1,204 @@
+# Trace branches through single-use private methods
+
+## Problem
+
+`RSpecParity/SufficientContexts` currently counts branches only inside the body of the public method under inspection. When a public method is decomposed into private helpers — idiomatic Ruby style — the branches in those helpers don't count toward the required spec-context total. The cop effectively penalizes clean decomposition.
+
+## Goal
+
+When a private (or protected) method is called from exactly one place in the same class/module, treat its branches as belonging to the caller. Apply transitively: if public `P` calls single-use private `A` which calls single-use private `B`, `B`'s branches roll into `P`'s total.
+
+## Configuration
+
+Single key on `RSpecParity/SufficientContexts`:
+
+```yaml
+RSpecParity/SufficientContexts:
+  TraceSingleUsePrivateMethods: true   # default
+```
+
+Set to `false` to restore the prior behavior.
+
+No max-depth knob — depth is unlimited.
+
+## Behavior
+
+### What gets inlined
+
+A private or protected method's branches roll into the caller's total when:
+
+- the method is defined in the same class/module body as the caller
+- it has exactly one static call site across the whole class/module body
+- the enclosing class/module has no dynamic dispatch (see below)
+
+Inlining is transitive: traversal follows the call graph from the public method, descending into any callee that satisfies the rules. A visited-set prevents double counting in diamond shapes and protects against mutual-recursion cycles.
+
+Instance methods (`def foo`) and class methods (`def self.foo`) live in separate namespaces in the graph — a class method calling `bar` resolves only to a class-level `bar`.
+
+### Dynamic dispatch — class-wide opt out
+
+If the class/module body contains any of the following, the call graph is considered untrustworthy and **no inlining occurs anywhere in that class**:
+
+- `send` / `public_send` with a non-symbol-literal argument
+- `define_method`
+- `method_missing` / `respond_to_missing?` definitions
+- `class_eval` / `instance_eval` / `module_eval` with a string argument
+- `method(:foo)` / `&:foo` (symbol-to-proc) references — these resolve methods symbolically and may extend reach beyond statically visible call sites
+
+This is conservative by design — a false-positive "missing context" warning is worse UX than a missed inlining opportunity.
+
+### Branchless helpers
+
+A private method whose own body contributes zero branches:
+
+- still has its callees traversed (it may call branchy helpers)
+- is **not** named in the `traced_methods` list reported to the user
+- doesn't count toward the user-visible "branches came from these methods" message
+
+### Visibility tracking
+
+The class-body walker recognizes all visibility forms:
+
+- modifier `send` nodes — `public`, `private`, `protected` on their own lines
+- declaration form — `private :foo, :bar`, `private_class_method :foo`
+- inline form — `private def foo …` and `private_class_method def self.foo …`
+- `class << self` blocks for class-method visibility
+
+## Architecture
+
+### New file: `lib/rubocop/cop/rspec_parity/private_method_call_graph.rb`
+
+Class `RuboCop::Cop::RSpecParity::PrivateMethodCallGraph`.
+
+**Constructor**
+
+```ruby
+PrivateMethodCallGraph.new(container_node)
+```
+
+`container_node` is the enclosing `:class`, `:module`, or `:sclass` AST node, or `nil` when the def is at top level (in which case nothing inlines).
+
+**Public API**
+
+```ruby
+graph.dynamic_dispatch?
+# => Boolean
+
+graph.inlinable_from(method_node, branch_counter)
+# branch_counter: a callable (->(node) { Integer })
+# returns: Struct.new(:branches, :traced_methods)
+#   branches        — total extra branches from reachable single-use helpers
+#   traced_methods  — Array<String> of names of helpers that contributed > 0 branches,
+#                     ordered by source position (deterministic)
+```
+
+**Internal data**
+
+```
+@methods = {
+  [:instance, "foo"] => { node:, visibility: :private, callees: Set[[:instance, "bar"]] },
+  [:class, "build"]  => { node:, visibility: :public,  callees: Set[…] },
+  …
+}
+
+@call_count = { method_key => Integer }   # union-count across all methods' callees
+```
+
+The graph is built lazily on first use and memoized on the instance. `SufficientContexts` keeps one graph per container node (memoized via `node.equal?` identity).
+
+### Changes to `SufficientContexts`
+
+1. New instance var `@trace_single_use_private = cop_config.fetch("TraceSingleUsePrivateMethods", true)` in `initialize`.
+2. New instance var `@call_graphs = {}.compare_by_identity` for per-container memoization.
+3. In `check_method`, after computing `branches = count_branches(node)`:
+   ```ruby
+   traced_methods = []
+   if @trace_single_use_private
+     container = find_class_or_module(node)
+     if container
+       graph = (@call_graphs[container] ||= PrivateMethodCallGraph.new(container))
+       extra = graph.inlinable_from(node, method(:count_branches))
+       branches += extra.branches
+       traced_methods = extra.traced_methods
+     end
+   end
+   ```
+4. Pass `traced_methods` into the message format. Update `MSG` to a base + optional suffix:
+   ```ruby
+   BASE_MSG = "Method `%<method_name>s` has %<branches>d %<branch_word>s but only " \
+              "%<contexts>d %<context_word>s in spec. Add %<missing>d more %<missing_word>s " \
+              "to cover all branches."
+   TRACED_SUFFIX = " (including branches from: %<traced>s)"
+   ```
+   Append `TRACED_SUFFIX` only when `traced_methods` is non-empty.
+
+### Config defaults
+
+`config/default.yml` — add under `RSpecParity/SufficientContexts`:
+
+```yaml
+TraceSingleUsePrivateMethods: true
+```
+
+## Edge cases
+
+- **Top-level defs** — no container → no inlining (graph is never built).
+- **`include`d / inherited methods** — invisible; not in `@methods`; never inflate counts. Calls *to* such methods don't appear in any helper's `callees`, so they don't push another method's call count up either. Correct.
+- **`super`** — doesn't reference a name we track. No effect on counts. Correct.
+- **Mutual recursion** — `priv_a` calls `priv_b`, `priv_b` calls `priv_a`, both used once from `pub`. Call count for each is 2 (one from `pub`, one from the other). Neither inlines. Correct.
+- **Diamond** — `pub` → `priv_a`, `pub` → `priv_b`, both call `priv_c`. `priv_c` call count is 2, doesn't inline. `priv_a` and `priv_b` each have call count 1 → do inline.
+- **`private def foo …`** — at AST level this is a `:send` whose argument is the `:def`. Walker handles both: detects the `:def` child, registers visibility, recurses into the def body for callees.
+- **`class << self`** — the `:sclass` body adds class-method entries with their own visibility state.
+- **Method named the same as a Kernel method** (e.g. `format`) — call-site detection uses receiver=`nil` send nodes whose method name matches a defined method in the same container. Kernel calls without a same-named local def are not in `@methods` and are ignored.
+
+## Testing
+
+### New file: `spec/rubocop/cop/rspec_parity/private_method_call_graph_spec.rb`
+
+Pure unit tests on the graph class — no RuboCop cop infrastructure. Parse a source string via `RuboCop::ProcessedSource`, get the class node, exercise the API. Covers:
+
+- Empty class → graph returns 0 branches, no traced methods
+- Single-use private with one branch → 1, [name]
+- Two-deep chain → both contribute, both named
+- Branchless intermediate → traversal continues, intermediate excluded from traced list
+- Two-caller helper → not inlined
+- Diamond → only single-use intermediates inline
+- Mutual recursion → neither inlines
+- Class method calling private class method → traced
+- Class method calling instance method of same name → not linked
+- `private def foo …` form recognized
+- `private :foo` declaration form recognized
+- Dynamic dispatch markers each trigger `dynamic_dispatch?`:
+  - `send(var)` (non-literal)
+  - `send(:foo)` with literal — does NOT trigger (literal symbol is safe — but per design we still treat it as dynamic because we can't statically prove the symbol set is closed; cover this in tests as a deliberate conservative choice — see Open Questions)
+  - `define_method(:foo) { … }`
+  - `method_missing` def
+  - `class_eval("def x; end")`
+  - `method(:foo)`
+  - `&:foo` block argument
+
+### Extensions to `spec/rubocop/cop/rspec_parity/sufficient_contexts_spec.rb`
+
+- Public method with single-use private helper → reports inflated branch count, message includes helper name
+- Multi-context spec satisfies inflated count → no offense
+- Two callers of same helper → no inflation
+- `TraceSingleUsePrivateMethods: false` config → behavior identical to current cop
+- Class with dynamic dispatch → no inflation, no traced_methods in message
+- Branchless helper that calls branchy helper → only branchy helper named in message
+
+## Performance
+
+Per file, RuboCop already parses and walks the AST. The new work is:
+
+- One pass over each class/module body to populate `@methods` (linear in body size)
+- One additional pass to count callees per method (linear in total send nodes)
+- Per public-method check: DFS over reachable single-use helpers — bounded by total methods in the class
+
+Class graphs are memoized by container identity, so a file with N public methods builds the graph once, not N times. Negligible compared to RuboCop's existing parsing and node-walking.
+
+## Open questions resolved during design
+
+- **Default value** — `true`. Opt-out rather than opt-in. The user accepts that existing users may see new offenses on their next gem update; the new behavior is more accurate.
+- **Protected methods** — treated the same as private (still internal API).
+- **Class methods** — same treatment as instance methods, separate namespace in the graph.
+- **Symbol-to-proc / `method(:foo)`** — treated as dynamic dispatch (conservative). The set of method references through these forms is hard to bound statically, and the cost of being conservative is just "no inlining for this class" not "wrong behavior".

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

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module RSpecParity
+      # Builds a static call graph for the methods defined directly inside a
+      # class/module node. Used by SufficientContexts to inline branches from
+      # 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)
+
+        DYNAMIC_DISPATCH_SENDS = %i[send public_send __send__].freeze
+        EVAL_METHODS = %i[class_eval instance_eval module_eval].freeze
+
+        def initialize(container_node)
+          @container = container_node
+          @methods = {}
+          @order = []
+          @built = false
+        end
+
+        def dynamic_dispatch?
+          return false unless @container
+
+          @dynamic_dispatch ||= detect_dynamic_dispatch
+          @dynamic_dispatch == :yes
+        end
+
+        def inlinable_from(method_node, branch_counter)
+          return Result.new(0, []) unless @container
+          return Result.new(0, []) if dynamic_dispatch?
+
+          build! unless @built
+
+          key = key_for(method_node)
+          return Result.new(0, []) unless @methods.key?(key)
+
+          traverse(key, branch_counter)
+        end
+
+        private
+
+        def traverse(start_key, branch_counter)
+          state = { visited: Set.new([start_key]), total: 0, traced: [] }
+          stack = callees_of(start_key)
+          until stack.empty?
+            key = stack.shift
+            next unless inlinable?(key, state[:visited])
+
+            visit_callee(key, branch_counter, state)
+            stack.concat(callees_of(key))
+          end
+          Result.new(state[:total], sorted_names(state[:traced]))
+        end
+
+        def callees_of(key)
+          @methods[key][:callees].to_a
+        end
+
+        def visit_callee(key, branch_counter, state)
+          state[:visited] << key
+          count = branch_counter.call(@methods[key][:node])
+          return unless count.positive?
+
+          state[:total] += count
+          state[:traced] << key
+        end
+
+        def inlinable?(key, visited)
+          return false if visited.include?(key)
+          return false unless @methods.key?(key)
+          return false if @methods[key][:visibility] == :public
+
+          call_count(key) == 1
+        end
+
+        def call_count(key)
+          @call_counts ||= compute_call_counts
+          @call_counts[key] || 0
+        end
+
+        def compute_call_counts
+          counts = Hash.new(0)
+          @methods.each_value do |entry|
+            entry[:callees].each { |callee_key| counts[callee_key] += 1 }
+          end
+          counts
+        end
+
+        def sorted_names(keys)
+          keys.sort_by { |k| @order.index(k) || @order.size }
+              .map { |k| @methods[k][:name] }
+        end
+
+        def key_for(node)
+          [node.defs_type? ? :class : :instance, node.method_name.to_s]
+        end
+
+        # ---------- Build phase ----------
+
+        def build!
+          @built = true
+          walk_body(body_children(@container), :public, :instance)
+          @methods.each_value { |entry| entry[:callees] = collect_callees(entry[:node], entry[:namespace]) }
+        end
+
+        def walk_body(children, visibility, namespace) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+          children.each do |child|
+            next unless child
+
+            case child.type
+            when :def
+              register_method(child, :instance, visibility) if namespace == :instance
+              register_method(child, :class, visibility) if namespace == :class
+            when :defs
+              register_method(child, :class, :public)
+            when :send
+              visibility = handle_visibility_send(child, visibility, namespace) || visibility
+            when :sclass
+              walk_body(body_children(child), :public, :class)
+            end
+          end
+        end
+
+        def register_method(def_node, kind, visibility)
+          name = def_node.method_name.to_s
+          key = [kind, name]
+          @methods[key] = { name: name, node: def_node, visibility: visibility, namespace: kind, callees: Set.new }
+          @order << key
+        end
+
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        def handle_visibility_send(send_node, current_visibility, namespace)
+          name = send_node.method_name
+          args = send_node.arguments
+
+          if %i[public private protected].include?(name)
+            kind = namespace == :class ? :class : :instance
+            if args.empty?
+              return name
+            elsif args.first.def_type?
+              register_method(args.first, kind, name)
+              return current_visibility
+            else
+              apply_named_visibility(args, name, kind)
+              return current_visibility
+            end
+          end
+
+          if %i[private_class_method public_class_method].include?(name)
+            target_vis = name == :private_class_method ? :private : :public
+            if args.first&.defs_type? || args.first&.def_type?
+              register_method(args.first, :class, target_vis)
+            else
+              apply_named_visibility(args, target_vis, :class)
+            end
+          end
+
+          current_visibility
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+        def apply_named_visibility(args, visibility, kind)
+          args.each do |arg|
+            next unless arg.sym_type? || arg.str_type?
+
+            key = [kind, arg.value.to_s]
+            @methods[key][:visibility] = visibility if @methods.key?(key)
+          end
+        end
+
+        # ---------- Callee collection ----------
+
+        def collect_callees(def_node, namespace)
+          callees = Set.new
+          body = def_node.body
+          return callees unless body
+
+          each_send(body) do |send_node|
+            add_callee(callees, send_node, namespace)
+          end
+          callees
+        end
+
+        def each_send(node, &block)
+          return unless node.is_a?(RuboCop::AST::Node)
+          return if node.def_type? || node.defs_type?
+
+          yield node if node.send_type?
+          node.children.each { |child| each_send(child, &block) if child.is_a?(RuboCop::AST::Node) }
+        end
+
+        def add_callee(callees, send_node, namespace)
+          receiver = send_node.receiver
+          return unless receiver.nil? || receiver.self_type?
+
+          name = literal_send_target(send_node) || send_node.method_name.to_s
+          key = [namespace, name]
+          callees << key if @methods.key?(key)
+        end
+
+        # `send(:foo)` / `public_send(:foo)` with a literal symbol → treat as a static call to `foo`.
+        def literal_send_target(send_node)
+          return nil unless DYNAMIC_DISPATCH_SENDS.include?(send_node.method_name)
+
+          first_arg = send_node.arguments.first
+          return nil unless first_arg&.sym_type? || first_arg&.str_type?
+
+          first_arg.value.to_s
+        end
+
+        # ---------- Dynamic dispatch detection ----------
+
+        def detect_dynamic_dispatch
+          return :no unless @container&.body
+
+          found = false
+          walk_for_dynamic(@container.body) { found = true }
+          found ? :yes : :no
+        end
+
+        def walk_for_dynamic(node, &block)
+          return unless node.is_a?(RuboCop::AST::Node)
+          return yield if dynamic_dispatch_node?(node)
+
+          node.children.each { |child| walk_for_dynamic(child, &block) if child.is_a?(RuboCop::AST::Node) }
+        end
+
+        def dynamic_dispatch_node?(node)
+          return method_missing_def?(node) if node.def_type?
+          return symbol_to_proc_block_pass?(node) if node.block_pass_type?
+          return false unless node.send_type?
+
+          dynamic_send?(node) || define_method?(node) || string_eval?(node) || method_reference?(node)
+        end
+
+        def method_missing_def?(node)
+          %i[method_missing respond_to_missing?].include?(node.method_name)
+        end
+
+        def symbol_to_proc_block_pass?(node)
+          node.children.first&.sym_type?
+        end
+
+        def dynamic_send?(node)
+          return false unless DYNAMIC_DISPATCH_SENDS.include?(node.method_name)
+
+          first = node.arguments.first
+          return false if first.nil?
+          return false if first.sym_type? || first.str_type?
+
+          true
+        end
+
+        def define_method?(node)
+          node.method_name == :define_method
+        end
+
+        def string_eval?(node)
+          return false unless EVAL_METHODS.include?(node.method_name)
+
+          node.arguments.any? { |arg| arg.str_type? || arg.dstr_type? }
+        end
+
+        def method_reference?(node)
+          node.method_name == :method && node.arguments.size == 1 && node.arguments.first.sym_type?
+        end
+
+        def body_children(node)
+          return [] unless node&.body
+
+          node.body.begin_type? ? node.body.children : [node.body]
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "spec_file_finder"
+require_relative "private_method_call_graph"
 
 module RuboCop
   module Cop
@@ -41,8 +42,11 @@ module RuboCop
         include DepartmentConfig
         include SpecFileFinder
 
-        MSG = "Method `%<method_name>s` has %<branches>d %<branch_word>s but only %<contexts>d %<context_word>s " \
-              "in spec. Add %<missing>d more %<missing_word>s to cover all branches."
+        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)."
+
+        TRACED_SUFFIX = " (including branches from: %<traced>s)"
 
         APP_DIR_PATTERN = %r{/app/}
 
@@ -56,9 +60,14 @@ module RuboCop
           /^autosave_/
         ].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)
+
         def initialize(config = nil, options = nil)
           super
           @ignore_memoization = cop_config.fetch("IgnoreMemoization", true)
+          @trace_single_use_private = cop_config.fetch("TraceSingleUsePrivateMethods", true)
+          @call_graphs = {}.compare_by_identity
         end
 
         def on_def(node)
@@ -76,6 +85,12 @@ module RuboCop
           return if excluded_method?(method_name(node))
 
           branches = count_branches(node)
+          traced_methods = []
+          if @trace_single_use_private
+            extra = inlined_branches(node)
+            branches += extra.branches
+            traced_methods = extra.traced_methods
+          end
           return if branches < 2 # Only check methods with branches
 
           class_name = extract_class_name(node)
@@ -101,15 +116,28 @@ module RuboCop
           return if contexts >= branches
 
           missing = branches - contexts
-          add_offense(node,
-                      message: format(MSG,
-                                      method_name: method_name(node),
-                                      branches: branches,
-                                      branch_word: pluralize("branch", branches),
-                                      contexts: contexts,
-                                      context_word: pluralize("context", contexts),
-                                      missing: missing,
-                                      missing_word: pluralize("context", missing)))
+          add_offense(node, message: build_message(node, branches, contexts, missing, traced_methods))
+        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
+        end
+
+        def inlined_branches(node)
+          container = find_class_or_module(node)
+          return PrivateMethodCallGraph::Result.new(0, []) unless container
+
+          graph = (@call_graphs[container] ||= PrivateMethodCallGraph.new(container))
+          graph.inlinable_from(node, method(:count_branches))
         end
 
         def method_name(node)
@@ -207,21 +235,38 @@ module RuboCop
 
         def count_contexts_for_method(spec_content, method_name)
           method_pattern = Regexp.escape(method_name)
-          context_count, has_examples, has_direct_examples = parse_spec_content(spec_content, method_pattern)
+          result = parse_spec_content(spec_content, method_pattern)
+
+          scenario_count(
+            result.context_count, result.example_count,
+            has_examples: result.has_examples, has_direct_examples: result.has_direct_examples
+          )
+        end
+
+        # A test scenario is the smaller unit between "a context block" and "an
+        # `it`/`example`". A single context whose examples each exercise a branch
+        # covers as many scenarios as it has examples, so the scenario count is
+        # the larger of the context-based count and the raw example count. Empty
+        # placeholder contexts (no examples) still count via the context-based
+        # path, so this never under-counts relative to the old behaviour.
+        def scenario_count(context_count, example_count, has_examples:, has_direct_examples:)
+          context_based =
+            if context_count.positive? && has_direct_examples
+              context_count + 1
+            elsif context_count.zero? && has_examples
+              1
+            else
+              context_count
+            end
 
-          if context_count.positive? && has_direct_examples
-            context_count + 1
-          elsif context_count.zero? && has_examples
-            1
-          else
-            context_count
-          end
+          [context_based, example_count].max
         end
 
         # 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
           base_indent = 0
@@ -245,6 +290,7 @@ module RuboCop
                 context_count += 1
               elsif nested_example?(line)
                 has_examples = true
+                example_count += 1
                 child_indent ||= current_indent
                 has_direct_examples = true if current_indent == child_indent
               end
@@ -253,7 +299,7 @@ module RuboCop
             end
           end
 
-          [context_count, has_examples, has_direct_examples]
+          ParsedSpec.new(context_count, example_count, has_examples, has_direct_examples)
         end
         # rubocop:enable Metrics/MethodLength
 
@@ -283,7 +329,6 @@ module RuboCop
 
           case word
           when "branch" then "branches"
-          when "context" then "contexts"
           else "#{word}s"
           end
         end
@@ -423,6 +468,7 @@ module RuboCop
           # 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
@@ -438,18 +484,13 @@ module RuboCop
               context_count += 1
             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
             end
           end
 
-          if context_count.positive? && has_direct_examples
-            context_count + 1
-          elsif context_count.zero? && has_examples
-            1
-          else
-            context_count
-          end
+          scenario_count(context_count, example_count, has_examples:, has_direct_examples:)
         end
         # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       end

data/lib/rubocop/rspec_parity/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module RSpecParity
-    VERSION = "1.4.6"
+    VERSION = "1.6.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-rspec_parity
 version: !ruby/object:Gem::Version
-  version: 1.4.6
+  version: 1.6.0
 platform: ruby
 authors:
 - Povilas Jurcys
@@ -53,9 +53,11 @@ files:
 - README.md
 - Rakefile
 - config/default.yml
+- docs/superpowers/specs/2026-05-21-trace-single-use-private-methods-design.md
 - lib/rubocop-rspec_parity.rb
 - lib/rubocop/cop/rspec_parity/department_config.rb
 - lib/rubocop/cop/rspec_parity/file_has_spec.rb
+- lib/rubocop/cop/rspec_parity/private_method_call_graph.rb
 - lib/rubocop/cop/rspec_parity/public_method_has_spec.rb
 - lib/rubocop/cop/rspec_parity/spec_file_finder.rb
 - lib/rubocop/cop/rspec_parity/sufficient_contexts.rb
@@ -87,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.3
 specification_version: 4
 summary: RuboCop plugin for enforcing RSpec spec parity and best practices
 test_files: []