rubocop-sorted_methods_by_call 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a05a73b134e3c92389b69552df981d71c730623059376b90029f1875bdf6945
-  data.tar.gz: cf522e97fabcf31eafb02ddf9b52980d9c681adc6f04bc297729dfe1f9f53af7
+  metadata.gz: 635807053b2df421a854cdc73001545451f8a7017623c93c6d6eb89bf304e172
+  data.tar.gz: cacd6163f57b4ee053b3053a950240b71bc2665b8bd93d6a4dba916d02490683
 SHA512:
-  metadata.gz: 2f5e49e6eefca4dcce2a4de646afae45292170f2389672fcc6a17120ac6d16d22e50e81fafaaf0c8e008300da816d1d886f4d43e5180ebe5c40b267d6a36e064
-  data.tar.gz: 7a0dc929281d31759bdef79d990d61427bc277421ae096df8f49662a04fd74fcae98b6f785912308d360ce35d9ac4a1a26947208c167265da00d0f240bd66f81
+  metadata.gz: 4bedcb4e198e0d75209bb286a15d55ba16ec3ea026cbc52769f7acb13bc8c8f118cac590d4ca7fd16bdfd82730e380c3d02782e6dbf24001fc4815f316928d2a
+  data.tar.gz: 05d4815fcce53e4c90e8b66ac1933363ec3a4940f551d6f0464a993b63b2b3af36ba8795be3bea7a34cb462ad9aa6f39da011a87f055ac5154e8e4174319ffab

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 15:18:01 UTC using RuboCop version 1.81.7.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -22,9 +22,9 @@ Gemspec/RequiredRubyVersion:
 # Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 61
+  Max: 60
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
@@ -45,10 +45,10 @@ Metrics/MethodLength:
 Metrics/PerceivedComplexity:
   Max: 22
 
-# Offense count: 11
+# Offense count: 12
 # 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.0)
+    rubocop-sorted_methods_by_call (1.1.0)
       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)
