rubocop-sorted_methods_by_call 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb5b1320e0c36ea11d3931c04aad10d03a3c909cf16added71b537bb540e9851
-  data.tar.gz: c2e121be2bfa362e5e6b8f7acaae7378d82158fbecdcb0c6b562e9eb4f4f1b0b
+  metadata.gz: 1d62de644bc87dd509f3407cc4db3c9e0b4c46991e6a4e682344a7024eae1217
+  data.tar.gz: 94858039c6204ae841a595b4e5c13db9cf3a0775cf615fdd4696951d68181303
 SHA512:
-  metadata.gz: 45b61992be6ad19b714eaa67929b0782c0cfb6b237cfb0a9770aca073f5672b817586305b8588052d636556e73afcd54826112d19ec67cb3d13df9af554a6e2b
-  data.tar.gz: 2983a3c4e99c5c58cb4361b2ac93b588230df3e318e79c1f4ec8b0b0f16d49ac69ff0e9f2fd443ecf5ac3ef8be3d673f3116f18854498590f129d23093079da8
+  metadata.gz: 91901d4d06ad36e83396752d9c7b47b3c838f61bb42686351b43f382281136aa219dcbeaaf1d5f0e2007db56728dd9e69dd7ba307f1758b9acc26cadf7b7416a
+  data.tar.gz: a06c24a47cf38ea1e06021d54f49a04ed26fb47174f2c4dd1b6491cb768243acbda01fe25933b55895387e58d8f00d7e163c24d08525394f1891953f9a8a6017

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-11-05 21:07:30 UTC using RuboCop version 1.81.7.
+# on 2025-11-06 17:19:21 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
@@ -24,7 +24,7 @@ Gemspec/RequiredRubyVersion:
 Metrics/AbcSize:
   Max: 61
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
@@ -33,22 +33,22 @@ Metrics/BlockLength:
 # Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 20
+  Max: 26
 
 # Offense count: 7
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 58
+  Max: 68
 
 # Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 22
+  Max: 27
 
-# Offense count: 11
+# Offense count: 16
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Max: 26
+  Max: 37
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).

data/Gemfile.lock

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

data/LICENSE.txt

@@ -1,11 +1,21 @@
-Copyright 2022 unurgunite
+MIT License
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Copyright (c) 2025 unurgunite
 
