rubocop-callbacksystems 0.1.0

data/lib/rubocop/cop/callbacksystems/no_redundant_wrapper_method.rb

@@ -0,0 +1,161 @@
+# Detects private methods that only call another method or read a constant
+# without adding value. Such a wrapper is one more name for a reader to
+# resolve on the way to the thing it stands for, and it hides the call site
+# from whoever searches for the method it wraps. Public methods and predicates
+# are excluded as they often provide semantic value.
+#
+# @example
+#   # bad - private wrapper just calls another method
+#   private
+#     def find_all
+#       find(@node)
+#     end
+#
+#   # bad - private wrapper carries the name of the constant it reads
+#   MESSAGE = "Remove this."
+#
+#   private
+#     def message
+#       MESSAGE
+#     end
+#
+#   # good - read the constant where it is needed
+#   MESSAGE = "Remove this."
+#
+#   private
+#     def offense
+#       Offense.new(node, MESSAGE)
+#     end
+#
+#   # good - the method names a concept, and a subclass answers with its own constant
+#   private
+#     def marker_tag
+#       DEFAULT_MARKER_TAG
+#     end
+#
+#   # good - nothing in the class calls it, so a superclass or a subclass does
+#   private
+#     def path_after_saving
+#       root_path
+#     end
+#
+#   # good - read from several places, so it is the one spelling of that value
+#   private
+#     def scope
+#       account.widgets
+#     end
+#
+#   # good - public method (may be API or provide semantic meaning)
+#   def authenticated?
+#     resume_session
+#   end
+#
+#   # good - predicate provides semantic alias
+#   def fulfillable?
+#     paid?
+#   end
+#
+#   # good - method does something meaningful
+#   def find_all
+#     find(@node).compact
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoRedundantWrapperMethod < RuboCop::Cop::Callbacksystems::Base
+  def on_new_investigation
+    @method_calls = RuboCop::Callbacksystems::Methods::Calls.new(processed_source.ast)
+    @macro_referenced_methods = RuboCop::Callbacksystems::Methods::MacroReferences::ContainerIndex.new
+  end
+
+  def on_def(node)
+    if private_non_predicate?(node)
+      report WrapperMethod.new(node, method_calls:, macro_referenced_methods:)
+    end
+  end
+
+  alias on_defs on_def
+
+  private
+    attr_reader :macro_referenced_methods, :method_calls
+
+    class WrapperMethod
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Method `%<wrapper>s` only wraps `%<target>s` without adding value. Consider removing the indirection."
+
+      def initialize(node, method_calls:, macro_referenced_methods:)
+        @node = node
+        @method_calls = method_calls
+        @macro_referenced_methods = macro_referenced_methods
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if redundant? && inlineable?
+      end
+
+      private
+        attr_reader :node, :method_calls, :macro_referenced_methods
+        delegate :body, to: :node, private: true
+
+        def redundant?
+          wraps_a_call? || reads_a_constant?
+        end
+
+        def wraps_a_call?
+          body&.send_type? && simple_method_call? && arguments_are_pass_through?
+        end
+
+        def simple_method_call?
+          body.receiver.nil? || body.receiver.self_type?
+        end
+
+        def arguments_are_pass_through?
+          body.arguments.all? { passes_through?(it) }
+        end
+
+        def passes_through?(argument)
+          argument.ivar_type? || parameter_names_of(node).include?(spelling_of(argument))
+        end
+
+        def spelling_of(argument)
+          argument.lvar_type? ? argument.name.to_s : argument.source
+        end
+
+        def reads_a_constant?
+          body&.const_type? && node.arguments.empty? && named_after_the_constant?
+        end
+
+        # A method naming the constant something else states a concept, usually a hook a subclass answers with its own.
+        def named_after_the_constant?
+          node.method_name.to_s.upcase == body.short_name.to_s
+        end
+
+        def inlineable?
+          called_in_its_class? && !sole_spelling_of_a_value? && !macro_referenced?
+        end
+
+        # A private method nothing in its class calls is the hook a superclass or a subclass answers.
+        def called_in_its_class?
+          calls.any?
+        end
+
+        def calls
+          @calls ||= method_calls.named(node.method_name, from: node)
+        end
+
+        def sole_spelling_of_a_value?
+          node.arguments.empty? && calls.many?
+        end
+
+        def macro_referenced?
+          macro_referenced_methods.include?(node.method_name, beside: node)
+        end
+
+        def message
+          format(MESSAGE, wrapper: node.method_name, target: target)
+        end
+
+        def target
+          body.const_type? ? body.source : body.method_name
+        end
+    end
+end

