rubocop-sorted_methods_by_call 1.2.2 → 1.2.3

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

@@ -89,37 +89,33 @@ module RuboCop
         MSG_SIBLING_CYCLE_NOTE =
           '%<base>s (Possible sibling cycle detected; autocorrect may be skipped.)'
 
-        # Entry point for root :begin nodes (top-level).
+        # Entry point for top-level `:begin` scopes; delegates to `analyze_scope`.
         #
-        # 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 node [RuboCop::AST::Node] root :begin node
+        # @param [RuboCop::AST::Node] node The `:begin` AST node representing the top-level scope.
         # @return [void]
         def on_begin(node)
           analyze_scope(node)
         end
 
-        # Entry point for class scopes.
+        # Entry point for `:class` scopes; delegates to `analyze_scope`.
         #
-        # @param node [RuboCop::AST::Node] :class node
+        # @param [RuboCop::AST::Node] node The `:class` AST node to analyze.
         # @return [void]
         def on_class(node)
           analyze_scope(node)
         end
 
-        # Entry point for module scopes.
+        # Entry point for `:module` scopes; delegates to `analyze_scope`.
         #
-        # @param node [RuboCop::AST::Node] :module node
+        # @param [RuboCop::AST::Node] node The `:module` AST node to analyze.
         # @return [void]
         def on_module(node)
           analyze_scope(node)
         end
 
-        # Entry point for singleton class scopes (class << self).
+        # Entry point for singleton class (`class << self`) scopes; delegates to `analyze_scope`.
         #
-        # @param node [RuboCop::AST::Node] :sclass node
+        # @param [RuboCop::AST::Node] node The `:sclass` AST node to analyze.
         # @return [void]
         def on_sclass(node)
           analyze_scope(node)
@@ -127,58 +123,70 @@ module RuboCop
 
         private
 
-        # Analyze a single scope node (:begin, :class, :module, :sclass):
-        # - Collect method defs in the scope body
-        # - Build direct call edges (caller → callee)
-        # - Optionally build sibling-order edges ("called together")
-        # - Find the first ordering violation and register an offense
-        # - Attempt autocorrect (under -A) within a contiguous visibility section
-        # - Recurse into nested scopes inside the body
+        # Analyze a scope node for waterfall ordering violations and recurse into nested scopes.
         #
-        # @param scope_node [RuboCop::AST::Node] a :begin, :class, :module, or :sclass node
+        # @private
+        # @param [RuboCop::AST::Node] scope_node The scope node (begin/class/module/sclass) to analyze.
         # @return [void]
-        # @api private
         def analyze_scope(scope_node)
-          body_nodes = scope_body_nodes(scope_node)
-          return if body_nodes.empty?
-
-          def_nodes = method_def_nodes(body_nodes)
-          return if def_nodes.size <= 1
+          data = scope_data(scope_node)
+          return unless data
 
-          names, names_set, index_of = method_name_index(def_nodes)
+          register_violation(data) if data[:edge]
+          analyze_nested_scopes(data[:body])
+        end
 
-          direct_edges = build_direct_edges(def_nodes, names_set)
-          sibling_edges = build_sibling_edges(def_nodes, names_set, direct_edges, names)
+        # Build a data hash with method definitions, edges, and the first violation (if any) for a scope.
+        #
+        # @private
+        # @param [RuboCop::AST::Node] scope_node The scope node to extract data from.
+        # @return [RuboCop::Cop::SortedMethodsByCall::Waterfall::data?]
+        def scope_data(scope_node)
+          body = scope_body_nodes(scope_node)
+          defs = method_def_nodes(body) if body.any?
+          return unless defs && defs.size > 1
 
-          edges_for_sort = direct_edges + sibling_edges
-          adj_direct = build_adj(names, direct_edges)
+          names, name_set, idx = method_name_index(defs)
+          direct = build_direct_edges(defs, name_set)
+          sibling = build_sibling_edges(defs, name_set, direct, names)
+          adj = build_adj(names, direct)
 
-          violation_type, violation = find_violation(direct_edges, sibling_edges, index_of, adj_direct)
-          if violation
-            _, callee_name = violation
-            callee_node = def_nodes[index_of.fetch(callee_name)]
+          type, edge = find_violation(direct, sibling, idx, adj)
 
-            message = build_offense_message(
-              violation_type: violation_type,
-              violation: violation,
-              names: names,
-              edges_for_sort: edges_for_sort,
-              body_nodes: body_nodes
-            )
+          { body: body, idx: idx, defs: defs, names: names, edges: direct + sibling,
+            type: type, edge: edge }
+        end
 
-            add_offense(callee_node, message: message) do |corrector|
-              try_autocorrect(corrector, body_nodes, def_nodes, edges_for_sort, violation)
-            end
+        # Register an offense for the given violation data.
+        #
+        # @private
+        # @param [RuboCop::Cop::SortedMethodsByCall::Waterfall::data] data The scope data hash containing violation and method information.
+        # @return [void]
+        def register_violation(data)
+          _, callee = data[:edge]
+          add_offense(data[:defs][data[:idx].fetch(callee)], message: build_offense_message(
+            violation_type: data[:type], violation: data[:edge], names: data[:names],
+            edges_for_sort: data[:edges], body_nodes: data[:body]
+          )) do |corrector|
+            auto_correct_violation(corrector, data)
           end
+        end
 
