rubocop-sorted_methods_by_call 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 635807053b2df421a854cdc73001545451f8a7017623c93c6d6eb89bf304e172
-  data.tar.gz: cacd6163f57b4ee053b3053a950240b71bc2665b8bd93d6a4dba916d02490683
+  metadata.gz: 3cac98639251f1177bd34bb14fb7098b8adbda6eae96d186a202a2ce75d37f77
+  data.tar.gz: b198db699e4cba49214d9f4188a11ae14965c7ba57b51dfa9dc046c0332762b0
 SHA512:
-  metadata.gz: 4bedcb4e198e0d75209bb286a15d55ba16ec3ea026cbc52769f7acb13bc8c8f118cac590d4ca7fd16bdfd82730e380c3d02782e6dbf24001fc4815f316928d2a
-  data.tar.gz: 05d4815fcce53e4c90e8b66ac1933363ec3a4940f551d6f0464a993b63b2b3af36ba8795be3bea7a34cb462ad9aa6f39da011a87f055ac5154e8e4174319ffab
+  metadata.gz: 774b4c4bced8dec5236826739aa7bb90a9266fe77a5355d677abbe4a629b2c20928861689f2b00c7063f471f3811f03605d624be6d7e4607d67a624578966d56
+  data.tar.gz: eb0b7cca4f2d460f4ff2b8c1cd3c70756011b424041f29715e0838a8678cac4192b2ac2e717a2f0a5b4ae6e6736bf60eae1dad6201578ad20bb657fe33033065

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-11-06 15:18:01 UTC using RuboCop version 1.81.7.
+# on 2025-11-12 14:06:36 UTC using RuboCop version 1.81.7.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -22,30 +22,30 @@ Gemspec/RequiredRubyVersion:
 # Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 60
+  Max: 87
 
 # Offense count: 2
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 43
+  Max: 36
 
 # Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 20
+  Max: 31
 
 # Offense count: 7
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 58
+  Max: 59
 
 # Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 22
+  Max: 34
 
-# Offense count: 12
+# Offense count: 19
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 37

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rubocop-sorted_methods_by_call (1.1.0)
+    rubocop-sorted_methods_by_call (1.1.2)
       lint_roller
       rubocop (>= 1.72.0)
 

data/config/default.yml

@@ -1,6 +1,6 @@
 SortedMethodsByCall/Waterfall:
   Description: "Enforces method ordering based on call relationships."
-  Enabled: false
-  VersionAdded: "1.1.0"
+  Enabled: true
+  VersionAdded: "1.1.2"
   SafeAutoCorrect: false
   AllowedRecursion: true

data/lib/rubocop/cop/sorted_methods_by_call/waterfall.rb

@@ -3,89 +3,107 @@
 module RuboCop
   module Cop
     module SortedMethodsByCall
-      # +RuboCop::Cop::SortedMethodsByCall::Waterfall+ enforces "waterfall" ordering:
-      # define a method after any method that calls it (within the same scope).
+      # Enforces "waterfall" ordering: define a method after any method
+      # that calls it within the same scope. Produces a top-down reading flow
+      # where orchestration appears before implementation details.
       #
-      # - Scopes: class/module/sclass (top-level can be enabled in config)
+      # - Scopes: class/module/sclass (top-level can be analyzed via on_begin)
       # - Offense: when a callee is defined above its caller
       # - Autocorrect: UNSAFE; reorders methods within a contiguous visibility section
+      #   (does not cross other statements or nested scopes). Preserves leading
+      #   doc comments on each method. Skips cycles and non-contiguous groups.
       #
-      # Example (good):
-      #   def call
-      #     foo
-      #     bar
-      #   end
+      # Configuration
+      # - AllowedRecursion [Boolean] (default: true)
+      #     If true, the cop ignores violations that are part of a mutual recursion
+      #     cycle (callee → … → caller). If false, such cycles are reported.
+      # - SafeAutoCorrect [Boolean] (default: false)
+      #     Autocorrection is unsafe and only runs under -A, never under -a.
       #
-      #   private
+      # @example Good (waterfall order)
+      #   class Service
+      #     def call
+      #       foo
+      #       bar
+      #     end
       #