data/lib/rubocop/cop/callbacksystems/no_section_divider_comments.rb

@@ -0,0 +1,105 @@
+# ASCII-art section dividers in comments add no information: a row of dashes,
+# equals, or box-drawing glyphs is noise to the toolchain and signals padding
+# over substance. A pure divider should be removed; a divider wrapping a title
+# (`=== Setup ===`) should keep only its inner text as a normal comment.
+#
+# @example
+#   # bad - a pure divider, here closing the statement it follows
+#   configure_defaults # ==========
+#
+#   # bad - a title wrapped in dividers
+#   # ===== Setup =====
+#
+#   # good - a plain comment
+#   # Setup
+#
+class RuboCop::Cop::Callbacksystems::NoSectionDividerComments < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_new_investigation
+    processed_source.comments.each { report DividerComment.new(it), rewrites_comments: true }
+  end
+
+  private
+    class DividerComment
+      include RuboCop::Callbacksystems::Helpers
+
+      PURE_MESSAGE = "Section-divider comments add no information. Remove."
+      WRAPPED_MESSAGE = "Strip the divider decorations; keep the inner text as a normal comment."
+      # `-=*_~#`, the dashes, and the Box Drawing and Block Elements blocks, by ordinal so this file stays ASCII.
+      DIVIDER_POINTS = Set[0x2D, 0x3D, 0x2A, 0x5F, 0x7E, 0x23, 0x2013, 0x2014]
+      DIVIDER_RANGE = (0x2500..0x259F)
+
+      def initialize(comment)
+        @comment = comment
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(comment, message) { correct(it) } if divider_comment?
+      end
+
+      private
+        attr_reader :comment
+
+        def divider_comment?
+          !tooling_comment?(comment) && (pure? || wrapped?)
+        end
+
+        def pure?
+          present? && only_divider_characters?(trimmed) && divider_run?(trimmed)
+        end
+
+        def present?
+          !trimmed.empty?
+        end
+
+        def trimmed
+          @trimmed ||= comment.text.delete_prefix("#").strip
+        end
+
+        def only_divider_characters?(text)
+          text.each_char.all? { divider_or_space?(it) }
+        end
+
+        def divider_or_space?(character)
+          divider?(character) || character.match?(/\s/)
+        end
+
+        def divider?(character)
+          DIVIDER_POINTS.include?(character.ord) || DIVIDER_RANGE.cover?(character.ord)
+        end
+
+        def divider_run?(text)
+          text.each_char.chunk_while { |left, right| divider?(left) && divider?(right) }
+            .any? { it.size >= 2 && divider?(it.first) }
+        end
+
+        def wrapped?
+          present? && !inner_text.nil?
+        end
+
+        def inner_text
+          @inner_text ||= strip_run(trimmed, side: :leading)&.then { strip_run(it, side: :trailing) }
+        end
+
+        def strip_run(text, side:)
+          characters = side == :leading ? text.each_char : text.reverse.each_char
+          run = characters.take_while { divider?(it) }
+          if run.size >= 2
+            side == :leading ? text[run.size..].lstrip : text[0...(text.size - run.size)].rstrip
+          end
+        end
+
+        def message
+          pure? ? PURE_MESSAGE : WRAPPED_MESSAGE
+        end
+
+        def correct(corrector)
+          if pure?
+            corrector.remove(comment_removal_range_for(comment))
+          else
+            corrector.replace(comment, "# #{inner_text}")
+          end
+        end
+    end
+end

data/lib/rubocop/cop/callbacksystems/no_send_in_tests.rb