-          analyze_nested_scopes(body_nodes)
+        # Delegate autocorrection to `try_autocorrect` with violation data.
+        #
+        # @private
+        # @param [RuboCop::Cop::Corrector] corrector The RuboCop corrector object used to apply corrections.
+        # @param [RuboCop::Cop::SortedMethodsByCall::Waterfall::data] data The scope data hash containing edges and violation info.
+        # @return [void]
+        def auto_correct_violation(corrector, data)
+          try_autocorrect(corrector, data[:body], data[:defs], data[:edges], data[:edge])
         end
 
-        # Return the direct "body statements" inside a scope node.
+        # Extract direct child nodes from a scope node's body.
         #
-        # @param node [RuboCop::AST::Node]
-        # @return [Array<RuboCop::AST::Node>] direct children inside the scope body
-        # @api private
+        # @private
+        # @param [Object] node The scope node whose body children to extract.
+        # @return [Array<RuboCop::AST::Node>]
         def scope_body_nodes(node)
           case node.type
           when :begin
@@ -193,31 +201,33 @@ module RuboCop
           end
         end
 
-        # Select only method definition nodes from a scope body.
+        # Filter body nodes to only `:def`/`:defs` (method definition) nodes.
         #
-        # @param body_nodes [Array<RuboCop::AST::Node>]
-        # @return [Array<RuboCop::AST::Node>] :def/:defs nodes
-        # @api private
+        # @private
+        # @param [Array<RuboCop::AST::Node>] body_nodes Array of child nodes from a scope body.
+        # @return [Array<RuboCop::AST::DefNode>]
         def method_def_nodes(body_nodes)
-          body_nodes.select { |n| %i[def defs].include?(n.type) }
+          # rubocop:disable Layout/LeadingCommentSpace
+          body_nodes.select { |n| %i[def defs].include?(n.type) } #: Array[::RuboCop::AST::DefNode]
+          # rubocop:enable Layout/LeadingCommentSpace
         end
 
-        # Compute helper structures for method names in this scope.
+        # Build index structures: array of names, set of names, and name-to-position hash.
         #
-        # @param def_nodes [Array<RuboCop::AST::Node>]
-        # @return [Array<(Array<Symbol>, Set<Symbol>, Hash{Symbol=>Integer})>]
-        # @api private
+        # @private
+        # @param [Array<RuboCop::AST::DefNode>] def_nodes Array of method definition nodes to index.
+        # @return [[ ::Array[::Symbol], ::Set[::Symbol], ::Hash[::Symbol, ::Integer] ]]
         def method_name_index(def_nodes)
           names = def_nodes.map(&:method_name)
           [names, names.to_set, names.each_with_index.to_h]
         end
 
-        # Build direct call edges (caller -> callee) for local calls within each method body.
+        # Build direct call edges from each method definition to its local callees.
         #
-        # @param def_nodes [Array<RuboCop::AST::Node>]
-        # @param names_set [Set<Symbol>]
-        # @return [Array<Array(Symbol, Symbol)>]
-        # @api private
+        # @private
+        # @param [Array<RuboCop::AST::DefNode>] def_nodes Array of method definition nodes to analyze.
+        # @param [Set<Symbol>] names_set Set of known method names within the current scope.
+        # @return [Array<[ ::Symbol, ::Symbol ]>]
         def build_direct_edges(def_nodes, names_set)
           def_nodes.flat_map do |def_node|
             local_calls(def_node, names_set)
@@ -226,53 +236,56 @@ module RuboCop
           end
         end
 
-        # Build sibling-order edges (a -> b) for consecutive calls inside orchestration methods.
+        # Build sibling call-order edges for orchestration methods.
         #
-        # Orchestration methods are those not called by any other method in this scope.
-        #
-        # @param def_nodes [Array<RuboCop::AST::Node>]
-        # @param names_set [Set<Symbol>]
-        # @param direct_edges [Array<Array(Symbol, Symbol)>]
-        # @param names [Array<Symbol>]
-        # @return [Array<Array(Symbol, Symbol)>]
-        # @api private
+        # @private
+        # @param [Array<RuboCop::AST::DefNode>] def_nodes Array of method definition nodes to analyze.
+        # @param [Set<Symbol>] names_set Set of known method names within the current scope.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] direct_edges Previously computed direct call edges.
+        # @param [Array<Symbol>] names Ordered array of method names in the current scope.
+        # @return [Array<[ ::Symbol, ::Symbol ]>]
         def build_sibling_edges(def_nodes, names_set, direct_edges, names)
           all_callees = direct_edges.to_set(&:last)
           direct_pair_set = direct_edges.to_set
-
-          skip_cyclic_siblings = skip_cyclic_sibling_edges?
           adj_for_siblings = build_adj(names, direct_edges)
 
-          sibling_edges = []
-
-          def_nodes.each do |def_node|
+          def_nodes.each_with_object([]) do |def_node, sibling_edges|
             next if all_callees.include?(def_node.method_name)
 
-            calls = local_calls(def_node, names_set)
-            calls.each_cons(2) do |a, b|
-              # If there is already a direct relationship between a and b (either direction),
-              # do not add a sibling-order edge.
-              next if direct_pair_set.include?([a, b]) || direct_pair_set.include?([b, a])
-
-              # Optional: do not add a sibling edge that would introduce a cycle.
-              next if skip_cyclic_siblings && path_exists?(b, a, adj_for_siblings)
-
-              sibling_edges << [a, b]
-              adj_for_siblings[a] << b unless adj_for_siblings[a].include?(b)
-            end
+            sibling_edges.concat(sibling_edges_for_method(def_node, names_set, direct_pair_set, adj_for_siblings))
           end
+        end
 