-      #   def bar
-      #     method123
-      #   end
+      #     private
       #
-      #   def method123
-      #     foo
-      #   end
+      #     def bar
+      #       method123
+      #     end
       #
-      #   def foo
-      #     123
-      #   end
+      #     def method123
+      #       foo
+      #     end
       #
-      # Example (bad):
-      #   def foo
-      #     123
+      #     def foo
+      #       123
+      #     end
       #   end
       #
-      #   def call
-      #     foo
+      # @example Bad (violates waterfall order)
+      #   class Service
+      #     def call
+      #       foo
+      #       bar
+      #     end
+      #
+      #     private
+      #
+      #     def foo
+      #       123
+      #     end
+      #
+      #     def bar
+      #       method123
+      #     end
+      #
+      #     def method123
+      #       foo
+      #     end
       #   end
       #
-      # Autocorrect (unsafe, opt-in via SafeAutoCorrect: false): topologically sorts the contiguous
-      # block of defs to satisfy edges (caller -> callee). Skips cycles and non-contiguous groups.
+      # @see #analyze_scope
+      # @see #try_autocorrect
       class Waterfall < ::RuboCop::Cop::Base # rubocop:disable Metrics/ClassLength
         include ::RuboCop::Cop::RangeHelp
         extend ::RuboCop::Cop::AutoCorrector
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall::MSG+ -> String
-        #
-        # Template message for offenses.
+        # Template message for offenses where a callee appears before its caller.
         MSG = 'Define %<callee>s after its caller %<caller>s (waterfall order).'
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#on_begin+ -> void
+        # Entry point for root :begin nodes (top-level).
         #
-        # Entry point for root :begin nodes (top-level). Whether it is analyzed
-        # depends on configuration (e.g., CheckTopLevel). By default, only class/module scopes are analyzed.
+        # Whether top-level is analyzed depends on how the code is structured;
+        # by default we only analyze class/module/sclass scopes, but top-level
+        # is supported through this hook.
         #
-        # @param [RuboCop::AST::Node] node
+        # @param node [RuboCop::AST::Node] root :begin node
         # @return [void]
         def on_begin(node)
           analyze_scope(node)
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#on_class+ -> void
-        #
         # Entry point for class scopes.
         #
-        # @param [RuboCop::AST::Node] node
+        # @param node [RuboCop::AST::Node] :class node
         # @return [void]
         def on_class(node)
           analyze_scope(node)
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#on_module+ -> void
-        #
         # Entry point for module scopes.
         #
-        # @param [RuboCop::AST::Node] node
+        # @param node [RuboCop::AST::Node] :module node
         # @return [void]
         def on_module(node)
           analyze_scope(node)
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#on_sclass+ -> void
-        #
         # Entry point for singleton class scopes (class << self).
         #
-        # @param [RuboCop::AST::Node] node
+        # @param node [RuboCop::AST::Node] :sclass node
         # @return [void]
         def on_sclass(node)
           analyze_scope(node)
@@ -93,14 +111,16 @@ module RuboCop
 
         private
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#analyze_scope+ -> void
+        # Collects defs in the current scope, builds caller→callee edges for local sends,
+        # locates the first backward edge (callee defined before caller), and registers
+        # an offense. If autocorrection is requested, attempts to reorder methods within
+        # the same visibility section.
         #
-        # Collects defs in the current scope, builds caller->callee edges
-        # for local sends, finds the first backward edge (callee defined before caller),
-        # and registers an offense. If autocorrection is requested, attempts to reorder
-        # methods within the same visibility section.
+        # - Direct edges are used for recursion checks (AllowedRecursion).
+        # - “Sibling” edges are added from orchestrator methods (not called by others)
+        #   to reflect the order of consecutive calls (foo then bar).
         #
-        # @param [RuboCop::AST::Node] scope_node
+        # @param scope_node [RuboCop::AST::Node] a :begin, :class, :module, or :sclass node
         # @return [void]
         def analyze_scope(scope_node)
           body_nodes = scope_body_nodes(scope_node)