@@ -20,19 +22,18 @@
         * [Release Process](#release-process)
     * [Requirements](#requirements)
     * [Contributing](#contributing)
+    * [Documentation](#documentation)
     * [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
 
@@ -81,20 +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 method123
+    foo
   end
 
-  def well
+  def foo
     123
   end
 end
@@ -106,17 +115,22 @@ end
 
 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
 ```
@@ -129,26 +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
 
@@ -162,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
@@ -207,10 +202,14 @@ Bug reports and pull requests are welcome! Please follow these guidelines:
 
 Please ensure your code passes all tests and follows the existing style.
 
+## Documentation
+
+Code is covered with YARD docs, you can access online docs
+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
 
@@ -218,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.0"
+  VersionAdded: "1.1.0"
   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
@@ -102,6 +113,7 @@ module RuboCop
           names_set = names.to_set
           index_of = names.each_with_index.to_h
 
+          # Build complete call graph - find ALL method calls in ALL methods
           edges = []
           def_nodes.each do |def_node|
             local_calls(def_node, names_set).each do |callee|
@@ -172,20 +184,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
@@ -215,7 +213,7 @@ module RuboCop
           # No violation -> nothing to do
           return unless caller_name && callee_name
 
-          #            Find a visibility section that contains both names
+          # Find a visibility section that contains both names
           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)
@@ -228,11 +226,9 @@ module RuboCop
           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) }
@@ -245,7 +241,7 @@ module RuboCop
           sorted_def_sources = sorted_names.map { |name| ranges_by_name[name].source }
 
           # Reconstruct the section: keep the visibility modifier (if any) above the first def
-          visibility_node   = target_section[:visibility]
+          visibility_node = target_section[:visibility]
           visibility_source = visibility_node&.source.to_s
 
           new_content = if visibility_source.empty?
@@ -255,7 +251,7 @@ module RuboCop
                         end
 
           # Expand the replaced region:
-          # - if a visibility node exists, start from its begin_pos (so we replace it)
+          # - if a visibility node exists, start from its begin_pos
           # - otherwise, start from the earliest leading doc-comment of the defs
           section_begin =
             if visibility_node
@@ -306,6 +302,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
@@ -470,7 +467,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/extensions/util.rb

@@ -18,7 +18,7 @@ module RuboCop
       #   RuboCop::SortedMethodsByCall::Util.deep_merge(base, other)
       #   #=> { main: [:abc], class_T: [:hi, :h1] }
       #
-      # @param [Hash] hash  The base hash to merge from.
+      # @param [Hash] h  The base hash to merge from.
       # @param [Hash] other The hash to merge into +hash+.
       # @return [Hash] A new hash with accumulated values per key.
       # @see Hash#merge

data/lib/rubocop/sorted_methods_by_call/version.rb

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

data/rakelib/docs.rake

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'yard'
+require 'fileutils'
+
+GEM_NAME = Bundler.load_gemspec(Dir.glob('*.gemspec').first).name
+DOCS_REPO_NAME = "#{GEM_NAME}_docs".freeze
+DOCS_REPO_PATH = "../#{DOCS_REPO_NAME}".freeze
+
+namespace :docs do # rubocop:disable Metrics/BlockLength
+  desc 'Generate new docs and push them to repo'
+  task generate: :clean do
+    puts 'Generating docs...'
+    YARD::CLI::Yardoc.run
+    puts 'OK!'
+  end
+
+  desc 'Clean existing docs'
+  task :clean do
+    if File.directory?('doc')
+      FileUtils.rm_rf('doc')
+      puts 'Cleaned existing docs directory'
+    end
+  end
+
+  desc 'Pushes docs to github'
+  task push: :generate do
+    unless File.directory?(DOCS_REPO_PATH)
+      puts "Error: Docs repo not found at #{DOCS_REPO_PATH}"
+      puts 'Please clone the docs repo first:'
+      puts "  git clone git@github.com:unurgunite/#{DOCS_REPO_NAME}.git #{DOCS_REPO_PATH}"
+      exit 1
+    end
+
+    puts "Copying docs to #{DOCS_REPO_PATH}..."
+    FileUtils.mkdir_p('doc') unless File.directory?('doc')
+    FileUtils.cp_r('doc/.', DOCS_REPO_PATH)
+
+    puts 'Changing dir...'
+    Dir.chdir(DOCS_REPO_PATH) do
+      puts 'Checking git status...'
+      status_output = `git status --porcelain`
+
+      if status_output.strip.empty?
+        puts 'No changes to commit'
+      else
+        puts 'Committing git changes...'
+        puts `git add .`
+        commit_result = `git commit -m "Update docs for #{GEM_NAME} #{Time.now.utc.strftime('%Y-%m-%d %H:%M:%S UTC')}"`
+        puts commit_result
+
+        if $CHILD_STATUS.success?
+          puts 'Pushing to GitHub...'
+          push_result = `git push origin master 2>&1`
+          puts push_result
+          if $CHILD_STATUS.success?
+            puts 'Docs successfully pushed!'
+          else
+            puts 'Push failed!'
+            exit 1
+          end
+        else
+          puts 'Commit failed!'
+          exit 1
+        end
+      end
+    end
+  end
+
+  desc 'Generate and push docs in one command'
+  task deploy: :push
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-sorted_methods_by_call
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - unurgunite
@@ -160,6 +160,7 @@ files:
 - lib/rubocop/sorted_methods_by_call/extensions/util.rb
 - lib/rubocop/sorted_methods_by_call/plugin.rb
 - lib/rubocop/sorted_methods_by_call/version.rb
+- rakelib/docs.rake
 - test_project/.rubocop.test.yml
 - test_project/Gemfile
 homepage: https://github.com/unurgunite/rubocop-sorted_methods_by_call