-          sibling_edges
+        # Generate sibling edges for consecutive calls within a single method body.
+        #
+        # @private
+        # @param [RuboCop::AST::DefNode] def_node The method definition node whose body to scan for consecutive calls.
+        # @param [Set<Symbol>] names_set Set of known method names within the current scope.
+        # @param [Set<[ ::Symbol, ::Symbol ]>] direct_pair_set Set of existing direct call pairs to avoid duplicating.
+        # @param [Hash<Symbol, Array<Symbol>>] adj_for_siblings Adjacency map of existing edges for cycle detection.
+        # @return [Array<[ ::Symbol, ::Symbol ]>]
+        def sibling_edges_for_method(def_node, names_set, direct_pair_set, adj_for_siblings)
+          calls = local_calls(def_node, names_set)
+          calls.each_cons(2).filter_map do |a, b|
+            # @type var a: Symbol
+            # @type var b: Symbol
+
+            next if direct_pair_set.include?([a, b]) || direct_pair_set.include?([b, a])
+            next if skip_cyclic_sibling_edges? && path_exists?(b, a, adj_for_siblings)
+
+            adj_for_siblings[a] << b unless adj_for_siblings[a].include?(b)
+            [a, b]
+          end
         end
 
-        # Find the first ordering violation. Checks direct edges first, then sibling edges.
+        # Find the first backward edge in direct or sibling edges (waterfall order violation).
         #
-        # @param direct_edges [Array<Array(Symbol, Symbol)>]
-        # @param sibling_edges [Array<Array(Symbol, Symbol)>]
-        # @param index_of [Hash{Symbol=>Integer}]
-        # @param adj_direct [Hash{Symbol=>Array<Symbol>}] adjacency list for direct edges
-        # @return [Array<(Symbol, Array(Symbol, Symbol))>, Array<(nil, nil)>]
-        # @api private
+        # @private
+        # @param [Array<[ ::Symbol, ::Symbol ]>] direct_edges Direct call edges to check for violations.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] sibling_edges Sibling call-order edges to check for violations.
+        # @param [Hash<Symbol, Integer>] index_of Map from method names to their definition position index.
+        # @param [Hash<Symbol, Array<Symbol>>] adj_direct Adjacency map of direct edges for recursion cycle detection.
+        # @return [[ ::Symbol, [ ::Symbol, ::Symbol ]? ]?]
         def find_violation(direct_edges, sibling_edges, index_of, adj_direct)
           allow_recursion = allowed_recursion?
 
@@ -282,18 +295,17 @@ module RuboCop
           violation = first_backward_edge(sibling_edges, index_of, adj_direct, allow_recursion)
           return [:sibling, violation] if violation
 
-          [nil, nil]
+          nil
         end
 
-        # Return the first backward edge found, optionally skipping edges that participate
-        # in recursion/cycles detectable in the direct-call graph (AllowedRecursion).
+        # Find the first edge where callee is defined before caller, optionally skipping recursive cycles.
         #
-        # @param edges [Array<Array(Symbol, Symbol)>]
-        # @param index_of [Hash{Symbol=>Integer}]
-        # @param adj_direct [Hash{Symbol=>Array<Symbol>}] direct-call adjacency for path checks
-        # @param allow_recursion [Boolean]
-        # @return [Array(Symbol, Symbol), nil]
-        # @api private
+        # @private
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges Edges to search for backward ordering.
+        # @param [Hash<Symbol, Integer>] index_of Map from method names to their definition position index.
+        # @param [Hash<Symbol, Array<Symbol>>] adj_direct Adjacency map for recursion cycle detection.
+        # @param [Boolean] allow_recursion Whether to skip edges that are part of a recursive call cycle.
+        # @return [[ ::Symbol, ::Symbol ]?]
         def first_backward_edge(edges, index_of, adj_direct, allow_recursion)
           edges.find do |caller, callee|
             next unless index_of.key?(caller) && index_of.key?(callee)
@@ -303,30 +315,31 @@ module RuboCop
           end
         end
 
-        # Construct the final offense message, including optional notes:
-        # - sibling cycle note (for sibling violations)
-        # - cross-visibility note (public/private/protected boundary)
+        # Build a full offense message with optional sibling-cycle and cross-visibility notes.
         #
-        # @param violation_type [Symbol] :direct or :sibling
-        # @param violation [Array(Symbol, Symbol)] (caller_name, callee_name)
-        # @param names [Array<Symbol>]
-        # @param edges_for_sort [Array<Array(Symbol, Symbol)>]
-        # @param body_nodes [Array<RuboCop::AST::Node>]
+        # @private
+        # @param [Symbol] violation_type Either `:direct` or `:sibling` indicating the violation kind.
+        # @param [[ ::Symbol, ::Symbol ]] violation The violating edge as a `[caller, callee]` pair.
+        # @param [Array<Symbol>] names Ordered array of method names for adjacency construction.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges_for_sort All edges in the scope used for building the full adjacency graph.
+        # @param [Array<RuboCop::AST::Node>] body_nodes Body nodes of the scope for cross-visibility detection.
         # @return [String]
-        # @api private
         def build_offense_message(violation_type:, violation:, names:, edges_for_sort:, body_nodes:)
           caller_name, callee_name = violation
 
           base = base_message_for(violation_type, caller_name, callee_name)
-          base = add_sibling_cycle_note_if_needed(base, violation_type, caller_name, callee_name, names, edges_for_sort)
+          adj_all = build_adj(names, edges_for_sort)
+          base = add_sibling_cycle_note_if_needed(base, violation_type, caller_name, callee_name, adj_all)
           add_cross_visibility_note_if_needed(base, body_nodes, caller_name, callee_name)
         end
 