@@ -109,44 +129,73 @@ module RuboCop
           def_nodes = body_nodes.select { |n| %i[def defs].include?(n.type) }
           return if def_nodes.size <= 1
 
-          names = def_nodes.map(&:method_name)
+          names     = def_nodes.map(&:method_name)
           names_set = names.to_set
-          index_of = names.each_with_index.to_h
+          index_of  = names.each_with_index.to_h
 
-          # Build complete call graph - find ALL method calls in ALL methods
-          edges = []
+          # Phase 1: direct call edges (caller -> callee)
+          direct_edges = def_nodes.flat_map do |def_node|
+            calls = local_calls(def_node, names_set)
+            calls.reject { |callee| callee == def_node.method_name }
+                 .map    { |callee| [def_node.method_name, callee] }
+          end
+
+          # Methods that are called by someone else in this scope
+          all_callees = direct_edges.to_set(&:last)
+
+          # Phase 2: sibling-order edges from orchestration methods
+          sibling_edges = []
           def_nodes.each do |def_node|
-            local_calls(def_node, names_set).each do |callee|
-              next if callee == def_node.method_name # self-recursion
+            next if all_callees.include?(def_node.method_name)
+
+            calls = local_calls(def_node, names_set)
+            calls.each_cons(2) do |a, b|
+              next if direct_edges.any? { |u, v| (u == a && v == b) || (u == b && v == a) }
 
-              edges << [def_node.method_name, callee]
+              sibling_edges << [a, b]
             end
           end
 
-          allow_recursion = cop_config.fetch('AllowedRecursion') { true }
-          adj = build_adj(names, edges)
+          # Phase 3: combine for sorting, but only use direct edges for recursion checks
+          edges_for_sort   = direct_edges + sibling_edges
+          allow_recursion  = cop_config.fetch('AllowedRecursion') { true }
+          adj_direct       = build_adj(names, direct_edges)
+
+          violation = first_backward_edge(direct_edges, index_of, adj_direct, allow_recursion)
+          violation_type = :direct if violation
+
+          unless violation
+            violation = first_backward_edge(sibling_edges, index_of, adj_direct, allow_recursion)
+            violation_type = :sibling if violation
+          end
 
-          violation = first_backward_edge(edges, index_of, adj, allow_recursion)
           return unless violation
 
           caller_name, callee_name = violation
           callee_node = def_nodes[index_of[callee_name]]
 
-          add_offense(callee_node,
-                      message: format(MSG, callee: "##{callee_name}", caller: "##{caller_name}")) do |corrector|
-            try_autocorrect(corrector, body_nodes, def_nodes, edges)
+          message =
+            if violation_type == :sibling
+              "Define ##{callee_name} after ##{caller_name} to match the order they are called together"
+            else
+              format(MSG, callee: "##{callee_name}", caller: "##{caller_name}")
+            end
+
+          add_offense(callee_node, message: message) do |corrector|
+            try_autocorrect(corrector, body_nodes, def_nodes, edges_for_sort, violation)
           end
 
-          # Recurse into nested scopes
-          body_nodes.each { |n| analyze_scope(n) if n.class_type? || n.module_type? || n.sclass_type? }
+          # Recurse into nested scopes inside this body
+          body_nodes.each do |n|
+            analyze_scope(n) if n.class_type? || n.module_type? || n.sclass_type?
+          end
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#scope_body_nodes+ -> Array<RuboCop::AST::Node>
-        #
         # Normalizes a scope node to its immediate "body" items we iterate over.
         #
-        # @param [RuboCop::AST::Node] node
-        # @return [Array<RuboCop::AST::Node>]
+        # @param node [RuboCop::AST::Node]
+        # @return [Array<RuboCop::AST::Node>] direct children inside this scope
+        # @api private
         def scope_body_nodes(node)
           case node.type
           when :begin
