rubocop-sorted_methods_by_call 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d62de644bc87dd509f3407cc4db3c9e0b4c46991e6a4e682344a7024eae1217
-  data.tar.gz: 94858039c6204ae841a595b4e5c13db9cf3a0775cf615fdd4696951d68181303
+  metadata.gz: 02e794a25b73c4b96c7ec77721e5b5e4c71a3a23e0137011f3d272d27e81121e
+  data.tar.gz: 75db5c1df55a2d40a9fdf596b654bafa76eecbb163e16c419b7c0366ef4cd772
 SHA512:
-  metadata.gz: 91901d4d06ad36e83396752d9c7b47b3c838f61bb42686351b43f382281136aa219dcbeaaf1d5f0e2007db56728dd9e69dd7ba307f1758b9acc26cadf7b7416a
-  data.tar.gz: a06c24a47cf38ea1e06021d54f49a04ed26fb47174f2c4dd1b6491cb768243acbda01fe25933b55895387e58d8f00d7e163c24d08525394f1891953f9a8a6017
+  metadata.gz: 7c3e6192757164ad8c877337a9bf60e78ccb2c4b8d8abd2a3f8c15a865cfe7ea4b1440f6c443dd26ca9836951884b229927a718081ab521b64926cc25896bab4
+  data.tar.gz: 14f8232209323631fb6a993282e6133907d3937ecf1b639c9e186b79fb835f531a750a4ebdb6e972c3f558921507c7fbb3a954c6c26e7510d19a3ddc3e3cfd7d

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-11-06 17:19:21 UTC using RuboCop version 1.81.7.
+# on 2026-01-13 11:42:57 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
@@ -19,37 +19,47 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'rubocop-sorted_methods_by_call.gemspec'
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 61
+  Max: 78
 
-# Offense count: 2
+# Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 43
+  Max: 36
 
-# Offense count: 5
+# Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 26
+  Max: 35
 
-# Offense count: 7
+# Offense count: 9
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 68
+  Max: 70
 
-# Offense count: 4
+# Offense count: 2
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 6
+
+# Offense count: 3
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 27
+  Max: 37
 
-# Offense count: 16
+# Offense count: 21
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 37
 
+# Offense count: 1
+# Configuration parameters: AllowedGroups.
+RSpec/NestedGroups:
+  Max: 4
+
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.

data/Gemfile.lock

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

data/README.md