-        # @param violation_type [Symbol]
-        # @param caller_name [Symbol]
-        # @param callee_name [Symbol]
+        # Return the base offense message template for a direct or sibling violation.
+        #
+        # @private
+        # @param [Symbol] violation_type Either `:direct` or `:sibling`.
+        # @param [Symbol] caller_name Name of the method that calls another.
+        # @param [Symbol] callee_name Name of the method being called.
         # @return [String]
-        # @api private
         def base_message_for(violation_type, caller_name, callee_name)
           if violation_type == :sibling
             format(SIBLING_MSG, callee: "##{callee_name}", caller: "##{caller_name}")
@@ -335,21 +348,18 @@ module RuboCop
           end
         end
 
-        # Add a note when a sibling-order edge is part of a cycle in the combined graph.
+        # Append a sibling-cycle warning note if applicable.
         #
-        # @param base_message [String]
-        # @param violation_type [Symbol]
-        # @param caller_name [Symbol]
-        # @param callee_name [Symbol]
-        # @param names [Array<Symbol>]
-        # @param edges_for_sort [Array<Array(Symbol, Symbol)>]
+        # @private
+        # @param [String] base_message The base offense message to potentially annotate.
+        # @param [Symbol] violation_type Either `:direct` or `:sibling`.
+        # @param [Symbol] caller_name Name of the caller method.
+        # @param [Symbol] callee_name Name of the callee method.
+        # @param [Hash<Symbol, Array<Symbol>>] adj_all Full adjacency map for cycle detection.
         # @return [String]
-        # @api private
-        def add_sibling_cycle_note_if_needed(base_message, violation_type, caller_name, callee_name, names,
-                                             edges_for_sort)
+        def add_sibling_cycle_note_if_needed(base_message, violation_type, caller_name, callee_name, adj_all)
           return base_message unless violation_type == :sibling
 
-          adj_all = build_adj(names, edges_for_sort)
           if path_exists?(callee_name, caller_name, adj_all)
             format(MSG_SIBLING_CYCLE_NOTE, base: base_message)
           else
@@ -357,128 +367,168 @@ module RuboCop
           end
         end
 
-        # Add a note when the violation crosses visibility boundaries.
+        # Append a cross-visibility note if caller and callee are in different visibility sections.
         #
-        # @param base_message [String]
-        # @param body_nodes [Array<RuboCop::AST::Node>]
-        # @param caller_name [Symbol]
-        # @param callee_name [Symbol]
+        # @private
+        # @param [String] base_message The base offense message to potentially annotate.
+        # @param [Array<RuboCop::AST::Node>] body_nodes Body nodes of the scope for visibility section extraction.
+        # @param [Symbol] caller_name Name of the caller method.
+        # @param [Symbol] callee_name Name of the callee method.
         # @return [String]
-        # @api private
         def add_cross_visibility_note_if_needed(base_message, body_nodes, caller_name, callee_name)
           sections = extract_visibility_sections(body_nodes)
-          caller_section = section_for_method(sections, caller_name)
-          callee_section = section_for_method(sections, callee_name)
-
-          caller_vis = visibility_label(caller_section)
-          callee_vis = visibility_label(callee_section)
-
-          if caller_section && callee_section && caller_vis != callee_vis
-            format(
-              MSG_CROSS_VISIBILITY_NOTE,
-              base: base_message,
-              caller_visibility: caller_vis,
-              callee_visibility: callee_vis
-            )
-          else
-            base_message
-          end
+          caller_vis = visibility_label(section_for_method(sections, caller_name))
+          callee_vis = visibility_label(section_for_method(sections, callee_name))
+
+          return base_message unless caller_vis != callee_vis
+
+          format(MSG_CROSS_VISIBILITY_NOTE,
+                 base: base_message,
+                 caller_visibility: caller_vis,
+                 callee_visibility: callee_vis)
         end
 
-        # UNSAFE autocorrect: reorder method definitions inside one contiguous visibility section only.
+        # Attempt to autocorrect a violation by reordering methods within their visibility section.
         #
-        # This method intentionally does NOT reorder across:
-        # - `private/protected/public` boundaries
-        # - nested scopes
-        # - non-visibility statements that break contiguity
-        #
-        # @param corrector [RuboCop::Cop::Corrector]
-        # @param body_nodes [Array<RuboCop::AST::Node>]
-        # @param def_nodes [Array<RuboCop::AST::Node>]
-        # @param edges [Array<Array(Symbol, Symbol)>] direct + sibling edges for this scope
-        # @param initial_violation [Array(Symbol, Symbol), nil]
+        # @private
+        # @param [RuboCop::Cop::Corrector] corrector The RuboCop corrector object used to apply corrections.
+        # @param [Array<RuboCop::AST::Node>] body_nodes Body nodes of the scope for visibility section extraction.
+        # @param [Array<RuboCop::AST::DefNode>] def_nodes All method definition nodes in the scope.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges All edges (direct + sibling) for the scope.
+        # @param [[ ::Symbol, ::Symbol ]?] initial_violation The specific violating edge to autocorrect, or nil to auto-detect.
         # @return [void]
-        # @api private
         def try_autocorrect(corrector, body_nodes, def_nodes, edges, initial_violation = nil)
-          sections = extract_visibility_sections(body_nodes)
+          data = auto_correct_data(def_nodes, edges, initial_violation) or return
+          target = section_containing(extract_visibility_sections(body_nodes), *data[:violation])
+          return unless target && target[:defs].size > 1
 