@@ -161,119 +210,140 @@ module RuboCop
           end
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#local_calls+ -> Array<Symbol>
-        #
-        # Returns the set of local method names (receiver is nil/self) invoked inside
-        # a given def node whose names exist in the provided name set.
-        #
-        # @param [RuboCop::AST::Node] def_node
-        # @param [Set<Symbol>] names_set
-        # @return [Array<Symbol>]
-        def local_calls(def_node, names_set)
-          body = def_node.body
-          return [] unless body
-
-          res = []
-          body.each_node(:send) do |send|
-            recv = send.receiver
-            next unless recv.nil? || recv&.self_type?
-
-            mname = send.method_name
-            res << mname if names_set.include?(mname)
-          end
-          res.uniq
-        end
-
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#try_autocorrect+ -> void
-        #
         # UNSAFE: Reorders method definitions inside the target visibility section only
         # (does not cross private/protected/public boundaries). Skips if defs are not
         # contiguous within the section or if a cycle prevents a consistent topo order.
         #
-        # @param [RuboCop::Cop::Corrector] corrector
-        # @param [Array<RuboCop::AST::Node>] body_nodes
-        # @param [Array<RuboCop::AST::Node>] def_nodes
-        # @param [Array<Array(Symbol, Symbol)>] edges
-        # @return [void]
+        # - Uses direct call edges for recursion checks.
+        # - If the violation is a direct-call violation, sorts using only direct edges
+        #   inside the section (so sibling edges cannot block the fix).
+        # - If the violation is a sibling-order violation, includes sibling edges.
+        # - Rewrites only the exact contiguous section (plus the visibility line if present).
+        # - Preserves leading doc comments for each method.
         #
-        # @note Applied only when user asked for autocorrections; with SafeAutoCorrect: false, this runs under -A.
-        # @note Also preserves contiguous leading doc comments above each method.
-        def try_autocorrect(corrector, body_nodes, def_nodes, edges)
-          # Group method definitions into visibility sections
+        # @param corrector [RuboCop::Cop::Corrector]
+        # @param body_nodes [Array<RuboCop::AST::Node>] raw nodes of the scope body
+        # @param def_nodes [Array<RuboCop::AST::Node>] all def/defs nodes in this body
+        # @param edges [Array<Array(Symbol, Symbol)>] direct + sibling edges for this scope
+        # @param initial_violation [Array<(Symbol, Symbol)>, nil] an already-found violating edge
+        # @return [void]
+        # @api private
+        def try_autocorrect(corrector, body_nodes, def_nodes, edges, initial_violation = nil)
           sections = extract_visibility_sections(body_nodes)
 
-          # Find the section that contains our violating methods
-          caller_name, callee_name = first_backward_edge(
-            edges,
-            def_nodes.map(&:method_name).each_with_index.to_h,
-            build_adj(def_nodes.map(&:method_name), edges),
-            cop_config.fetch('AllowedRecursion') { true }
-          )
+          names  = def_nodes.map(&:method_name)
+          idx_of = names.each_with_index.to_h
+          names_set = names.to_set
+
+          # Recompute direct edges; split edges back into direct vs sibling
+          direct_edges = def_nodes.flat_map do |def_node|
+            local_calls(def_node, names_set)
+              .reject { |callee| callee == def_node.method_name }
+              .map { |callee| [def_node.method_name, callee] }
+          end
+          sibling_edges = edges - direct_edges
+
+          # Recursion check uses only direct edges
+          allow_recursion = cop_config.fetch('AllowedRecursion') { true }
+          adj_direct = build_adj(names, direct_edges)
+
+          violation = initial_violation ||
+                      first_backward_edge(edges, idx_of, adj_direct, allow_recursion)
+          return unless violation
 
-          # No violation -> nothing to do
-          return unless caller_name && callee_name
+          caller_name, callee_name = violation
 
-          # Find a visibility section that contains both names
+          # Find the contiguous section containing both caller and callee
           target_section = sections.find do |section|
-            names_in_section = section[:defs].to_set(&:method_name)
-            names_in_section.include?(caller_name) && names_in_section.include?(callee_name)
+            section_names = section[:defs].map(&:method_name)
+            section_names.include?(caller_name) && section_names.include?(callee_name)
           end
-
-          # If violation spans multiple sections, skip autocorrect
           return unless target_section
 
           defs = target_section[:defs]