@@ -15,6 +15,7 @@
     * [Usage Examples](#usage-examples)
         * [Good Code (waterfall order)](#good-code-waterfall-order)
         * [Bad Code (violates waterfall order)](#bad-code-violates-waterfall-order)
+        * [Sibling ordering and cycles (why autocorrect can be skipped)](#sibling-ordering-and-cycles-why-autocorrect-can-be-skipped)
         * [Autocorrection](#autocorrection)
     * [Testing](#testing)
     * [Development](#development)
@@ -76,6 +77,12 @@ SortedMethodsByCall/Waterfall:
   Enabled: true
   SafeAutoCorrect: false          # Autocorrection requires -A flag
   AllowedRecursion: true          # Allow mutual recursion (default: true)
+  # If true, the cop will NOT add "called together" sibling-order edges
+  # that would introduce a cycle with existing constraints. This reduces
+  # impossible-to-fix sibling offenses and makes autocorrect more reliable.
+  #
+  # Default: false
+  SkipCyclicSiblingEdges: false
 ```
 
 ## Usage Examples
@@ -135,6 +142,46 @@ class Service
 end
 ```
 
+### Sibling ordering and cycles (why autocorrect can be skipped)
+
+`SortedMethodsByCall/Waterfall` enforces two kinds of ordering constraints:
+
+1. **Direct call edges**: if `caller` calls `callee`, then `caller` must be defined **before** `callee`.
+2. **Sibling ("called together") edges**: in orchestration methods (methods not called by others in the same scope),
+   consecutive calls imply an intended order (e.g., `a` then `b`), so `a` should be defined before `b`.
+
+Sometimes these constraints can conflict and create a **cycle**, which means there is no valid ordering that satisfies
+all constraints. In this situation, autocorrect may be skipped.
+
+Example:
+
+```ruby
+class SiblingCycleExample
+  def call
+    a
+    b
+  end
+
+  private
+
+  def b
+    c
+  end
+
+  def c
+    a
+  end
+
+  def a; end
+end
+```
+
+Here, the direct dependencies imply `b -> c -> a`, but the orchestration method implies `a -> b`,
+which forms the cycle `a -> b -> c -> a`.
+
+If you prefer to keep the warning (to encourage refactoring), leave `SkipCyclicSiblingEdges: false`.
+If you prefer the cop to avoid enforcing sibling edges that create cycles, set `SkipCyclicSiblingEdges: true`.
+
 ### Autocorrection
 
 Run with unsafe autocorrection to automatically fix violations:

data/config/default.yml

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

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

@@ -3,89 +3,123 @@
 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 recursion cycle
+      #     detectable in the direct call graph (callee → … → caller). If false,
+      #     such cycles are reported.
+      # - SafeAutoCorrect [Boolean] (default: false)
+      #     Autocorrection is unsafe and only runs under -A, never under -a.
+      # - SkipCyclicSiblingEdges [Boolean] (default: false)
+      #     If true, the cop will not add "called together" sibling-order edges
+      #     that would introduce a cycle with existing constraints (direct edges +
+      #     already accepted sibling edges).
       #
-      #   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.
+        VISIBILITY_METHODS = %i[private protected public].freeze
+
+        # 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
+        SIBLING_MSG = 'Define %<callee>s after %<caller>s to match the order they are called together.'
+
+        MSG_CROSS_VISIBILITY_NOTE =
+          '%<base>s (Autocorrect not supported across visibility boundaries: ' \
+          '%<caller_visibility>s vs %<callee_visibility>s.)'
+
+        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 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,156 +127,297 @@ module RuboCop
 
         private
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#analyze_scope+ -> void
-        #
-        # 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.
+        # 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
         #
-        # @param [RuboCop::AST::Node] scope_node
+        # @param scope_node [RuboCop::AST::Node] a :begin, :class, :module, or :sclass node
         # @return [void]
+        # @api private
         def analyze_scope(scope_node)
           body_nodes = scope_body_nodes(scope_node)
           return if body_nodes.empty?
 
-          def_nodes = body_nodes.select { |n| %i[def defs].include?(n.type) }
+          def_nodes = method_def_nodes(body_nodes)
           return if def_nodes.size <= 1
 
-          names     = def_nodes.map(&:method_name)
-          names_set = names.to_set
-          index_of  = names.each_with_index.to_h
+          names, names_set, index_of = method_name_index(def_nodes)
 
-          # -----------------------------------------------------------
-          # Phase 1  Collect 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] }
+          direct_edges = build_direct_edges(def_nodes, names_set)
+          sibling_edges = build_sibling_edges(def_nodes, names_set, direct_edges, names)
+
+          edges_for_sort = direct_edges + sibling_edges
+          adj_direct = build_adj(names, direct_edges)
+
+          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)]
+
+            message = build_offense_message(
+              violation_type: violation_type,
+              violation: violation,
+              names: names,
+              edges_for_sort: edges_for_sort,
+              body_nodes: body_nodes
+            )
+
+            add_offense(callee_node, message: message) do |corrector|
+              try_autocorrect(corrector, body_nodes, def_nodes, edges_for_sort, violation)
+            end
           end
 
+          analyze_nested_scopes(body_nodes)
+        end
+
+        # Return the direct "body statements" inside a scope node.
+        #
+        # @param node [RuboCop::AST::Node]
+        # @return [Array<RuboCop::AST::Node>] direct children inside the scope body
+        # @api private
+        def scope_body_nodes(node)
+          case node.type
+          when :begin
+            node.children
+          when :class, :module, :sclass
+            body = node.body
+            return [] unless body
+
+            body.begin_type? ? body.children : [body]
+          else
+            []
+          end
+        end
+
+        # Select only method definition nodes from a scope body.
+        #
+        # @param body_nodes [Array<RuboCop::AST::Node>]
+        # @return [Array<RuboCop::AST::Node>] :def/:defs nodes
+        # @api private
+        def method_def_nodes(body_nodes)
+          body_nodes.select { |n| %i[def defs].include?(n.type) }
+        end
+
+        # Compute helper structures for method names in this scope.
+        #
+        # @param def_nodes [Array<RuboCop::AST::Node>]
+        # @return [Array<(Array<Symbol>, Set<Symbol>, Hash{Symbol=>Integer})>]
+        # @api private
+        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.
+        #
+        # @param def_nodes [Array<RuboCop::AST::Node>]
+        # @param names_set [Set<Symbol>]
+        # @return [Array<Array(Symbol, Symbol)>]
+        # @api private
+        def build_direct_edges(def_nodes, names_set)
+          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
+        end
+
+        # Build sibling-order edges (a -> b) for consecutive calls inside 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
+        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)
 
-          # -----------------------------------------------------------
-          # Phase 2  Add sibling‑order edges for orchestration methods
-          # -----------------------------------------------------------
           sibling_edges = []
+
           def_nodes.each do |def_node|
             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) }
+              # 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
           end
 
-          # -----------------------------------------------------------
-          # Phase 3  Combine for sorting, but keep direct set for recursion
-          # -----------------------------------------------------------
-          edges_for_sort = direct_edges + sibling_edges
-          allow_recursion = cop_config.fetch('AllowedRecursion') { true }
+          sibling_edges
+        end
 
-          # Build adjacency only from *direct* calls for recursion checks
-          adj_direct = build_adj(names, direct_edges)
+        # Find the first ordering violation. Checks direct edges first, then sibling edges.
+        #
+        # @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
+        def find_violation(direct_edges, sibling_edges, index_of, adj_direct)
+          allow_recursion = allowed_recursion?
 
-          # Check for violations with edge type tracking
           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
+          return [:direct, violation] if violation
 
-          return unless violation
+          violation = first_backward_edge(sibling_edges, index_of, adj_direct, allow_recursion)
+          return [:sibling, violation] if violation
 
-          caller_name, callee_name = violation
-          callee_node = def_nodes[index_of[callee_name]]
-
-          # Choose message based on violation type
-          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
+          [nil, nil]
+        end
 
-          add_offense(callee_node, message: message) do |corrector|
-            try_autocorrect(corrector, body_nodes, def_nodes, edges_for_sort, violation)
-          end
+        # Return the first backward edge found, optionally skipping edges that participate
+        # in recursion/cycles detectable in the direct-call graph (AllowedRecursion).
+        #
+        # @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
+        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)
+            next if allow_recursion && path_exists?(callee, caller, adj_direct)
 
-          # Recurse into nested scopes
-          body_nodes.each do |n|
-            analyze_scope(n) if n.class_type? || n.module_type? || n.sclass_type?
+            index_of[callee] < index_of[caller]
           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.
+        # Construct the final offense message, including optional notes:
+        # - sibling cycle note (for sibling violations)
+        # - cross-visibility note (public/private/protected boundary)
         #
-        # @param [RuboCop::AST::Node] node
-        # @return [Array<RuboCop::AST::Node>]
-        def scope_body_nodes(node)
-          case node.type
-          when :begin
-            node.children
-          when :class, :module, :sclass
-            body = node.body
-            return [] unless body
+        # @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>]
+        # @return [String]
+        # @api private
+        def build_offense_message(violation_type:, violation:, names:, edges_for_sort:, body_nodes:)
+          caller_name, callee_name = violation
 
-            body.begin_type? ? body.children : [body]
+          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)
+          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 [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}")
           else