-          names     = def_nodes.map(&:method_name)
-          names_set = names.to_set
-          idx_of    = names.each_with_index.to_h
+          sorted = correction_order(target[:defs], data, data[:violation])
+          return unless sorted
 
-          # Recompute direct edges; split edges back into direct vs sibling
-          direct_edges = build_direct_edges(def_nodes, names_set)
-          sibling_edges = edges - direct_edges
-
-          allow_recursion = allowed_recursion?
-          adj_direct = build_adj(names, direct_edges)
-
-          violation = initial_violation || first_backward_edge(edges, idx_of, adj_direct, allow_recursion)
-          return unless violation
+          replace_sorted_section(corrector, target[:defs], sorted)
+        end
 
+        # Compute the corrected method order via topological sort; returns nil if already correct.
+        #
+        # @private
+        # @param [Array<RuboCop::AST::DefNode>] defs Method definition nodes in the target visibility section.
+        # @param [RuboCop::Cop::SortedMethodsByCall::Waterfall::data] data Autocorrect data hash with direct, sibling edges, and violation.
+        # @param [[ ::Symbol, ::Symbol ]] violation The violating `[caller, callee]` pair to resolve.
+        # @return [Array<Symbol>?]
+        def correction_order(defs, data, violation)
+          names = defs.map(&:method_name)
           caller_name, callee_name = violation
+          result = topo_sort(names, edges_for_section(data, names, caller_name, callee_name),
+                             names.each_with_index.to_h)
+          result == names ? nil : result
+        end
 
-          target_section = sections.find do |section|
-            section_names = section[:defs].map(&:method_name)
-            section_names.include?(caller_name) && section_names.include?(callee_name)
-          end
-          return unless target_section
+        # Build data for autocorrection, recomputing direct edges and finding the violation.
+        #
+        # @private
+        # @param [Array<RuboCop::AST::DefNode>] def_nodes All method definition nodes in the scope.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges All edges (direct + sibling) for the scope.
+        # @param [[ ::Symbol, ::Symbol ]?] initial_violation The specific violating edge, or nil to auto-detect.
+        # @return [RuboCop::Cop::SortedMethodsByCall::Waterfall::data?]
+        def auto_correct_data(def_nodes, edges, initial_violation)
+          names = def_nodes.map(&:method_name)
+          name_set = names.to_set
+          direct = build_direct_edges(def_nodes, name_set)
+          adj = build_adj(names, direct)
+          violation = initial_violation || first_backward_edge(
+            edges, names.each_with_index.to_h, adj, allowed_recursion?
+          )
+          return unless violation
 
-          defs = target_section[:defs]
-          return if defs.size <= 1
+          { direct: direct, sibling: edges - direct, violation: violation }
+        end
 
-          section_names  = defs.map(&:method_name)
-          section_idx_of = section_names.each_with_index.to_h
+        # Filter edges to those relevant to a given visibility section and violation.
+        #
+        # @private
+        # @param [RuboCop::Cop::SortedMethodsByCall::Waterfall::data] data Autocorrect data hash with direct and sibling edge lists.
+        # @param [Array<Symbol>] section_names Method names in the target visibility section.
+        # @param [Symbol] caller_name Name of the caller method in the violation.
+        # @param [Symbol] callee_name Name of the callee method in the violation.
+        # @return [Array<[ ::Symbol, ::Symbol ]>]
+        def edges_for_section(data, section_names, caller_name, callee_name)
+          direct = filter_names(data[:direct], section_names)
+          sibling = filter_names(data[:sibling], section_names)
+          direct = reject_reciprocal(direct) if allowed_recursion?
+          data[:direct].any? { |u, v| u == caller_name && v == callee_name } ? direct : sibling + direct
+        end
 
-          direct_violation = direct_edges.any? { |u, v| u == caller_name && v == callee_name }
+        # Filter edges to only those whose both endpoints are in the given name list.
+        #
+        # @private
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges Edges to filter.
+        # @param [Array<Symbol>] names Allowed method names; only edges between these names are kept.
+        # @return [Array<[ ::Symbol, ::Symbol ]>]
+        def filter_names(edges, names)
+          edges.select { |u, v| names.include?(u) && names.include?(v) }
+        end
 
-          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) }
+        # Remove pairs of reciprocal edges (a→b, b→a) from the edge list.
+        #
+        # @private
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges Edges to filter reciprocal pairs from.
+        # @return [Array<[ ::Symbol, ::Symbol ]>]
+        def reject_reciprocal(edges)
+          pair_set = edges.to_set
+          edges.reject { |u, v| pair_set.include?([v, u]) }
+        end
 
-          if allow_recursion
-            pair_set = section_direct_edges.to_set
-            section_direct_edges = section_direct_edges.reject { |u, v| pair_set.include?([v, u]) }
+        # Find the visibility section that contains all given method names.
+        #
+        # @private
+        # @param [Array<RuboCop::Cop::SortedMethodsByCall::Waterfall::section>] sections Visibility sections to search through.
+        # @param [Array<Symbol>] method_names Method names to locate within a single section.
+        # @return [RuboCop::Cop::SortedMethodsByCall::Waterfall::section?]
+        def section_containing(sections, *method_names)
+          sections.find do |section|
+            section_names = section[:defs].map(&:method_name)
+            method_names.all? { |name| section_names.include?(name) }
           end
+        end
 