-          return unless defs.size > 1
+          return if defs.size <= 1
 
-          # Apply topological sort only within this visibility section
-          names = defs.map(&:method_name)
-          idx_of = names.each_with_index.to_h
+          section_names   = defs.map(&:method_name)
+          section_idx_of  = section_names.each_with_index.to_h
 
-          # Filter edges to only those within this section
-          section_names = names.to_set
-          section_edges = edges.select { |u, v| section_names.include?(u) && section_names.include?(v) }
+          # Is this a direct-call violation?
+          direct_violation = direct_edges.any? { |u, v| u == caller_name && v == callee_name }
 
-          sorted_names = topo_sort(names, section_edges, idx_of)
-          return unless sorted_names
+          # Restrict edges to this contiguous section
+          section_direct_edges  = direct_edges.select  { |u, v| section_names.include?(u) && section_names.include?(v) }
+          section_sibling_edges = sibling_edges.select { |u, v| section_names.include?(u) && section_names.include?(v) }
 
-          # Capture each def with its leading contiguous comment block
+          # Prune mutual-recursion edges inside the section if allowed
+          if allow_recursion
+            pair_set = section_direct_edges.to_set
+            section_direct_edges = section_direct_edges.reject { |u, v| pair_set.include?([v, u]) }
+          end
+
+          # Sorting edges: direct-only for direct violation, otherwise sibling + pruned direct
+          section_edges_for_sort =
+            if direct_violation
+              section_direct_edges
+            else
+              section_sibling_edges + section_direct_edges
+            end
+
+          sorted_names = topo_sort(section_names, section_edges_for_sort, section_idx_of)
+          return if sorted_names.nil? || sorted_names == section_names
+
+          # Rebuild section (preserve per-method leading docs)
           ranges_by_name = defs.to_h { |d| [d.method_name, range_with_leading_comments(d)] }
-          sorted_def_sources = sorted_names.map { |name| ranges_by_name[name].source }
+          sorted_def_sources = sorted_names.map { |n| ranges_by_name[n].source }
 
-          # Reconstruct the section: keep the visibility modifier (if any) above the first def
-          visibility_node = target_section[:visibility]
+          visibility_node   = target_section[:visibility]
           visibility_source = visibility_node&.source.to_s
 
-          new_content = if visibility_source.empty?
-                          sorted_def_sources.join("\n\n")
-                        else
-                          "#{visibility_source}\n\n#{sorted_def_sources.join("\n\n")}"
-                        end
+          new_content =
+            if visibility_source.empty?
+              sorted_def_sources.join("\n\n")
+            else
+              "#{visibility_source}\n\n#{sorted_def_sources.join("\n\n")}"
+            end
 
-          # Expand the replaced region:
-          # - if a visibility node exists, start from its begin_pos
-          # - otherwise, start from the earliest leading doc-comment of the defs
           section_begin =
             if visibility_node
               visibility_node.source_range.begin_pos
             else
               defs.map { |d| range_with_leading_comments(d).begin_pos }.min
             end
-
-          # Always end at the end of the last def
-          section_end = defs.last.source_range.end_pos
+          section_end = target_section[:end_pos]
 
           region = Parser::Source::Range.new(processed_source.buffer, section_begin, section_end)
           corrector.replace(region, new_content)
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#build_adj+ -> Hash{Symbol=>Array<Symbol>}
+        # Collects local calls (receiver is nil/self) from within a def node
+        # whose names are present in +names_set+.
         #
+        # @param def_node [RuboCop::AST::Node] :def or :defs
+        # @param names_set [Set<Symbol>] known local method names in this scope
+        # @return [Array<Symbol>] unique callee names
+        # @api private
+        def local_calls(def_node, names_set)
+          body = def_node.body
+          return [] unless body
+
+          res = []
+          body.each_node(:send) do |send|
+            recv = send.receiver
+            next unless recv.nil? || recv&.self_type?
+
+            mname = send.method_name
+            res << mname if names_set.include?(mname)
+          end
+          res.uniq
+        end
+
         # Builds an adjacency list for edges restricted to known names.
         #
