rubocop-canon 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec9b67b96a586164140535f5e47bae25d02443a7f37094b0dd6fe8c2256d7d57
-  data.tar.gz: 79bebd07f1aec3b30061849a9c0166640eef0728756dc6eb477d47e17c5a9c69
+  metadata.gz: 24d224c2ecf5e361f702c300a79778baf8ad63247fb726cb8c39b89534d7dd3f
+  data.tar.gz: 8e4e0ca31f844a61bdba984c2efd2ccadb2d0ddea11693f38dc452c9b356e40c
 SHA512:
-  metadata.gz: 49faab8220e3b5c1fe4004566a664c19051848136a628245e7e30da3e5b072fed9b349089681831cd5efac7052e40dd788986e9827ee16569617c26a304b541c
-  data.tar.gz: d01f901f2b9748cf4617eb75a633930dd8c9049c1c45bd4c6379cce308ac1678f5fc41facb34a4d5da664b9ea1dbcfb5fbad15232eb90437921cf79f1fdea79b
+  metadata.gz: b1eea01a2c5652d7513ccfe08b048cd61817f4f20c3dcb757c5e7b0e96ac99c92d0b52f1840d40b69a9c3c5b2eced42444c22ae29ed3461eedc83c1dbd4b5081
+  data.tar.gz: 98f0a6237ae0b71995af7bf03e8d8b46bcf83ebd92f3fa0ddf81f607a503ab71061b365f2e19a05279702791998be00d7cd1d621224dcdd965ae79d2d3fc2d84

data/README.md

@@ -6,7 +6,10 @@ Deterministic RuboCop cops that reduce Ruby code to canonical form. Given any in
 
 | Cop | What it does |
 |-----|-------------|
+| `Canon/BlockPhases` | A block body ends in one unbroken run of calls, opened by one blank line |
+| `Canon/DeclarationGroups` | One blank line between declaration groups, none inside a group |
 | `Canon/KeywordShorthand` | `foo(bar: bar)` becomes `foo(bar:)` |
+| `Canon/MethodBodyBlankLines` | One blank line around a method body's standalone calls, none anywhere else |
 | `Canon/SortHash` | `{b: 1, a: 2}` becomes `{a: 2, b: 1}` |
 | `Canon/SortKeywords` | `method(z: 1, a: 2)` becomes `method(a: 2, z: 1)` |
 | `Canon/SortMethodArguments` | `attr_reader :z, :a` becomes `attr_reader :a, :z` |
@@ -29,6 +32,32 @@ plugins:
 
 ## Configuration
 
+The blank-line cops are driven by name lists:
+
+```yaml
+Canon/BlockPhases:
+  Blocks:                   # only check blocks of these methods (required)
+    - it
+  TrailingMethods:          # calls that make up the trailing phase (required)
+    - expect
+  MaxPhases: 3              # phases allowed before the trailing one
+
+Canon/DeclarationGroups:
+  GroupedMethods:           # method names that form one group
+    - [belongs_to, has_many, has_one]
+    - [validate, validates]
+
+Canon/MethodBodyBlankLines:
+  SeparatedMethods:         # calls that take a blank line beside them
+    - expose
+    - mail
+    - errors.add            # dotted: matches a receiver and method together
+```
+
+`Canon/BlockPhases` does nothing without both lists. `Canon/DeclarationGroups` treats every
+method name as its own group until `GroupedMethods` merges them. `Canon/MethodBodyBlankLines`
+only removes blank lines until `SeparatedMethods` says where they belong.
+
 `Canon/SortHash` and the three sort cops accept:
 
 ```yaml
@@ -49,7 +78,7 @@ Canon/SortMethodArguments:
     - delegate
 ```
 
-`Canon/SortKeywords` and `Canon/SortMethodArguments` are disabled by default. They require a `Methods` list to function.
+Every cop is disabled by default. Enable the ones you want in your `.rubocop.yml`.
 
 ## License
 

data/config/default.yml

@@ -1,11 +1,31 @@
+Canon/BlockPhases:
+  Description: 'Separate a block body into phases, ending in a trailing run of calls.'
+  Enabled: false
+  VersionAdded: '0.2'
+  Blocks: []
+  MaxPhases: 3
+  TrailingMethods: []
+
+Canon/DeclarationGroups:
+  Description: 'Separate declaration groups with one blank line and nothing inside a group.'
+  Enabled: false
+  VersionAdded: '0.2'
+  GroupedMethods: []
+
 Canon/KeywordShorthand:
   Description: 'Use Ruby 3.1+ keyword shorthand where a local variable matches the key name.'