-            []
+            format(MSG, callee: "##{callee_name}", caller: "##{caller_name}")
           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.
+        # Add a note when a sibling-order edge is part of a cycle in the combined graph.
         #
-        # @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?
+        # @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)>]
+        # @return [String]
+        # @api private
+        def add_sibling_cycle_note_if_needed(base_message, violation_type, caller_name, callee_name, names,
+                                             edges_for_sort)
+          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
+            base_message
+          end
+        end
 
-            mname = send.method_name
-            res << mname if names_set.include?(mname)
+        # Add a note when the violation crosses visibility boundaries.
+        #
+        # @param base_message [String]
+        # @param body_nodes [Array<RuboCop::AST::Node>]
+        # @param caller_name [Symbol]
+        # @param callee_name [Symbol]
+        # @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
-          res.uniq
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#try_autocorrect+ -> void
+        # UNSAFE autocorrect: reorder method definitions inside one contiguous visibility section only.
         #
-        # 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.
+        # This method intentionally does NOT reorder across:
+        # - `private/protected/public` boundaries
+        # - nested scopes
+        # - non-visibility statements that break contiguity
         #
-        # @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
-        # @param [Array(Symbol, Symbol)] violation The found violation (caller, callee)
+        # @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]
         # @return [void]
-        #
-        # @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, violation)
+        # @api private
+        def try_autocorrect(corrector, body_nodes, def_nodes, edges, initial_violation = nil)
           sections = extract_visibility_sections(body_nodes)
 