-1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -4,6 +4,8 @@
 [![CI](https://github.com/unurgunite/rubocop-sorted_methods_by_call/actions/workflows/ci.yml/badge.svg)](https://github.com/unurgunite/rubocop-sorted_methods_by_call/actions)
 [![Gem Version](https://badge.fury.io/rb/rubocop-sorted_methods_by_call.svg)](https://rubygems.org/gems/rubocop-sorted_methods_by_call)
 
+**Enforces "waterfall" method ordering**: define methods *after* any method that calls them within the same scope.
+
 * [RuboCop::SortedMethodsByCall](#rubocopsortedmethodsbycall)
     * [Features](#features)
     * [Installation](#installation)
@@ -24,16 +26,14 @@
     * [License](#license)
     * [Code of Conduct](#code-of-conduct)
 
-**Enforces "waterfall" method ordering**: define methods *after* any method that calls them within the same scope.
-
 ## Features
 
-- **Waterfall ordering enforcement**: Caller methods must be defined before their callees
-- **Smart visibility handling**: Respects `private`/`protected`/`public` sections
-- **Safe mutual recursion**: Handles recursive method calls gracefully
-- **Autocorrection support**: Automatically reorders methods (opt-in with `-A`)
-- **Full RuboCop integration**: Works seamlessly with modern RuboCop plugin system
-- **Comprehensive scope support**: Classes, modules, singleton classes, and top-level
+- **Waterfall ordering enforcement**: Caller methods must be defined before their callees;
+- **Smart visibility handling**: Respects `private`/`protected`/`public` sections;
+- **Safe mutual recursion**: Handles recursive method calls gracefully;
+- **Autocorrection support**: Automatically reorders methods (opt-in with `-A`);
+- **Full RuboCop integration**: Works seamlessly with modern RuboCop plugin system;
+- **Comprehensive scope support**: Classes, modules, singleton classes, and top-level;
 
 ## Installation
 
@@ -82,19 +82,28 @@ SortedMethodsByCall/Waterfall:
 
 ### Good Code (waterfall order)
 
+In waterfall ordering, **callers come before callees**. This creates a top-down reading flow where main logic appears
+before implementation details.
+
 ```ruby
+
 class Service
   def call
-    do_smth
+    foo
+    bar
   end
 
   private
 
-  def do_smth
-    well
+  def bar
+    method123
   end
 
-  def well
+  def method123
+    foo
+  end
+
+  def foo
     123
   end
 end
@@ -103,19 +112,25 @@ end
 ### Bad Code (violates waterfall order)
 
 ```ruby
+
 class Service
   def call
-    do_smth
+    foo
+    bar
   end
 
   private
 
-  def well # ❌ Offense: Define #well after its caller #do_smth
+  def foo # ❌ Offense: Define #foo after its caller #method123
     123
   end
 
-  def do_smth
-    well
+  def bar
+    method123
+  end
+
+  def method123
+    foo
   end
 end
 ```
@@ -128,25 +143,7 @@ Run with unsafe autocorrection to automatically fix violations:
 bundle exec rubocop -A
 ```
 
-This will reorder the methods while preserving comments and visibility modifiers:
-
-```ruby
-class Service
-  def call
-    do_smth
-  end
-
-  private
-
-  def do_smth
-    well
-  end
-
-  def well
-    123
-  end
-end
-```
+This will reorder the methods while preserving comments and visibility modifiers.
 
 ## Testing
 
@@ -160,7 +157,7 @@ Run RuboCop on the gem itself:
 
 ```bash
 bundle exec rubocop
-bundle exec rubocop --config .rubocop.test.yml lib/ -A
+bundle exec rubocop --config test_project/.rubocop.test.yml lib/ -A
 ```
 
 ## Development
@@ -212,8 +209,7 @@ at https://unurgunite.github.io/rubocop-sorted_methods_by_call_docs/
 
 ## License
 
-The gem is available as open source under the terms of
-the [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause).
+The gem is available as open source under the terms of MIT License.
 
 ## Code of Conduct
 
@@ -221,5 +217,6 @@ Everyone interacting with this project is expected to follow the [Code of Conduc
 
 ---
 
-> **Note**: This gem is now stable and ready for production use! The "waterfall" ordering pattern helps create more
-> readable code by ensuring that methods are defined in the order they're conceptually needed.
+> **Note**: This gem implements **true waterfall ordering** that considers the complete call graph across all methods in
+> a scope. Methods are ordered so that every callee appears after all of its callers, creating a natural top-down
+> reading flow.

data/config/default.yml

@@ -1,7 +1,6 @@
-# Default configuration for rubocop-sorted_methods_by_call
 SortedMethodsByCall/Waterfall:
-  Description: "Enforces waterfall ordering: define methods after the methods that call them."
+  Description: "Enforces method ordering based on call relationships."
   Enabled: false
-  VersionAdded: "1.0.1"
+  VersionAdded: "1.1.1"
   SafeAutoCorrect: false
   AllowedRecursion: true

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

@@ -11,21 +11,32 @@ module RuboCop
       # - Autocorrect: UNSAFE; reorders methods within a contiguous visibility section
       #
       # Example (good):
-      #   def foo
+      #   def call
+      #     foo
       #     bar
       #   end
       #
+      #   private
+      #
       #   def bar
+      #     method123
+      #   end
+      #
+      #   def method123
+      #     foo
+      #   end
+      #
+      #   def foo
       #     123
       #   end
       #
       # Example (bad):
-      #   def bar
+      #   def foo
       #     123
       #   end
       #
-      #   def foo
-      #     bar
+      #   def call
+      #     foo
       #   end
       #
       # Autocorrect (unsafe, opt-in via SafeAutoCorrect: false): topologically sorts the contiguous
@@ -98,35 +109,74 @@ module RuboCop
           def_nodes = body_nodes.select { |n| %i[def defs].include?(n.type) }
           return if def_nodes.size <= 1
 
-          names = def_nodes.map(&:method_name)
+          names     = def_nodes.map(&:method_name)
           names_set = names.to_set
-          index_of = names.each_with_index.to_h
+          index_of  = names.each_with_index.to_h
+
+          # -----------------------------------------------------------
+          # 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] }
+          end
+
+          all_callees = direct_edges.to_set(&:last)
 
-          edges = []
+          # -----------------------------------------------------------
+          # Phase 2  Add sibling‑order edges for orchestration methods
+          # -----------------------------------------------------------
+          sibling_edges = []
           def_nodes.each do |def_node|
-            local_calls(def_node, names_set).each do |callee|
-              next if callee == def_node.method_name # self-recursion
+            next if all_callees.include?(def_node.method_name)
+
+            calls = local_calls(def_node, names_set)
+            calls.each_cons(2) do |a, b|
+              next if direct_edges.any? { |u, v| (u == a && v == b) || (u == b && v == a) }
 
-              edges << [def_node.method_name, callee]
+              sibling_edges << [a, b]
             end
           end
 
+          # -----------------------------------------------------------
+          # 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 }
-          adj = build_adj(names, edges)
 
-          violation = first_backward_edge(edges, index_of, adj, allow_recursion)
+          # Build adjacency only from *direct* calls for recursion checks
+          adj_direct = build_adj(names, direct_edges)
+
+          # 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 unless violation
 
           caller_name, callee_name = violation
           callee_node = def_nodes[index_of[callee_name]]
 
-          add_offense(callee_node,
-                      message: format(MSG, callee: "##{callee_name}", caller: "##{caller_name}")) do |corrector|
-            try_autocorrect(corrector, body_nodes, def_nodes, edges)
+          # 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
+
+          add_offense(callee_node, message: message) do |corrector|
+            try_autocorrect(corrector, body_nodes, def_nodes, edges_for_sort, violation)
           end
 
           # Recurse into nested scopes
-          body_nodes.each { |n| analyze_scope(n) if n.class_type? || n.module_type? || n.sclass_type? }
+          body_nodes.each do |n|
+            analyze_scope(n) if n.class_type? || n.module_type? || n.sclass_type?
+          end
         end
 
         # +RuboCop::Cop::SortedMethodsByCall::Waterfall#scope_body_nodes+ -> Array<RuboCop::AST::Node>
@@ -172,20 +222,6 @@ module RuboCop
           res.uniq
         end
 
-        # +RuboCop::Cop::SortedMethodsByCall::Waterfall#find_violation+ -> [Symbol, Symbol], nil
-        #
-        # Finds the first backward edge (caller->callee where callee is defined above caller)
-        # using the provided index map.
-        #
-        # @param [Array<Array(Symbol, Symbol)>] edges
-        # @param [Hash{Symbol=>Integer}] index_of
-        # @return [[Symbol, Symbol], nil] tuple [caller, callee] or nil if none found
-        def find_violation(edges, index_of)
-          edges.find do |caller, callee|
-            index_of.key?(caller) && index_of.key?(callee) && index_of[callee] < index_of[caller]
-          end
-        end
-
         # +RuboCop::Cop::SortedMethodsByCall::Waterfall#try_autocorrect+ -> void
         #
         # UNSAFE: Reorders method definitions inside the target visibility section only
@@ -196,75 +232,64 @@ module RuboCop
         # @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)
         # @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)
-          # Group method definitions into visibility sections
+        def try_autocorrect(corrector, body_nodes, _def_nodes, edges, violation)
           sections = extract_visibility_sections(body_nodes)
 
-          # Find the section that contains our violating methods
-          caller_name, callee_name = first_backward_edge(
-            edges,
-            def_nodes.map(&:method_name).each_with_index.to_h,
-            build_adj(def_nodes.map(&:method_name), edges),
-            cop_config.fetch('AllowedRecursion') { true }
-          )
-
-          # No violation -> nothing to do
-          return unless caller_name && callee_name
+          caller_name, callee_name = violation
 
-          #            Find a visibility section that contains both names
+          # find target section containing both defs
           target_section = sections.find do |section|
-            names_in_section = section[:defs].to_set(&:method_name)
-            names_in_section.include?(caller_name) && names_in_section.include?(callee_name)
+            section_names = section[:defs].map(&:method_name)
+            section_names.include?(caller_name) && section_names.include?(callee_name)
           end
-
-          # If violation spans multiple sections, skip autocorrect
           return unless target_section
 
           defs = target_section[:defs]
-          return unless defs.size > 1
-
-          # Apply topological sort only within this visibility section
-          defs = target_section[:defs]
-          names = defs.map(&:method_name)
-          idx_of = names.each_with_index.to_h
-
-          # Filter edges to only those within this section
-          # Filter edges to only those within this section
-          section_names = names.to_set
-          section_edges = edges.select { |u, v| section_names.include?(u) && section_names.include?(v) }
-
-          sorted_names = topo_sort(names, section_edges, idx_of)
-          return unless sorted_names
+          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
+
+          # sort within section or minimally fix if graph is cyclic
+          sorted_names = topo_sort(section_names, section_edges, section_idx_of)
+
+          # 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
 
-          # Capture each def with its leading contiguous comment block
-          ranges_by_name = defs.to_h { |d| [d.method_name, range_with_leading_comments(d)] }
-          sorted_def_sources = sorted_names.map { |name| ranges_by_name[name].source }
+          # reconstruct source
+          ranges_by_name = defs.to_h do |d|
+            [d.method_name, range_with_leading_comments(d)]
+          end
+          sorted_def_sources = sorted_names.map { |n| ranges_by_name[n].source }
 
-          # Reconstruct the section: keep the visibility modifier (if any) above the first def
           visibility_node   = target_section[:visibility]
           visibility_source = visibility_node&.source.to_s
 
-          new_content = if visibility_source.empty?
-                          sorted_def_sources.join("\n\n")
-                        else
-                          "#{visibility_source}\n\n#{sorted_def_sources.join("\n\n")}"
-                        end
+          new_content =
+            if visibility_source.empty?
+              sorted_def_sources.join("\n\n")
+            else
+              "#{visibility_source}\n\n#{sorted_def_sources.join("\n\n")}"
+            end
 
-          # Expand the replaced region:
-          # - if a visibility node exists, start from its begin_pos (so we replace it)
-          # - otherwise, start from the earliest leading doc-comment of the defs
           section_begin =
             if visibility_node
               visibility_node.source_range.begin_pos
             else
               defs.map { |d| range_with_leading_comments(d).begin_pos }.min
             end
-
-          # Always end at the end of the last def
           section_end = defs.last.source_range.end_pos
 
           region = Parser::Source::Range.new(processed_source.buffer, section_begin, section_end)
@@ -306,6 +331,7 @@ module RuboCop
             # 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
         end
@@ -363,9 +389,10 @@ module RuboCop
               current_defs << node
               section_start ||= node.source_range.begin_pos
             when :send
-              # Check if this is a visibility modifier (private/protected/public)
-              if node.receiver.nil? && %i[private protected public].include?(node.method_name) && node.arguments.empty?
-                # End current section if it has defs
+              # 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,
@@ -378,7 +405,7 @@ module RuboCop
                 end
                 current_visibility = node
               else
-                # Non-visibility send - breaks contiguity
+                # anything else breaks contiguous run
                 unless current_defs.empty?
                   sections << {
                     visibility: current_visibility,
@@ -388,11 +415,9 @@ module RuboCop
                   }
                   current_defs = []
                   section_start = nil
-                  current_visibility = nil
                 end
               end
             else
-              # Any other node type breaks contiguity
               unless current_defs.empty?
                 sections << {
                   visibility: current_visibility,
@@ -402,12 +427,11 @@ module RuboCop
                 }
                 current_defs = []
                 section_start = nil
-                current_visibility = nil
               end
             end
           end
 
-          # Handle trailing defs
+          # trailing defs
           unless current_defs.empty?
             sections << {
               visibility: current_visibility,
@@ -417,7 +441,20 @@ module RuboCop
             }
           end
 
-          sections
+          # -----------------------------------------------
+          # 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
         end
 
         # +RuboCop::Cop::SortedMethodsByCall::Waterfall#topo_sort+ -> Array<Symbol>, nil
@@ -470,7 +507,7 @@ module RuboCop
         # @return [Parser::Source::Range] Range covering leading comments + method body.
         def range_with_leading_comments(node)
           buffer = processed_source.buffer
-          expr   = node.source_range
+          expr = node.source_range
 
           start_line = expr.line
           lineno = start_line - 1

data/lib/rubocop/sorted_methods_by_call/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module SortedMethodsByCall
-    VERSION = '1.0.1'
+    VERSION = '1.1.1'
   end
 end

metadata

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