-          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
-
-          ranges_by_name = defs.to_h { |d| [d.method_name, range_with_leading_comments(d)] }
-          sorted_def_sources = sorted_names.map { |n| ranges_by_name.fetch(n).source }
-
-          # IMPORTANT: only rewrite the contiguous def/defs block itself.
-          # Do NOT include the visibility line (private/protected/public) in the rewritten region,
-          # otherwise non-method statements between the visibility modifier and the first `def`
-          # (e.g., `helper_method :x`) can be deleted. See issue #10.
-          new_content = sorted_def_sources.join("\n\n")
-
-          section_begin = defs.map { |d| ranges_by_name.fetch(d.method_name).begin_pos }.min
-          section_end   = defs.map { |d| ranges_by_name.fetch(d.method_name).end_pos }.max
+        # Replace the source code of a section of method definitions with the new sorted order.
+        #
+        # @private
+        # @param [RuboCop::Cop::Corrector] corrector The RuboCop corrector object used to apply corrections.
+        # @param [Array<RuboCop::AST::DefNode>] defs Method definition nodes in the section being reordered.
+        # @param [Array<Symbol>] sorted_names Method names in their corrected order.
+        # @return [void]
+        def replace_sorted_section(corrector, defs, sorted_names)
+          ranges = defs.to_h { |d| [d.method_name, range_with_leading_comments(d)] }
+          content = sorted_names.map { |n| ranges.fetch(n).source }.join("\n\n")
+          corrector.replace(bounds(ranges, defs), content)
+        end
 
-          region = range_between(section_begin, section_end)
-          corrector.replace(region, new_content)
+        # Compute a source range spanning all given method definitions by their stored ranges.
+        #
+        # @private
+        # @param [Hash<Symbol, Object>] ranges Hash mapping method names to their source ranges (including leading comments).
+        # @param [Array<RuboCop::AST::DefNode>] defs Method definition nodes whose span to compute.
+        # @return [Parser::Source::Range]
+        def bounds(ranges, defs)
+          range_between(defs.map { |d| ranges.fetch(d.method_name).begin_pos }.min,
+                        defs.map { |d| ranges.fetch(d.method_name).end_pos }.max)
         end
 
-        # Collect local method calls (receiver is nil/self) from within a def node,
-        # restricted to known method names in this scope.
+        # Collect local method calls (no receiver or self) within a method body that match known names.
         #
-        # @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
+        # @private
+        # @param [RuboCop::AST::DefNode] def_node The method definition node whose body to scan.
+        # @param [Set<Symbol>] names_set Set of known method names to match against.
+        # @return [Array<Symbol>]
         def local_calls(def_node, names_set)
           body = def_node.body
           return [] unless body
 
+          # @type var res: Array[Symbol]
           res = []
           body.each_node(:send) do |send|
+            # @type var send: ::RuboCop::AST::SendNode
             recv = send.receiver
             next unless recv.nil? || recv&.self_type?
 
@@ -488,14 +538,15 @@ module RuboCop
           res.uniq
         end
 
-        # Build an adjacency list for a set of edges restricted to known names.
+        # Build an adjacency list (caller → [callees]) from edges, restricted to known names.
         #
-        # @param names [Array<Symbol>]
-        # @param edges [Array<Array(Symbol, Symbol)>]
-        # @return [Hash{Symbol=>Array<Symbol>}] adjacency list
-        # @api private
+        # @private
+        # @param [Array<Symbol>] names Ordered array of method names to restrict the adjacency to.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges Edges to build the adjacency list from.
+        # @return [Hash<Symbol, Array<Symbol>>]
         def build_adj(names, edges)
           allowed = names.to_set
+          # @type var adj: Hash[Symbol, Array[Symbol]]
           adj = Hash.new { |h, k| h[k] = [] }
 
           edges.each do |u, v|
@@ -508,114 +559,81 @@ module RuboCop
           adj
         end
 
-        # Breadth-first search to detect whether a path exists from +src+ to +dst+.
+        # Check if a path exists from `src` to `dst` in the adjacency graph (BFS with limit).
         #
-        # @param src [Symbol]
-        # @param dst [Symbol]
-        # @param adj [Hash{Symbol=>Array<Symbol>}] adjacency list
-        # @param limit [Integer] traversal safety limit
+        # @private
+        # @param [Symbol] src The starting node for the path search.
+        # @param [Symbol] dst The target node to find a path to.
+        # @param [Hash<Symbol, Array<Symbol>>] adj Adjacency map of the graph to search.
+        # @param [Integer] limit Maximum number of iterations (nodes visited) for the BFS.
         # @return [Boolean]
-        # @api private
         def path_exists?(src, dst, adj, limit = 200)
-          return true if src == dst
-
+          # @type var visited: Hash[Symbol, bool]
           visited = {}
-          q = [src]
-          i = 0
-          steps = 0
+          queue = [src]
+          limit.times do
+            break if queue.empty?
 
-          while i < q.length
-            steps += 1
-            return false if steps > limit
-
-            u = q[i]
-            i += 1
-            next if visited[u]
-
-            visited[u] = true
+            u = queue.shift
+            visited[u] ? next : (visited[u] = true)
             return true if u == dst
 
-            adj[u].each { |v| q << v unless visited[v] }
+            adj[u].each { |v| queue << v unless visited[v] }
           end
-
           false
         end
 
-        # Split the scope body into contiguous sections of def/defs grouped
-        # by the visibility modifier immediately preceding them (private/protected/public).
-        #
-        # 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]
-        # - :end_pos [Integer]
+        # Split body nodes into contiguous groups separated by non-def nodes, each with a visibility.
         #