+          names     = def_nodes.map(&:method_name)
+          names_set = names.to_set
+          idx_of    = names.each_with_index.to_h
+
+          # 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
+
           caller_name, callee_name = violation
 
-          # find target section containing both defs
           target_section = sections.find do |section|
             section_names = section[:defs].map(&:method_name)
             section_names.include?(caller_name) && section_names.include?(callee_name)
@@ -252,27 +427,31 @@ module RuboCop
           defs = target_section[:defs]
           return if defs.size <= 1
 
-          section_names   = defs.map(&:method_name)
-          section_edges   = edges.select { |u, v| section_names.include?(u) && section_names.include?(v) }
-          section_idx_of  = section_names.each_with_index.to_h
+          section_names  = defs.map(&:method_name)
+          section_idx_of = section_names.each_with_index.to_h
 
-          # sort within section or minimally fix if graph is cyclic
-          sorted_names = topo_sort(section_names, section_edges, section_idx_of)
+          direct_violation = direct_edges.any? { |u, v| u == caller_name && v == callee_name }
 
-          # forcibly fix when topo_sort failed or produced same order
-          if sorted_names.nil? || sorted_names == section_names
-            sorted_names = section_names.dup
-            # remove callee and reinsert it after its caller
-            sorted_names.delete(callee_name)
-            caller_index = sorted_names.index(caller_name) || -1
-            sorted_names.insert(caller_index + 1, callee_name)
-          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) }
 
-          # reconstruct source
-          ranges_by_name = defs.to_h do |d|
-            [d.method_name, range_with_leading_comments(d)]
+          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
-          sorted_def_sources = sorted_names.map { |n| ranges_by_name[n].source }
+
+          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 }
 
           visibility_node   = target_section[:visibility]
           visibility_source = visibility_node&.source.to_s
@@ -290,72 +469,76 @@ module RuboCop
             else
               defs.map { |d| range_with_leading_comments(d).begin_pos }.min
             end
-          section_end = defs.last.source_range.end_pos
 
-          region = Parser::Source::Range.new(processed_source.buffer, section_begin, section_end)
+          section_end = target_section[:end_pos]
+          region = range_between(section_begin, section_end)
           corrector.replace(region, new_content)
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#build_adj+ -> Hash{Symbol=>Array<Symbol>}
+        # Collect local method calls (receiver is nil/self) from within a def node,
+        # restricted to known method names in this scope.
         #