-        # @param [Array<Symbol>] names
-        # @param [Array<Array(Symbol, Symbol)>] edges
-        # @return [Hash{Symbol=>Array<Symbol>}]
+        # @param names [Array<Symbol>] method names
+        # @param edges [Array<Array(Symbol, Symbol)>] caller→callee pairs
+        # @return [Hash{Symbol=>Array<Symbol>}] adjacency list
+        # @api private
         def build_adj(names, edges)
           allowed = names.to_set
           adj = Hash.new { |h, k| h[k] = [] }
@@ -286,16 +356,15 @@ module RuboCop
           adj
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#first_backward_edge+ -> [Symbol, Symbol], nil
-        #
-        # Returns the first backward edge found, optionally skipping mutual recursion
-        # if so configured.
+        # Returns the first backward edge found, optionally skipping edges
+        # that participate in mutual recursion (when AllowedRecursion is true).
         #
-        # @param [Array<Array(Symbol, Symbol)>] edges
-        # @param [Hash{Symbol=>Integer}] index_of
-        # @param [Hash{Symbol=>Array<Symbol>}] adj
-        # @param [Boolean] allow_recursion whether to ignore cycles
-        # @return [[Symbol, Symbol], nil]
+        # @param edges [Array<Array(Symbol, Symbol)>] candidate edges to check
+        # @param index_of [Hash{Symbol=>Integer}] current definition order (name -> index)
+        # @param adj [Hash{Symbol=>Array<Symbol>}] direct-call adjacency for path checks
+        # @param allow_recursion [Boolean] whether mutual recursion suppresses a violation
+        # @return [(Symbol, Symbol), nil] the violating (caller, callee) or nil
+        # @api private
         def first_backward_edge(edges, index_of, adj, allow_recursion)
           edges.find do |caller, callee|
             next unless index_of.key?(caller) && index_of.key?(callee)
@@ -307,15 +376,14 @@ module RuboCop
           end
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#path_exists?+ -> Boolean
-        #
-        # Tests whether a path exists in the adjacency graph from +src+ to +dst+ (BFS).
+        # Breadth-first search to detect if a path exists in the direct-call graph.
         #
-        # @param [Symbol] src
-        # @param [Symbol] dst
-        # @param [Hash{Symbol=>Array<Symbol>}] adj
-        # @param [Integer] limit traversal step limit (guard)
-        # @return [Boolean]
+        # @param src [Symbol] source method
+        # @param dst [Symbol] destination method
+        # @param adj [Hash{Symbol=>Array<Symbol>}] adjacency list
+        # @param limit [Integer] traversal safety limit
+        # @return [Boolean] true if a path exists
+        # @api private
         def path_exists?(src, dst, adj, limit = 200)
           return true if src == dst
 
@@ -337,17 +405,20 @@ module RuboCop
           false
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#extract_visibility_sections+ -> Array<Hash>
+        # Splits the scope body into contiguous sections of def/defs grouped
+        # by the visibility modifier immediately preceding them (private/protected/public).
         #
-        # Splits the body into contiguous sections of defs grouped by visibility modifier
-        # (private/protected/public). Returns metadata for each section including:
-        #   :visibility  -> visibility modifier node or nil
-        #   :defs        -> array of def/defs nodes
-        #   :start_pos   -> Integer (begin_pos)
-        #   :end_pos     -> Integer (end_pos)
+        # A section is represented as a Hash with:
+        # - :visibility [RuboCop::AST::Node, nil] the bare visibility send, or nil
+        # - :defs [Array<RuboCop::AST::Node>] contiguous def/defs nodes
+        # - :start_pos [Integer] begin_pos of the first def in the section
+        # - :end_pos [Integer] end_pos of the last def in the section
         #
-        # @param [Array<RuboCop::AST::Node>] body_nodes
-        # @return [Array<Hash{Symbol=>untyped}>]
+        # Non-visibility sends, constants, and nested scopes break contiguity.
+        #
+        # @param body_nodes [Array<RuboCop::AST::Node>] raw nodes in the scope body
+        # @return [Array<Hash>] list of sections metadata
+        # @api private
         def extract_visibility_sections(body_nodes)
           sections = []
           current_visibility = nil