@@ -0,0 +1,75 @@
+# Prohibits using `send` or `__send__` inside test blocks.
+# Private methods are private for a reason; tests should verify
+# behavior and outcomes, not call private methods directly.
+#
+# @example
+#   # bad
+#   test "processes payment" do
+#     result = order.send(:process_payment)
+#     assert result
+#   end
+#
+#   # bad
+#   test "processes payment" do
+#     order.__send__(:process_payment)
+#   end
+#
+#   # good - test the public interface
+#   test "processes payment" do
+#     order.checkout
+#     assert order.paid?
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoSendInTests < RuboCop::Cop::Callbacksystems::Base
+  include RuboCop::Callbacksystems::Testing::CopHelpers
+
+  def on_block(node)
+    report_each RestrictedCalls.new(node) if test_block?(node)
+  end
+
+  alias on_numblock on_block
+  alias on_itblock on_block
+
+  private
+    class RestrictedCalls
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Don't use `%<method>s` to test private methods. Test behavior through the public interface instead."
+      RESTRICTED_METHODS = %i[ send __send__ ]
+
+      def initialize(test_block)
+        @test_block = test_block
+      end
+
+      def each_offense
+        restricted_calls.each { yield RuboCop::Callbacksystems::Offense.new(it, message_for(it)) }
+      end
+
+      private
+        attr_reader :test_block
+
+        def restricted_calls
+          immediate_execution.select { restricted?(it) }
+        end
+
+        def immediate_execution
+          RuboCop::Callbacksystems::Execution::Immediate.new(test_block.body, deferred_blocks: deferred_blocks)
+        end
+
+        def deferred_blocks
+          nodes_in(test_block.body, :any_block).select { method_definition_block?(it) || nested_test_block?(it) }
+        end
+
+        def nested_test_block?(node)
+          any_block_type?(node) && bare_send?(call_of(node)) && call_of(node).method?(:test)
+        end
+
+        def restricted?(send_node)
+          send_node.call_type? && RESTRICTED_METHODS.include?(send_node.method_name) && !send_node.receiver.nil?
+        end
+
+        def message_for(send_node)
+          format(MESSAGE, method: send_node.method_name)
+        end
+    end
+end

data/lib/rubocop/cop/callbacksystems/no_service_objects.rb