-        # Builds an adjacency list for edges restricted to 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
+        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
+
+        # Build an adjacency list for a set of edges restricted to known names.
         #
-        # @param [Array<Symbol>] names
-        # @param [Array<Array(Symbol, Symbol)>] edges
-        # @return [Hash{Symbol=>Array<Symbol>}]
+        # @param names [Array<Symbol>]
+        # @param edges [Array<Array(Symbol, Symbol)>]
+        # @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] = [] }
+
           edges.each do |u, v|
             next unless allowed.include?(u) && allowed.include?(v)
             next if u == v
 
             adj[u] << v
           end
-          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.
-        #
-        # @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]
-        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)
-            # If mutual recursion allowed and there is a path callee -> caller, skip
-            next if allow_recursion && path_exists?(callee, caller, adj)
-
-            # Violation: callee is defined BEFORE caller (waterfall order)
-            index_of[callee] < index_of[caller]
-          end
+          adj
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#path_exists?+ -> Boolean
+        # Breadth-first search to detect whether a path exists from +src+ to +dst+.
         #
-        # Tests whether a path exists in the adjacency graph from +src+ to +dst+ (BFS).
-        #
-        # @param [Symbol] src
-        # @param [Symbol] dst
-        # @param [Hash{Symbol=>Array<Symbol>}] adj
-        # @param [Integer] limit traversal step limit (guard)
+        # @param src [Symbol]
+        # @param dst [Symbol]
+        # @param adj [Hash{Symbol=>Array<Symbol>}] adjacency list
+        # @param limit [Integer] traversal safety limit
         # @return [Boolean]
+        # @api private
         def path_exists?(src, dst, adj, limit = 200)
           return true if src == dst
 
           visited = {}
           q = [src]
+          i = 0
           steps = 0
-          until q.empty?
+
+          while i < q.length
             steps += 1
             return false if steps > limit
 
-            u = q.shift
+            u = q[i]
+            i += 1
             next if visited[u]
 
             visited[u] = true
@@ -363,20 +546,22 @@ module RuboCop
 
             adj[u].each { |v| q << v unless visited[v] }
           end
+
           false
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#extract_visibility_sections+ -> Array<Hash>
+        # Split 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]
+        # - :end_pos [Integer]
         #
-        # @param [Array<RuboCop::AST::Node>] body_nodes
-        # @return [Array<Hash{Symbol=>untyped}>]
+        # @param body_nodes [Array<RuboCop::AST::Node>]
+        # @return [Array<Hash>]
+        # @api private
         def extract_visibility_sections(body_nodes)
           sections = []
           current_visibility = nil
@@ -389,49 +574,18 @@ module RuboCop
               current_defs << node
               section_start ||= node.source_range.begin_pos
             when :send
-              # visibility modifier?
-              if node.receiver.nil? &&
-                 %i[private protected public].include?(node.method_name) &&
-                 node.arguments.empty?
-                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
-                # anything else breaks contiguous run
-                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
-              end
+              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
-              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
+              flush_visibility_section!(sections, current_visibility, current_defs, section_start, body_nodes, idx - 1)
+              current_defs = []
+              section_start = nil
+              current_visibility = nil
             end
           end
 
-          # trailing defs
           unless current_defs.empty?
             sections << {
               visibility: current_visibility,
@@ -441,30 +595,70 @@ module RuboCop
             }
           end
 