-  Enabled: true
+  Enabled: false
   VersionAdded: '0.1'
 
+Canon/MethodBodyBlankLines:
+  Description: "One blank line around a method body's standalone calls, none anywhere else."
+  Enabled: false
+  VersionAdded: '0.2'
+  SeparatedMethods: []
+
 Canon/SortHash:
   Description: 'Sort hash keys alphabetically.'
-  Enabled: true
+  Enabled: false
   VersionAdded: '0.1'
   ShorthandsFirst: false
   ExcludeMethods: []
@@ -25,5 +45,5 @@ Canon/SortMethodArguments:
 
 Canon/SortMethodDefinition:
   Description: 'Sort keyword arguments in method definitions alphabetically.'
-  Enabled: true
+  Enabled: false
   VersionAdded: '0.1'

data/lib/rubocop/canon/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Canon
-    VERSION = '0.1.0'
+    VERSION = '0.2.1'
   end
 end

data/lib/rubocop/cop/canon/blank_line_help.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Canon
+      # Shared mechanics for the cops that decide where a blank line belongs.
+      #
+      # A cop mixing this in supplies the decision — how many blank lines a
+      # pair of statements takes — and leaves the counting, the comment guard,
+      # the source ranges and the corrections here.
+      module BlankLineHelp
+        include RangeHelp
+
+        BLOCK_TYPES = %i[block numblock].freeze
+
+        private
+
+        def body_statements(node)
+          body = node.body
+          return [] if body.nil?
+          return body.children if body.begin_type?
+
+          [body]
+        end
+
+        def blank_lines_between(previous, following)
+          following.first_line - previous.last_line - 1
+        end
+
+        def comments_between?(previous, following)
+          processed_source.comments.any? do |comment|
+            comment.loc.line >= previous.last_line && comment.loc.line < following.first_line
+          end
+        end
+
+        def register_extra_blank_line(previous, message)
+          add_offense(blank_line_range(previous), message:) do |corrector|
+            corrector.remove(newline_range(previous))
+          end
+        end
+
+        def register_missing_blank_line(previous, following, message)
+          add_offense(first_line_range(following), message:) do |corrector|
+            corrector.insert_after(line_range(previous.last_line), "\n")
+          end
+        end
+
+        def call_chain(node)
+          chain = []
+          current = unwrap_block(node)
+
+          while current.respond_to?(:send_type?) && current.send_type?
+            chain.unshift(current.method_name.to_s)
+            current = unwrap_block(current.receiver)
+          end
+
+          chain
+        end
+
+        def unwrap_block(node)
+          return if node.nil?
+          return node.send_node if BLOCK_TYPES.include?(node.type)
+
+          node
+        end
+
+        def line_range(line)
+          processed_source.buffer.line_range(line)
+        end
+
+        def blank_line_range(previous)
+          line_range(previous.last_line + 1)
+        end
+
+        def newline_range(previous)
+          range_between(line_range(previous.last_line).end_pos, line_range(previous.last_line + 1).end_pos)
+        end
+
+        def first_line_range(node)
+          line_end = line_range(node.first_line).end_pos
+
+          range_between(node.source_range.begin_pos, [node.source_range.end_pos, line_end].min)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/canon/block_phases.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Canon
+      # Enforces the phase structure of a block body.
+      #
+      # A body checked by this cop ends in a *trailing phase*: the run of
+      # statements that call one of `TrailingMethods`. Exactly one blank line
+      # opens that run, no blank line splits it, and the statements before it
+      # form at most `MaxPhases` - 1 further phases.
+      #
+      # `Blocks` names the methods whose blocks are checked and
+      # `TrailingMethods` the calls that make up the trailing phase, matched
+      # against the leftmost call in a chain. Both are empty by default, so
+      # the cop does nothing until it is configured.
+      #
+      # A body carrying more phases than `MaxPhases` allows keeps the last
+      # separator before the trailing phase and loses the earlier ones —
+      # everything ahead of the last leading statement is one phase.
+      #
+      # @example Blocks: ['step'], TrailingMethods: ['report']
+      #   # bad — no blank line opens the trailing phase
+      #   step 'totals the order' do
+      #     order = build_order
+      #     report order.total
+      #   end
+      #
+      #   # bad — a blank line splits the trailing phase
+      #   step 'totals the order' do
+      #     order = build_order
+      #
+      #     report order.total
+      #
+      #     report order.currency
+      #   end
+      #
+      #   # good
+      #   step 'totals the order' do
+      #     order = build_order
+      #
+      #     report order.total
+      #     report order.currency
+      #   end
+      class BlockPhases < Base
+        extend AutoCorrector
+        include BlankLineHelp
+
+        MSG_EXTRA = 'Remove the blank line inside the trailing phase.'
+        MSG_MISSING = 'Add a blank line before the trailing phase.'
+        MSG_TOO_MANY_PHASES = 'Use at most %<max_phases>d phases in a block body.'
+
+        def on_block(node)
+          return unless configured_block?(node)
+
+          check_phases(node)
+        end
+
+        alias on_numblock on_block
+
+        private
+
+        def check_phases(node)
+          statements = body_statements(node)
+          return if statements.size < 2
+
+          trailing_start = detect_trailing_start(statements)
+          return if trailing_start.nil?
+
+          check_trailing_phase(statements, trailing_start)
+          check_leading_phases(statements, trailing_start)
+        end
+
+        def check_trailing_phase(statements, trailing_start)
+          statements[trailing_start..].each_cons(2) do |previous, following|
+            next if comments_between?(previous, following)
+            next if blank_lines_between(previous, following) != 1
+
+            register_extra_blank_line(previous, MSG_EXTRA)
+          end
+        end
+
+        def check_leading_phases(statements, trailing_start)
+          return if trailing_start.zero?
+
+          check_separator(statements[trailing_start - 1], statements[trailing_start])
+          check_phase_count(statements[..(trailing_start - 1)])
+        end
+
+        def check_separator(previous, following)
+          return if comments_between?(previous, following)
+          return if blank_lines_between(previous, following) == 1
+
+          register_missing_blank_line(previous, following, MSG_MISSING)
+        end
+
+        def check_phase_count(statements)
+          separators = leading_separators(statements)
+          return if separators.size < max_phases - 1
+
+          surplus = separators[0..-(max_phases - 1)]
+
+          surplus.each do |previous|
+            register_extra_blank_line(previous, format(MSG_TOO_MANY_PHASES, max_phases:))
+          end
+        end
+
+        def leading_separators(statements)
+          statements.each_cons(2).filter_map do |previous, following|
+            next if comments_between?(previous, following)
+
+            previous if blank_lines_between(previous, following) == 1
+          end
+        end
+
+        def detect_trailing_start(statements)
+          trailing_start = nil
+
+          statements.each_with_index.reverse_each do |statement, index|
+            break unless trailing?(statement)
+
+            trailing_start = index
+          end
+
+          trailing_start
+        end
+
+        def configured_block?(node)
+          return false unless node.send_node.receiver.nil?
+
+          block_methods.include?(node.method_name.to_s)
+        end
+
+        def trailing?(node)
+          chain = call_chain(node)
+          return false if chain.empty?
+
+          trailing_methods.include?(chain.first)
+        end
+
+        def block_methods
+          @block_methods ||= Array(cop_config['Blocks']).map(&:to_s)
+        end
+
+        def trailing_methods
+          @trailing_methods ||= Array(cop_config['TrailingMethods']).map(&:to_s)
+        end
+
+        def max_phases
+          cop_config['MaxPhases']
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/canon/declaration_groups.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Canon
+      # Enforces blank lines between declaration groups in a class, module or
+      # DSL block body.
+      #
+      # `GroupedMethods` is the whole specification: two declarations calling
+      # methods listed in the same group take no blank line between them, and
+      # two calling methods listed in different groups take exactly one. The
+      # cop says nothing about a method name it has not been given, so a DSL
+      # it does not know stays as its author wrote it.
+      #
+      # A block is a group of one whatever it calls, so a DSL block always
+      # stands apart from the declarations around it. Everything else the cop
+      # has not been told about — an unlisted method name, a constant — it
+      # leaves alone.
+      #
+      # @example GroupedMethods: [[belongs_to, has_many], [validate, validates]]
+      #   # bad
+      #   class Shift < ApplicationRecord
+      #     belongs_to :site
+      #
+      #     has_many :shift_assignments, dependent: :destroy
+      #     validates :starts_at, presence: true
+      #   end
+      #
+      #   # good
+      #   class Shift < ApplicationRecord
+      #     belongs_to :site
+      #     has_many :shift_assignments, dependent: :destroy
+      #
+      #     validates :starts_at, presence: true
+      #   end
+      #
+      #   # good — neither name is listed, so the cop leaves the body alone
+      #   class Filtering < Capability::Base
+      #     request_transformer RequestTransformer
+      #     api_builder APIBuilder
+      #   end
+      class DeclarationGroups < Base
+        extend AutoCorrector
+        include BlankLineHelp
+
+        MSG_EXTRA = 'Remove the blank line between declarations of the same group.'
+        MSG_MISSING = 'Add a blank line between declaration groups.'
+        ACCESS_MODIFIERS = %i[private protected public module_function private_class_method].freeze
+        DEFINITION_TYPES = %i[def defs].freeze
+        BLOCK_TYPES = %i[block numblock].freeze
+        STANDALONE_TYPES = %i[block numblock def defs].freeze
+
+        def on_class(node)
+          check_declarations(node)
+        end
+
+        def on_module(node)
+          check_declarations(node)
+        end
+
+        def on_block(node)
+          return unless declaration_context?(node)
+
+          check_declarations(node)
+        end
+
+        alias on_numblock on_block
+
+        private
+
+        def check_declarations(node)
+          statements = body_statements(node)
+          return if statements.size < 2
+          return unless statements.all? { |statement| declaration?(statement) }
+
+          statements.each_cons(2) do |previous, following|
+            next if definitions?(previous, following)
+            next if access_modifier?(previous)
+            next if access_modifier?(following)
+            next unless grouped?(previous, following)
+
+            check_gap(previous, following, expected_blank_lines(previous, following))
+          end
+        end
+
+        def check_gap(previous, following, expected)
+          return if comments_between?(previous, following)
+
+          blank_lines = blank_lines_between(previous, following)
+          return if blank_lines == expected
+          return if blank_lines > 1
+
+          return register_extra_blank_line(previous, MSG_EXTRA) if expected.zero?
+
+          register_missing_blank_line(previous, following, MSG_MISSING)
+        end
+
+        def grouped?(previous, following)
+          return true if standalone?(previous)
+          return true if standalone?(following)
+          return false if group_key(previous).nil?
+
+          !group_key(following).nil?
+        end
+
+        def expected_blank_lines(previous, following)
+          return 1 if standalone?(previous)
+          return 1 if standalone?(following)
+          return 0 if group_key(previous) == group_key(following)
+
+          1
+        end
+
+        def standalone?(node)
+          STANDALONE_TYPES.include?(node.type)
+        end
+
+        def group_key(node)
+          return unless node.send_type?
+
+          grouped_methods.index { |group| group.include?(node.method_name.to_s) }
+        end
+
+        def declaration_context?(node)
+          enclosing = node.each_ancestor(:def, :defs, :class, :module).first
+          return false if enclosing.nil?
+          return true if enclosing.class_type?
+
+          enclosing.module_type?
+        end
+
+        def declaration?(node)
+          return true if node.casgn_type?
+          return true if DEFINITION_TYPES.include?(node.type)
+          return node.send_node.receiver.nil? if BLOCK_TYPES.include?(node.type)
+
+          node.send_type? && node.receiver.nil?
+        end
+
+        def definitions?(previous, following)
+          DEFINITION_TYPES.include?(previous.type) && DEFINITION_TYPES.include?(following.type)
+        end
+
+        def access_modifier?(node)
+          return false unless node.send_type?
+          return false unless node.arguments.empty?
+
+          ACCESS_MODIFIERS.include?(node.method_name)
+        end
+
+        def grouped_methods
+          @grouped_methods ||= Array(cop_config['GroupedMethods']).map { |group| Array(group).map(&:to_s) }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/canon/method_body_blank_lines.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Canon
+      # Enforces blank lines around a method body's standalone calls and
+      # nowhere else.
+      #
+      # `SeparatedMethods` names the calls that stand on their own —
+      # `authorize!`, `expose`, `mail`. Each takes exactly one blank line
+      # between it and any statement next to it. Every other pair of
+      # statements takes none, because a blank line there marks a step that
+      # wants a name: extract a method instead.
+      #
+      # The list is empty by default, so the cop only removes until it is
+      # configured.
+      #
+      # The position after a guard clause belongs to
+      # `Layout/EmptyLineAfterGuardClause`, so this cop leaves it alone.
+      #
+      # An entry matches a method name anywhere in the call chain. Write it
+      # dotted — `errors.add` — to match a receiver and method together, so
+      # `coverage_request.errors.add(...)` matches and a bare `add` does not.
+      #
+      # @example SeparatedMethods: ['authorize!', 'expose']
+      #   # bad
+      #   def index
+      #     authorize!
+      #     shift = find_shift
+      #     employees = Employee.for_shift(shift)
+      #     expose employees
+      #   end
+      #
+      #   # good
+      #   def index
+      #     authorize!
+      #
+      #     shift = find_shift
+      #     employees = Employee.for_shift(shift)
+      #
+      #     expose employees
+      #   end
+      #
+      #   # good — no standalone call, so no blank line
+      #   def reset
+      #     Current.session = nil
+      #     Current.account = nil
+      #   end
+      #
+      #   # good — the guard clause owns its own blank line
+      #   def total
+      #     items = order.items
+      #     return 0 if items.empty?
+      #
+      #     items.sum(&:amount)
+      #   end
+      class MethodBodyBlankLines < Base
+        extend AutoCorrector
+        include BlankLineHelp
+
+        MSG_EXTRA = 'Remove the blank line inside the method body.'
+        MSG_MISSING = 'Add a blank line around the standalone call.'
+        JUMP_METHODS = %i[raise fail throw].freeze
+
+        def on_def(node)
+          check_method_body(node)
+        end
+
+        def on_defs(node)
+          check_method_body(node)
+        end
+
+        private
+
+        def check_method_body(node)
+          statements = body_statements(node)
+          return if statements.size < 2
+
+          statements.each_cons(2) do |previous, following|
+            next if guard?(previous)
+
+            check_gap(previous, following, expected_blank_lines(previous, following))
+          end
+        end
+
+        def check_gap(previous, following, expected)
+          return if comments_between?(previous, following)
+
+          blank_lines = blank_lines_between(previous, following)
+          return if blank_lines == expected
+          return if blank_lines > 1
+
+          return register_extra_blank_line(previous, MSG_EXTRA) if expected.zero?
+
+          register_missing_blank_line(previous, following, MSG_MISSING)
+        end
+
+        def expected_blank_lines(previous, following)
+          return 1 if separated?(previous)
+          return 1 if separated?(following)
+
+          0
+        end
+
+        def separated?(node)
+          chain = call_chain(node)
+          return false if chain.empty?
+
+          separated_methods.any? { |name| matches_chain?(chain, name) }
+        end
+
+        def matches_chain?(chain, name)
+          return chain.include?(name) unless name.include?('.')
+
+          chain.each_cons(2).any? { |pair| pair.join('.') == name }
+        end
+
+        def guard?(node)
+          return true if jump?(node)
+          return false unless node.if_type?
+          return false unless node.modifier_form?
+          return true if jump?(node.if_branch)
+
+          jump?(node.else_branch)
+        end
+
+        def jump?(node)
+          return false if node.nil?
+          return true if node.return_type?
+          return true if node.break_type?
+          return true if node.next_type?
+
+          node.send_type? && JUMP_METHODS.include?(node.method_name)
+        end
+
+        def separated_methods
+          @separated_methods ||= Array(cop_config['SeparatedMethods']).map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop-canon.rb