@@ -0,0 +1,64 @@
+# Prohibits files in service object-style directories under `app/`. A service
+# is a verb with no noun, so the behavior it holds drifts away from the model
+# that owns the data it acts on, and the model is left anemic. The behavior
+# belongs to that model, or to a plain object in `app/models` named after the
+# concept it stands for.
+#
+# Only applies to Rails applications (paths under `app/`). Gems or libraries
+# that use directories like `commands/` or `queries/` outside of `app/` are
+# untouched.
+#
+# @example
+#   # bad - file in app/services/
+#   # app/services/order_processor.rb
+#
+#   # bad - file in app/decorators/
+#   # app/decorators/user_decorator.rb
+#
+#   # bad - file in app/interactors/
+#   # app/interactors/create_order.rb
+#
+#   # bad - file in app/presenters/
+#   # app/presenters/user_presenter.rb
+#
+#   # bad - file in app/forms/
+#   # app/forms/registration_form.rb
+#
+#   # good - use models
+#   # app/models/order.rb
+#
+#   # good - non-Rails gem with commands in lib/
+#   # lib/my_gem/commands/run.rb
+#
+class RuboCop::Cop::Callbacksystems::NoServiceObjects < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Files in `app/%<directory>s/` are not allowed. Use models or POROs in `app/models/` instead."
+
+  def on_new_investigation
+    forbidden_directory&.then { add_offense(offense_range, message: format(MESSAGE, directory: it)) }
+  end
+
+  private
+    FORBIDDEN_DIRECTORIES = %w[
+      services
+      decorators
+      interactors
+      presenters
+      forms
+      operations
+      commands
+      queries
+      use_cases
+    ]
+
+    def forbidden_directory
+      FORBIDDEN_DIRECTORIES.find { in_directory?(it) }
+    end
+
+    def in_directory?(directory)
+      processed_source.file_path.match?(%r{(^|/)app/#{Regexp.escape(directory)}/})
+    end
+
+    def offense_range
+      processed_source.ast || processed_source.buffer.source_range
+    end
+end

data/lib/rubocop/cop/callbacksystems/no_single_letter_names.rb

@@ -0,0 +1,47 @@
+# Detects single-letter names for variables, block arguments, and method
+# parameters. A single letter says nothing about what it holds, so a reader
+# has to go back to where it was assigned to learn what `i` or `e` stands for,
+# where a descriptive name answers on the spot.
+#
+# @example
+#   # bad
+#   x = 5
+#   items.each { |i| process(i) }
+#   def foo(n); end
+#   items.map { |e| e.name }
+#   hash.each { |k, v| puts k }
+#
+#   # good
+#   count = 5
+#   items.each { |item| process(item) }
+#   def foo(number); end
+#   items.map { |element| element.name }
+#   hash.each { |key, value| puts key }
+#
+#   # ok - underscore convention for unused
+#   items.each { |_| process }
+#   [1,2].each_with_index { |_, index| puts index }
+#
+class RuboCop::Cop::Callbacksystems::NoSingleLetterNames < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Avoid single-letter name `%<name>s`. Use a descriptive name instead."
+
+  def on_lvasgn(node)
+    name = variable_name_of(node)
+    add_offense(node, message: format(MESSAGE, name:)) if single_letter?(name)
+  end
+
+  alias on_arg on_lvasgn
+  alias on_optarg on_lvasgn
+  alias on_restarg on_lvasgn
+  alias on_kwarg on_lvasgn
+  alias on_kwoptarg on_lvasgn
+  alias on_kwrestarg on_lvasgn
+  alias on_blockarg on_lvasgn
+  alias on_match_var on_lvasgn
+  alias on_shadowarg on_lvasgn
+
+  private
+    def single_letter?(name)
+      name && name.length == 1 && !name.start_with?("_")
+    end
+end

data/lib/rubocop/cop/callbacksystems/no_singleton_class_in_modules.rb

@@ -0,0 +1,43 @@
+# Forbids using `class << self` inside modules.
+# Use `extend self` instead to define module-level methods.
+#
+# `class << self` in modules is an imperative way to define methods
+# when a more declarative `extend self` approach exists.
+#
+# @example
+#   # bad - using class << self in module
+#   module Calculator
+#     class << self
+#       def add(a, b)
+#         a + b
+#       end
+#     end
+#   end
+#
+#   # good - using extend self
+#   module Calculator
+#     extend self
+#
+#     def add(a, b)
+#       a + b
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoSingletonClassInModules < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Use `extend self` instead of `class << self` in modules."
+
+  def on_sclass(node)
+    add_offense(node, message: MESSAGE) if singleton_section?(node) && lexical_owner_of(node)&.module_type?
+  end
+
+  private
+    def lexical_owner_of(node)
+      node.each_ancestor.find { lexical_boundary?(it) }
+    end
+
+    # A block may be evaluated with another receiver (`included`, `class_eval`, and friends), so its `self` cannot be
+    # attributed to the module around the block from syntax alone.
+    def lexical_boundary?(node)
+      node.type?(:class, :module, :sclass, :def, :defs) || any_block_type?(node)
+    end
+end

data/lib/rubocop/cop/callbacksystems/no_tap_collection_building.rb

@@ -0,0 +1,173 @@
+# Detects using tap to build collections imperatively. A `tap` on an empty
+# collection is a loop that fills it by hand, so a reader has to run the block
+# to learn what comes out, where `map`, `select`, `index_by` or `group_by`
+# names the result in the call itself.
+#
+# @example
+#   # bad - building array with tap
+#   [].tap { |arr| items.each { |i| arr << i.name } }
+#
+#   # good - use map
+#   items.map { it.name }
+#
+#   # bad - building hash with tap
+#   {}.tap { |h| items.each { |i| h[i.id] = i } }
+#
+#   # good - use index_by or to_h
+#   items.index_by { it.id }
+#
+#   # bad - building Set with tap
+#   Set.new.tap { |s| items.each { |i| s << i.id } }
+#
+#   # good - use Set.new with block or to_set
+#   items.map(&:id).to_set
+#
+#   # bad - building Hash with default value and tap
+#   Hash.new { |h, k| h[k] = [] }.tap { |h| items.each { |i| h[i.type] << i } }
+#
+#   # good - use group_by
+#   items.group_by(&:type)
+#
+#   # ok - tap for logging (not collection building)
+#   user.tap { |u| logger.info(u.id) }
+#
+#   # ok - tap for configuring object
+#   User.new.tap { |u| u.name = "John" }
+#
+class RuboCop::Cop::Callbacksystems::NoTapCollectionBuilding < RuboCop::Cop::Callbacksystems::Base
+  def on_block(node)
+    report TapBlock.new(node)
+  end
+
+  alias on_numblock on_block
+  alias on_itblock on_block
+
+  private
+    class TapBlock
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Don't use `tap` to build collections. Use `map`, `select`, `index_by`, `group_by`, or `to_h` instead."
+      MUTATION_METHODS = %i[ << push append []= store merge! ]
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, MESSAGE) if tap_on_empty_collection? && mutation_in_block?
+      end
+
+      private
+        attr_reader :node
+
+        def tap_on_empty_collection?
+          node.method?(:tap) && CollectionReceiver.new(node.receiver).empty_collection?
+        end
+
+        def mutation_in_block?
+          RuboCop::Callbacksystems::Execution::Immediate.new(node.body).any? do |candidate|
+            candidate.call_type? && mutates_collection?(candidate)
+          end
+        end
+
+        def mutates_collection?(call)
+          MUTATION_METHODS.include?(call.method_name) && yielded_collection?(call.receiver)
+        end
+
+        def yielded_collection?(receiver)
+          directly_yielded_collection?(receiver) || stored_default_collection?(receiver)
+        end
+
+        def directly_yielded_collection?(receiver)
+          receiver&.lvar_type? && node.argument_list.any? { it.name == receiver.name } &&
+            !name_rebound_between?(receiver.name, node: receiver, boundary: node)
+        end
+
+        def stored_default_collection?(receiver)
+          receiver&.call_type? && receiver.method?(:[]) && directly_yielded_collection?(receiver.receiver) &&
+            StoredHashDefault.new(node.receiver).collection?
+        end
+    end
+
+    class StoredHashDefault
+      def initialize(block)
+        @block = block
+      end
+
+      def collection?
+        default_block? && stores_default? &&
+          CollectionReceiver.new(default_value).empty_collection?
+      end
+
+      private
+        attr_reader :block
+
+        def default_block?
+          block&.any_block_type? && argument_names.size == 2 && block.argument_list.all?(&:arg_type?)
+        end
+
+        def argument_names
+          @argument_names ||= block.argument_list.map(&:name)
+        end
+
+        def stores_default?
+          hash_argument_assigned? && key_argument_used?
+        end
+
+        def hash_argument_assigned?
+          assignment&.call_type? && assignment.method?(:[]=) && assignment.receiver&.lvar_type? &&
+            assignment.receiver.name == argument_names.first
+        end
+
+        def assignment
+          block.body
+        end
+
+        def key_argument_used?
+          key&.lvar_type? && key.name == argument_names.second
+        end
+
+        def key
+          assignment.first_argument
+        end
+
+        def default_value
+          assignment.last_argument
+        end
+    end
+
+    class CollectionReceiver
+      include RuboCop::Callbacksystems::Helpers
+
+      COLLECTION_CLASSES = %i[ Set Hash Array ]
+
+      def initialize(receiver)
+        @receiver = receiver
+      end
+
+      def empty_collection?
+        receiver && (empty_collection_literal?(receiver) || collection_class_constructor?)
+      end
+
+      private
+        attr_reader :receiver
+
+        def collection_class_constructor?
+          constructor.send_type? && collection_constructor? &&
+            constructor_without_entries?
+        end
+
+        def constructor
+          @constructor ||= call_of(receiver)
+        end
+
+        def collection_constructor?
+          constructor.method?(:new) && core_constant?(constructor.receiver) &&
+            COLLECTION_CLASSES.include?(constructor.receiver.short_name)
+        end
+
+        def constructor_without_entries?
+          constructor.arguments.empty? || constructor.receiver.short_name == :Hash
+        end
+    end
+end