-        # @param body_nodes [Array<RuboCop::AST::Node>]
-        # @return [Array<Hash>]
-        # @api private
+        # @private
+        # @param [Array<RuboCop::AST::Node>] body_nodes Body nodes of the scope to partition into visibility sections.
+        # @return [Array<RuboCop::Cop::SortedMethodsByCall::Waterfall::section>]
         def extract_visibility_sections(body_nodes)
-          sections = []
-          current_visibility = nil
-          current_defs = []
-          section_start = nil
-
-          body_nodes.each_with_index do |node, idx|
-            case node.type
-            when :def, :defs
-              current_defs << node
-              section_start ||= node.source_range.begin_pos
-            when :send
-              flush_visibility_section!(sections, current_visibility, current_defs, section_start, body_nodes, idx - 1)
-              current_defs = []
-              section_start = nil
-              current_visibility = node if bare_visibility_send?(node)
-            else
-              flush_visibility_section!(sections, current_visibility, current_defs, section_start, body_nodes, idx - 1)
-              current_defs = []
-              section_start = nil
-              current_visibility = nil
-            end
-          end
-
-          unless current_defs.empty?
-            sections << {
-              visibility: current_visibility,
-              defs: current_defs,
-              start_pos: section_start,
-              end_pos: current_defs.last.source_range.end_pos
-            }
+          vis = nil
+          body_nodes.slice_when { |_, b| not_def_node?(b) }.filter_map do |group|
+            # @type var defs: Array[::RuboCop::AST::DefNode]
+            defs = group.reject { |n| not_def_node?(n) }
+            next if defs.empty?
+
+            vis = vis_node(group) || vis
+            make_section(vis, defs)
           end
+        end
 
-          sections
+        # Check if a node is NOT a `:def` or `:defs` node.
+        #
+        # @private
+        # @param [Object] node The AST node to check.
+        # @return [Boolean]
+        def not_def_node?(node)
+          !%i[def defs].include?(node.type)
         end
 
-        # Flush a currently-collected contiguous def/defs group into +sections+.
+        # Find the visibility modifier node (`private`/`protected`/`public`) in a group of nodes.
         #
-        # @param sections [Array<Hash>]
-        # @param current_visibility [RuboCop::AST::Node, nil]
-        # @param current_defs [Array<RuboCop::AST::Node>]
-        # @param section_start [Integer, nil]
-        # @param body_nodes [Array<RuboCop::AST::Node>]
-        # @param last_idx [Integer]
-        # @return [void]
-        # @api private
-        def flush_visibility_section!(sections, current_visibility, current_defs, section_start, body_nodes, last_idx)
-          return if current_defs.empty?
+        # @private
+        # @param [Array<RuboCop::AST::Node>] group A group of consecutive body nodes to search for a visibility modifier.
+        # @return [RuboCop::AST::Node?]
+        def vis_node(group)
+          group.find { |n| n.send_type? && bare_visibility_send?(n) }
+        end
 
-          sections << {
-            visibility: current_visibility,
-            defs: current_defs.dup,
-            start_pos: section_start,
-            end_pos: body_nodes[last_idx].source_range.end_pos
-          }
+        # Build a section hash with visibility, def nodes, and positional bounds.
+        #
+        # @private
+        # @param [RuboCop::AST::Node?] vis The visibility modifier node (or nil for default public).
+        # @param [Array<RuboCop::AST::DefNode>] defs Array of method definition nodes in this section.
+        # @return [RuboCop::Cop::SortedMethodsByCall::Waterfall::section]
+        def make_section(vis, defs)
+          { visibility: vis, defs: defs, start_pos: defs.first.source_range.begin_pos,
+            end_pos: defs.last.source_range.end_pos }
         end
 
-        # Check if +node+ is a bare visibility modifier send:
-        # `private`, `protected`, or `public` (with no args and no receiver).
+        # Check if a node is a bare visibility modifier send (no receiver, no args).
         #
-        # @param node [RuboCop::AST::Node]
+        # @private
+        # @param [Object] node The AST node to check for bare visibility send pattern.
         # @return [Boolean]
-        # @api private
         def bare_visibility_send?(node)
           node.receiver.nil? &&
             VISIBILITY_METHODS.include?(node.method_name) &&
@@ -624,34 +642,70 @@ module RuboCop
 
         # Find the visibility section containing a given method name.
         #
-        # @param sections [Array<Hash>]
-        # @param method_name [Symbol]
-        # @return [Hash, nil]
-        # @api private
+        # @private
+        # @param [Array<RuboCop::Cop::SortedMethodsByCall::Waterfall::section>] sections Visibility sections to search through.
+        # @param [Symbol] method_name The method name to locate.
+        # @return [RuboCop::Cop::SortedMethodsByCall::Waterfall::section?]
         def section_for_method(sections, method_name)
           sections.find { |s| s[:defs].any? { |d| d.method_name == method_name } }
         end
 
-        # Normalize a section to a string visibility label ("public", "private", "protected").
+        # Convert a visibility section to a string label (`"public"`, `"private"`, `"protected"`).
         #
-        # @param section [Hash, nil]
+        # @private
+        # @param [RuboCop::Cop::SortedMethodsByCall::Waterfall::section?] section The visibility section node (or nil for default public).
         # @return [String]
-        # @api private
         def visibility_label(section)
           return 'public' unless section # default visibility
 
           (section[:visibility]&.method_name || :public).to_s
         end
 