-          # -----------------------------------------------
-          # merge consecutive groups with identical visibility
-          # -----------------------------------------------
-          merged = []
-          sections.each do |s|
-            if !merged.empty? &&
-               merged.last[:visibility]&.source == s[:visibility]&.source
-              merged.last[:defs].concat(s[:defs])
-              merged.last[:end_pos] = s[:end_pos]
-            else
-              merged << s
-            end
-          end
-          merged
+          sections
+        end
+
+        # Flush a currently-collected contiguous def/defs group into +sections+.
+        #
+        # @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?
+
+          sections << {
+            visibility: current_visibility,
+            defs: current_defs.dup,
+            start_pos: section_start,
+            end_pos: body_nodes[last_idx].source_range.end_pos
+          }
+        end
+
+        # Check if +node+ is a bare visibility modifier send:
+        # `private`, `protected`, or `public` (with no args and no receiver).
+        #
+        # @param node [RuboCop::AST::Node]
+        # @return [Boolean]
+        # @api private
+        def bare_visibility_send?(node)
+          node.receiver.nil? &&
+            VISIBILITY_METHODS.include?(node.method_name) &&
+            node.arguments.empty?
+        end
+
+        # Find the visibility section containing a given method name.
+        #
+        # @param sections [Array<Hash>]
+        # @param method_name [Symbol]
+        # @return [Hash, nil]
+        # @api private
+        def section_for_method(sections, method_name)
+          sections.find { |s| s[:defs].any? { |d| d.method_name == method_name } }
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#topo_sort+ -> Array<Symbol>, nil
+        # Normalize a section to a string visibility label ("public", "private", "protected").
         #
-        # Performs a stable topological sort using current order as a tie-breaker.
+        # @param section [Hash, nil]
+        # @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.
         #
-        # @param [Array<Symbol>] names
-        # @param [Array<Array(Symbol, Symbol)>] edges
-        # @param [Hash{Symbol=>Integer}] idx_of
-        # @return [Array<Symbol>, nil] sorted names or nil if a cycle prevents a full order
+        # @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
         def topo_sort(names, edges, idx_of)
           indegree = Hash.new(0)
           adj = Hash.new { |h, k| h[k] = [] }
@@ -477,6 +671,7 @@ module RuboCop
             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] }
@@ -485,10 +680,12 @@ module RuboCop
           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
 
@@ -497,20 +694,20 @@ module RuboCop
           result
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#range_with_leading_comments+ -> Parser::Source::Range
+        # 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.
         #
-        # 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
-        # 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
+        # @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*#/
@@ -520,7 +717,34 @@ module RuboCop
           end
 
           start_pos = buffer.line_range(start_line).begin_pos
-          Parser::Source::Range.new(buffer, start_pos, expr.end_pos)
+          range_between(start_pos, expr.end_pos)
+        end
+
+        # Recurse into nested scopes inside the current scope body.
+        #
+        # @param body_nodes [Array<RuboCop::AST::Node>]
+        # @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).
+        #
+        # @return [Boolean]
+        # @api private
+        def allowed_recursion?
+          cop_config.fetch('AllowedRecursion') { true }
+        end
+
+        # Read config: SkipCyclicSiblingEdges (default false).
+        #
+        # @return [Boolean]
+        # @api private
+        def skip_cyclic_sibling_edges?
+          cop_config.fetch('SkipCyclicSiblingEdges') { false }
         end
       end
     end

data/lib/rubocop/sorted_methods_by_call/compare.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module SortedMethodsByCall
     # +RuboCop::SortedMethodsByCall::Compare+ provides helpers to compare
-    # definition orders and call orders using “ordered subsequence” semantics.
+    # definition orders and call orders using "ordered subsequence" semantics.
     # It’s used by the cop to check that called methods appear in the same
     # relative order as they are defined (not necessarily contiguously).
     module Compare

data/lib/rubocop/sorted_methods_by_call/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module SortedMethodsByCall
-    VERSION = '1.1.1'
+    VERSION = '1.2.0'
   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.1
+  version: 1.2.0
 platform: ruby
 authors:
 - unurgunite
@@ -186,7 +186,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.2
 specification_version: 4
 summary: RuboCop extension for method sorting in AST by stack trace.
 test_files: []