@@ -3,7 +3,11 @@
 require 'rubocop'
 require_relative 'rubocop/canon/version'
 require_relative 'rubocop/canon/plugin'
+require_relative 'rubocop/cop/canon/blank_line_help'
+require_relative 'rubocop/cop/canon/block_phases'
+require_relative 'rubocop/cop/canon/declaration_groups'
 require_relative 'rubocop/cop/canon/keyword_shorthand'
+require_relative 'rubocop/cop/canon/method_body_blank_lines'
 require_relative 'rubocop/cop/canon/sort_hash'
 require_relative 'rubocop/cop/canon/sort_keywords'
 require_relative 'rubocop/cop/canon/sort_method_arguments'

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-canon
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: lint_roller
   requirement: !ruby/object:Gem::Requirement
@@ -56,7 +70,11 @@ files:
 - lib/rubocop-canon.rb
 - lib/rubocop/canon/plugin.rb
 - lib/rubocop/canon/version.rb
+- lib/rubocop/cop/canon/blank_line_help.rb
+- lib/rubocop/cop/canon/block_phases.rb
+- lib/rubocop/cop/canon/declaration_groups.rb
 - lib/rubocop/cop/canon/keyword_shorthand.rb
+- lib/rubocop/cop/canon/method_body_blank_lines.rb
 - lib/rubocop/cop/canon/sort_hash.rb
 - lib/rubocop/cop/canon/sort_keywords.rb
 - lib/rubocop/cop/canon/sort_method_arguments.rb
@@ -84,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Deterministic RuboCop cops for canonical Ruby form