-        # Stable topological sort using the current definition order as a tie-breaker.
+        # Topologically sort names by edges; returns nil if a cycle exists.
         #
-        # @param names [Array<Symbol>]
-        # @param edges [Array<Array(Symbol, Symbol)>]
-        # @param idx_of [Hash{Symbol=>Integer}]
-        # @return [Array<Symbol>, nil] sorted list, or nil if cycle prevents a full order
-        # @api private
+        # @private
+        # @param [Array<Symbol>] names Ordered array of method names to sort.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges Edges defining the dependency ordering constraints.
+        # @param [Hash<Symbol, Integer>] idx_of Map from method names to their original position index for stable sorting.
+        # @return [Array<Symbol>?]
         def topo_sort(names, edges, idx_of)
+          indegree, adj = graph(names, edges)
+          queue = names.select { |n| indegree[n].zero? }.sort_by { |n| idx_of[n] }
+          result = kahn_sort(indegree, adj, queue, idx_of)
+          result.size == names.size ? result : nil
+        end
+
+        # Kahn's algorithm for topological sort with stable tie-breaking by original index.
+        #
+        # @private
+        # @param [Hash<Symbol, Integer>] indegree Map from node to its indegree count.
+        # @param [Hash<Symbol, Array<Symbol>>] adj Adjacency list of the graph.
+        # @param [Array<Symbol>] queue Initial queue of nodes with zero indegree, pre-sorted by original index.
+        # @param [Hash<Symbol, Integer>] idx_of Map from method names to their original position index for stable sorting.
+        # @return [Array<Symbol>]
+        def kahn_sort(indegree, adj, queue, idx_of)
+          # @type var result: Array[Symbol]
+          result = []
+          until queue.empty?
+            result << (n = queue.shift)
+            adj[n].each do |m|
+              indegree[m] -= 1
+              queue << m if indegree[m].zero?
+            end
+            queue.sort_by! { |x| idx_of[x] }
+          end
+          result
+        end
+
+        # Build indegree map and adjacency list from edges for topological sort.
+        #
+        # @private
+        # @param [Array<Symbol>] names Ordered array of method names to include in the graph.
+        # @param [Array<[ ::Symbol, ::Symbol ]>] edges Edges defining the dependency relationships.
+        # @return [[ ::Hash[::Symbol, ::Integer], ::Hash[::Symbol, ::Array[::Symbol]] ]]
+        def graph(names, edges)
           indegree = Hash.new(0)
+          # @type var adj: Hash[Symbol, Array[Symbol]]
           adj = Hash.new { |h, k| h[k] = [] }
 
           edges.each do |caller, callee|
@@ -660,80 +714,52 @@ module RuboCop
 
             adj[caller] << callee
             indegree[callee] += 1
-            indegree[caller] ||= 0
           end
 
           names.each { |n| indegree[n] ||= 0 }
 
-          queue = names.select { |n| indegree[n].zero? }.sort_by { |n| idx_of[n] }
-          result = []
-
-          until queue.empty?
-            n = queue.shift
-            result << n
-
-            adj[n].each do |m|
-              indegree[m] -= 1
-              queue << m if indegree[m].zero?
-            end
-
-            queue.sort_by! { |x| idx_of[x] }
-          end
-
-          return nil unless result.size == names.size
-
-          result
+          [indegree, adj]
         end
 
-        # Return 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
-        # doc comments when methods are moved during autocorrect.
+        # Expand a node's source range to include leading comment lines.
         #
-        # @param node [RuboCop::AST::Node] :def or :defs
+        # @private
+        # @param [RuboCop::AST::Node] node The AST node whose source range to expand.
         # @return [Parser::Source::Range]
-        # @api private
         def range_with_leading_comments(node)
           buffer = processed_source.buffer
           expr = node.source_range
 
-          start_line = expr.line
-          lineno = start_line - 1
-
-          while lineno >= 1
-            line = buffer.source_line(lineno)
-            break unless line =~ /\A\s*#/
-
-            start_line = lineno
-            lineno -= 1
+          start_line = (1...expr.line).reverse_each.reduce(expr.line) do |line, lineno|
+            buffer.source_line(lineno) =~ /\A\s*#/ ? lineno : (break line)
           end
 
-          start_pos = buffer.line_range(start_line).begin_pos
-          range_between(start_pos, expr.end_pos)
+          range_between(buffer.line_range(start_line).begin_pos, expr.end_pos)
         end
 
-        # Recurse into nested scopes inside the current scope body.
+        # Recursively analyze nested class/module/sclass scopes within body nodes.
         #
-        # @param body_nodes [Array<RuboCop::AST::Node>]
+        # @private
+        # @param [Array<RuboCop::AST::Node>] body_nodes Body nodes to scan for nested scope definitions.
         # @return [void]
-        # @api private
         def analyze_nested_scopes(body_nodes)
           body_nodes.each do |n|
             analyze_scope(n) if n.class_type? || n.module_type? || n.sclass_type?
           end
         end
 
-        # Read config: AllowedRecursion (default true).
+        # Read the `AllowedRecursion` config option (default true).
         #
+        # @private
         # @return [Boolean]
-        # @api private
         def allowed_recursion?
           cop_config.fetch('AllowedRecursion') { true }
         end
 
-        # Read config: SkipCyclicSiblingEdges (default false).
+        # Read the `SkipCyclicSiblingEdges` config option (default false).
         #
+        # @private
         # @return [Boolean]
-        # @api private
         def skip_cyclic_sibling_edges?
           cop_config.fetch('SkipCyclicSiblingEdges') { false }
         end