rubocop-rspec_parity 1.4.6 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce7a1961eafacef8055e79414d28cfd37157f3d56aa8317befaa6e03ec8e1351
-  data.tar.gz: 3dc54f2de9deb5a2b5636d87aa2e0faabf625e62c4ab7540958f85ef92771868
+  metadata.gz: 4c9e27c87b24c7df00daa4eb0a88c31644a7f9986b384d5c875d42bb8358d071
+  data.tar.gz: aaeab2c5bccca24e24c39250299235ec3a46950f48bee5181a575b2cf45ef683
 SHA512:
-  metadata.gz: 56b3b3a5dd71d2360779382c0f4e8661c8c84097eacff2a76c9c4c8a53f3d1f1d0487f5e00f391923437c01ee72a7b7092ef8c6ccd74562aa0cf413138ea5498
-  data.tar.gz: 262cf615d136461f78253e2412cfb16f4aa270793c36789d7f4494071d95a0908a58f745983d842cdcb19d9ce1b9f054e3471c76ec919e1f1d7f567f3f08a53f
+  metadata.gz: 858ae886ee9a32d83cd0a8695f0e5d0acc8758af31802ef5fdfe3d4686860dc40991adfa29cacb5a24a4191a9d94011e531b35edccbc40b8300b83c2c46b2996
+  data.tar.gz: 7d1184d3ea750869fcf9d655865e3a1d7b93a3d30f2292bc8e57fbd6cb4166e8da9a8ee274c54ccb9d2f825039911b230ede34731be80f9ade8c98dd3a59e8df

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [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
@@ -44,6 +45,8 @@ module RuboCop
         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)"
+
         APP_DIR_PATTERN = %r{/app/}
 
         EXCLUDED_METHODS = %w[initialize].freeze
@@ -59,6 +62,8 @@ module RuboCop
         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 +81,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 +112,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,
+                           context_word: pluralize("context", contexts),
+                           missing: missing,
+                           missing_word: pluralize("context", 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)

data/lib/rubocop/rspec_parity/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module RSpecParity
-    VERSION = "1.4.6"
+    VERSION = "1.5.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.5.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: []