@@ -359,37 +430,30 @@ module RuboCop
             when :def, :defs
               current_defs << node
               section_start ||= node.source_range.begin_pos
+
             when :send
-              # Check if this is a visibility modifier (private/protected/public)
+              # Close any running section before processing visibility/non-visibility send
+              unless current_defs.empty?
+                sections << {
+                  visibility: current_visibility,
+                  defs: current_defs.dup,
+                  start_pos: section_start,
+                  end_pos: body_nodes[idx - 1].source_range.end_pos
+                }
+                current_defs = []
+                section_start = nil
+              end
+
+              # Bare visibility modifiers: private/protected/public without args
               if node.receiver.nil? && %i[private protected public].include?(node.method_name) && node.arguments.empty?
-                # End current section if it has defs
-                unless current_defs.empty?
-                  sections << {
-                    visibility: current_visibility,
-                    defs: current_defs.dup,
-                    start_pos: section_start,
-                    end_pos: body_nodes[idx - 1].source_range.end_pos
-                  }
-                  current_defs = []
-                  section_start = nil
-                end
                 current_visibility = node
               else
-                # Non-visibility send - breaks contiguity
-                unless current_defs.empty?
-                  sections << {
-                    visibility: current_visibility,
-                    defs: current_defs.dup,
-                    start_pos: section_start,
-                    end_pos: body_nodes[idx - 1].source_range.end_pos
-                  }
-                  current_defs = []
-                  section_start = nil
-                  current_visibility = nil
-                end
+                # Non-visibility send breaks contiguity and resets visibility context
+                current_visibility = nil
               end
+
             else
-              # Any other node type breaks contiguity
+              # Any other node breaks contiguity and resets visibility context
               unless current_defs.empty?
                 sections << {
                   visibility: current_visibility,
@@ -399,12 +463,12 @@ module RuboCop
                 }
                 current_defs = []
                 section_start = nil
-                current_visibility = nil
               end
+              current_visibility = nil
             end
           end
 
-          # Handle trailing defs
+          # trailing defs
           unless current_defs.empty?
             sections << {
               visibility: current_visibility,
@@ -417,14 +481,13 @@ module RuboCop
           sections
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#topo_sort+ -> Array<Symbol>, nil
-        #
-        # Performs a stable topological sort using current order as a tie-breaker.
+        # Stable topological sort using the current order as a tie-breaker.
         #
-        # @param [Array<Symbol>] names
-        # @param [Array<Array(Symbol, Symbol)>] edges
-        # @param [Hash{Symbol=>Integer}] idx_of
+        # @param names [Array<Symbol>] names to sort
+        # @param edges [Array<Array(Symbol, Symbol)>] caller→callee edges to respect
+        # @param idx_of [Hash{Symbol=>Integer}] current order (name -> index)
         # @return [Array<Symbol>, nil] sorted names or nil if a cycle prevents a full order
+        # @api private
         def topo_sort(names, edges, idx_of)
           indegree = Hash.new(0)
           adj = Hash.new { |h, k| h[k] = [] }
@@ -457,14 +520,13 @@ module RuboCop
           result
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#range_with_leading_comments+ -> Parser::Source::Range
-        #
         # Returns a range that starts at the first contiguous comment line immediately
-        # above the def/defs node, and ends at the end of the def. This preserves
+        # above the def/defs node and ends at the end of the def. This preserves
         # YARD/RDoc doc comments when methods are moved during autocorrect.
         #
-        # @param [RuboCop::AST::Node] node The def/defs node.
-        # @return [Parser::Source::Range] Range covering leading comments + method body.
+        # @param node [RuboCop::AST::Node] :def or :defs to capture with leading comments
+        # @return [Parser::Source::Range]
+        # @api private
         def range_with_leading_comments(node)
           buffer = processed_source.buffer
           expr = node.source_range

data/lib/rubocop/sorted_methods_by_call/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module SortedMethodsByCall
-    VERSION = '1.1.0'
+    VERSION = '1.1.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-sorted_methods_by_call
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
 - unurgunite