rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,173 @@
+# Prohibits returning a local variable as the last statement of a method. The
+# variable is a name for the value the method already hands back, so the last
+# line reads as a summary of the ones above it, and the whole body is a
+# `tap`, a `then` or an `each_with_object` spelled out by hand.
+#
+# @example
+#   # bad - returning a local variable
+#   def process
+#     result = calculate_something
+#     result
+#   end
+#
+#   # bad - assign, mutate, return
+#   def process
+#     result = []
+#     result << item
+#     result
+#   end
+#
+#   # bad - explicit return of local variable
+#   def process
+#     result = {}
+#     result[:key] = value
+#     return result
+#   end
+#
+#   # good - return the expression directly
+#   def process
+#     calculate_something
+#   end
+#
+#   # good - use tap
+#   def process
+#     [].tap do |result|
+#       result << item
+#     end
+#   end
+#
+#   # good - use each_with_object
+#   def process
+#     items.each_with_object([]) do |item, result|
+#       result << transform(item)
+#     end
+#   end
+#
+#   # good - use then
+#   def process
+#     calculate_something.then do |result|
+#       result.merge(extra: value)
+#     end
+#   end
+#
+#   # good - declarative approach
+#   def process
+#     [item]
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoLocalVariableReturn < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_def(node)
+    last_statement_in(node.body)&.then do |statement|
+      report ReturnedLocal.new(statement, source_comments: RuboCop::Callbacksystems::Source::Comments.for(processed_source))
+    end
+  end
+
+  alias on_defs on_def
+
+  private
+    class ReturnedLocal
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Avoid returning a local variable. " \
+        "Return the expression directly, or use `.tap`, `.then`, or `each_with_object`."
+      SCOPE_REFLECTION_METHODS = %i[ binding eval local_variables ]
+
+      def initialize(node, source_comments:)
+        @node = node
+        @source_comments = source_comments
+      end
+
+      def offense
+        if variable&.lvar_type? && assigned?
+          RuboCop::Callbacksystems::Offense.new(node, MESSAGE, correcting: inlineable?) { correct(it) }
+        end
+      end
+
+      private
+        attr_reader :node, :source_comments
+
+        def variable
+          @variable ||= returned_expression_of(node)
+        end
+
+        # A parameter handed back as it came is not a value computed and then returned.
+        def assigned?
+          occurrences.any? { it.type?(:lvasgn, :match_var) }
+        end
+
+        def occurrences
+          @occurrences ||= RuboCop::Callbacksystems::Execution::LocalVariableOccurrences.new(method_node)
+            .named_in_method(variable.name, around: node)
+        end
+
+        def method_node
+          @method_node ||= enclosing_method_of(node)
+        end
+
+        # A heredoc keeps its body on the lines past the assignment, so inlining the opener would leave the body behind.
+        def inlineable?
+          assignment && only_read_once? && scope_preserved? && source_preserved?
+        end
+
+        def assignment
+          @assignment ||= statements_before(node).last(1).find { it.lvasgn_type? && it.name == variable.name }
+        end
+
+        def only_read_once?
+          occurrences.one?(&:lvar_type?) && occurrences.one?(&:lvasgn_type?) && occurrences.none?(&:match_var_type?)
+        end
+
+        def scope_preserved?
+          !captured_by_deferred_callable? && !reflects_on_local_scope?
+        end
+
+        def captured_by_deferred_callable?
+          RuboCop::Callbacksystems::Execution::DeferredLocalVariables.new(method_node.body).include?(variable.name)
+        end
+
+        # Removing the assignment removes its name from bindings even when Ruby source never reads that name directly.
+        def reflects_on_local_scope?
+          nodes_in(method_node.body, :send, :csend).any? do |call|
+            SCOPE_REFLECTION_METHODS.include?(call.method_name) && scope_reader?(call)
+          end
+        end
+
+        def scope_reader?(call)
+          call_on_self?(call) || (core_constant?(call.receiver) && call.receiver.short_name == :Kernel)
+        end
+
+        def source_preserved?
+          !carries_heredoc?(assignment.expression) && !reads_source_line? && !moves_tooling_comment? &&
+            !assignment_trailing_comment?
+        end
+
+        def reads_source_line?
+          assignment.expression.source.include?("__LINE__")
+        end
+
+        def moves_tooling_comment?
+          source_comments.tooling_within?(assignment.source_range.join(node.source_range))
+        end
+
+        def assignment_trailing_comment?
+          source_comments.trailing_comment_on(assignment.last_line).present?
+        end
+
+        def correct(corrector)
+          corrector.remove(assignment_removal_range)
+          corrector.replace(node, replacement)
+        end
+
+        def assignment_removal_range
+          inline_statement_removal_range_for(assignment) ||
+            blank_line_below(line_removal_range_for(assignment)) ||
+            line_removal_range_for(assignment)
+        end
+
+        def replacement
+          node.return_type? ? "return #{assignment.expression.source}" : assignment.expression.source
+        end
+    end
+end

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

@@ -0,0 +1,188 @@
+# Detects an empty collection filled by hand inside an `each`. An empty array
+# or hash assigned to a variable and then filled from a loop is a `map`,
+# `select`, `filter_map`, `index_by` or `to_h` spread over two statements, so
+# a reader has to run the loop in their head to learn what the collection
+# holds, where the declarative call names it. The collection may be a local or
+# an instance variable, and it need not be returned afterwards. The mutation
+# may sit under `if`, `unless` or `case` branches, as long as every statement
+# the body reaches is that mutation. A loop with any other statement, or one
+# leaving through `next`, `break`, `return` or `raise`, is left alone, since
+# the declarative form would drop that behavior.
+#
+# @example
+#   # bad - array accumulation returned by the method
+#   def names
+#     results = []
+#     items.each { |x| results << x.name }
+#     results
+#   end
+#
+#   # good - use map
+#   def names
+#     items.map { it.name }
+#   end
+#
+#   # bad - array accumulation with a guard
+#   results = []
+#   items.each { |x| results << x.name if x.active? }
+#
+#   # good - use select or filter_map
+#   results = items.filter_map { it.name if it.active? }
+#
+#   # bad - array filled by index
+#   results = []
+#   items.each_with_index { |x, index| results[index] = x.name }
+#
+#   # good - use map
+#   results = items.map { it.name }
+#
+#   # bad - hash accumulation into an instance variable
+#   @index = {}
+#   items.each { |x| @index[x.id] = x }
+#
+#   # good - use index_by or to_h
+#   @index = items.index_by { it.id }
+#
+class RuboCop::Cop::Callbacksystems::NoManualAccumulation < RuboCop::Cop::Callbacksystems::Base
+  LOOP_METHODS = %i[ each each_with_index ]
+
+  def on_block(node)
+    report Accumulation.new(node) if LOOP_METHODS.include?(node.method_name)
+  end
+
+  alias on_numblock on_block
+  alias on_itblock on_block
+
+  private
+    # A loop filling an empty collection that an earlier statement in the same list assigned.
+    class Accumulation
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGES = {
+        array: "Don't fill an array with `%<loop>s`. Use `map`, `select` or `filter_map` instead.",
+        hash: "Don't fill a hash with `%<loop>s`. Use `index_by` or `to_h` instead."
+      }
+      MUTATORS = { array: %i[ << push append []= store ], hash: %i[ []= store merge! ] }
+
+      def initialize(loop_block)
+        @loop_block = loop_block
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(loop_block.send_node, message) if accumulator && keeps_flow?
+      end
+
+      private
+        attr_reader :loop_block
+        delegate :body, to: :loop_block, private: true
+
+        def accumulator
+          @accumulator ||= empty_collection_assignments_before.find { fills?(it) }
+        end
+
+        def empty_collection_assignments_before
+          preceding_statements.select { empty_collection_assignment?(it) && !reassigned_after?(it) }
+        end
+
+        def preceding_statements
+          @preceding_statements ||= statements_before(loop_block)
+        end
+
+        def empty_collection_assignment?(statement)
+          statement.type?(:lvasgn, :ivasgn) && empty_collection_literal?(statement.expression)
+        end
+
+        def reassigned_after?(assignment)
+          preceding_statements.drop_while { !it.equal?(assignment) }.drop(1).any? do |statement|
+            reassigned_within?(statement, assignment)
+          end
+        end
+
+        def reassigned_within?(statement, assignment)
+          RuboCop::Callbacksystems::Execution::Immediate.new(statement).nodes_of_type(assignment.type).any? do |node|
+            node.name == assignment.name && !rebound_local?(node, assignment)
+          end
+        end
+
+        def rebound_local?(candidate, assignment)
+          assignment.lvasgn_type? &&
+            name_rebound_between?(assignment.name, node: candidate, boundary: loop_block.parent)
+        end
+
+        # A statement beyond the mutation is a side effect `map` or `select` would drop, so such a loop is left alone.
+        def fills?(assignment)
+          leaves.any? && leaves.all? { mutation_of?(assignment, it) }
+        end
+
+        def leaves
+          @leaves ||= Leaves.new(body).to_a
+        end
+
+        def mutation_of?(assignment, leaf)
+          leaf.call_type? && reads_variable?(leaf.receiver, assignment.name) && mutator_of?(assignment, leaf)
+        end
+
+        def mutator_of?(assignment, call)
+          MUTATORS[kind_of(assignment)].include?(call.method_name)
+        end
+
+        def kind_of(assignment)
+          assignment.expression.type
+        end
+
+        def keeps_flow?
+          RuboCop::Callbacksystems::Execution::Immediate.new(body).none? do |node|
+            node.type?(:next, :break, :return) || raise?(node)
+          end
+        end
+
+        def raise?(node)
+          bare_send?(node) && node.method?(:raise)
+        end
+
+        def message
+          format(MESSAGES[kind_of(accumulator)], loop: loop_block.method_name)
+        end
+
+        # Terminal statements reached through conditional branches, in the order the source presents them.
+        class Leaves
+          include Enumerable
+          include RuboCop::Callbacksystems::Helpers
+
+          def initialize(body)
+            @body = body
+          end
+
+          def each
+            if block_given?
+              pending = statements_in(body).reverse
+              until pending.empty?
+                statement = pending.pop
+                if branching?(statement)
+                  branches_of(statement).reverse_each { pending.concat(statements_in(it).reverse) }
+                else
+                  yield statement
+                end
+              end
+            else
+              to_enum(__method__)
+            end
+          end
+
+          private
+            attr_reader :body
+
+            def branching?(statement)
+              statement.type?(:if, :case)
+            end
+
+            def branches_of(statement)
+              if statement.if_type?
+                [ statement.if_branch, statement.else_branch ]
+              else
+                [ *statement.when_branches.map(&:body), statement.else_branch ]
+              end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,145 @@
+# Detects memoization mixed with other statements in the same method. A
+# memoized method reads as a value, so a statement beside the `||=` runs on the
+# first read and never again, an effect hidden behind a getter that the caller
+# has no way to see. Conditional memoization (with if/unless) and rescue
+# blocks are allowed.
+#
+# @example
+#   # bad - memoization with other statements before
+#   def user
+#     validate_params
+#     @user ||= User.find(params[:id])
+#   end
+#
+#   # bad - memoization with other statements after
+#   def user
+#     @user ||= User.find(params[:id])
+#     log_access
+#   end
+#
+#   # good - memoization is the entire method body
+#   def user
+#     @user ||= User.find(params[:id])
+#   end
+#
+#   # good - conditional memoization
+#   def period
+#     @period ||= compute_period if params[:starts_on].present?
+#   end
+#
+#   # good - memoization with rescue
+#   def processor
+#     @processor ||= find_processor
+#   rescue ActiveRecord::RecordNotFound
+#     nil
+#   end
+#
+#   # good - complex computation inside the memoization
+#   def user
+#     @user ||= begin
+#       data = fetch_data
+#       process(data)
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoMixedMemoization < RuboCop::Cop::Callbacksystems::Base
+  def on_def(node)
+    report MemoizationBody.new(node)
+  end
+
+  alias on_defs on_def
+
+  private
+    class MemoizationBody
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Memoization should be the entire method body. Extract other statements to separate methods."
+
+      def initialize(method_node)
+        @method_node = method_node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(memoization_node, MESSAGE) if mixed?
+      end
+
+      private
+        attr_reader :method_node
+        delegate :body, to: :method_node, private: true
+
+        def mixed?
+          memoization_node && !entire_body_is_memoization?
+        end
+
+        def memoization_node
+          @memoization_node ||= RuboCop::Callbacksystems::Execution::Immediate.new(body).nodes_of_type(:or_asgn)
+            .find { instance_variable_memoization?(it) }
+        end
+
+        def instance_variable_memoization?(node)
+          node&.or_asgn_type? && node.children.first.ivasgn_type?
+        end
+
+        def entire_body_is_memoization?
+          simple_memoization? || multiple_memoizations? || conditional_memoization? ||
+            memoization_with_rescue? || memoization_then_field_return?
+        end
+
+        def simple_memoization?
+          instance_variable_memoization?(effective_body)
+        end
+
+        def effective_body
+          @effective_body ||= TransparentExpression.new(body).value
+        end
+
+        def multiple_memoizations?
+          effective_body.type?(:begin, :kwbegin) &&
+            effective_body.children.all? { instance_variable_memoization?(it) }
+        end
+
+        def conditional_memoization?
+          effective_body.if_type? && effective_body.else_branch.nil? &&
+            instance_variable_memoization?(effective_body.if_branch)
+        end
+
+        def memoization_with_rescue?
+          instance_variable_memoization?(rescue_node&.children&.first)
+        end
+
+        def rescue_node
+          effective_body if effective_body.rescue_type?
+        end
+
+        # `@user ||= load; @user` reads back the field it just memoized, which is still a single concern.
+        def memoization_then_field_return?
+          effective_body.type?(:begin, :kwbegin) && effective_body.children.size == 2 &&
+            instance_variable_memoization?(effective_body.children.first) &&
+            returns_memoized_variable?(effective_body.children.last)
+        end
+
+        def returns_memoized_variable?(node)
+          reads_variable?(returned_expression_of(node), memoization_node.lhs.name)
+        end
+
+        class TransparentExpression
+          def initialize(node)
+            @node = node
+          end
+
+          def value
+            node.then do |current|
+              current = current.children.first while transparent?(current)
+              current
+            end
+          end
+
+          private
+            attr_reader :node
+
+            def transparent?(current)
+              current.type?(:begin, :kwbegin) && current.children.one?
+            end
+        end
+    end
+end

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

@@ -0,0 +1,78 @@
+# Forbids nested modules inside classes.
+# Modules should be defined at the top level or inside other modules,
+# not inside classes.
+#
+# Nested modules in classes are often used to avoid creating proper
+# objects, leading to imperative rather than declarative code.
+#
+# @example
+#   # bad - nested module in class
+#   class Order
+#     module Calculations
+#       def total
+#         # ...
+#       end
+#     end
+#   end
+#
+#   # bad - nested module in private section
+#   class Order
+#     private
+#       module Calculations
+#         def total
+#           # ...
+#         end
+#       end
+#   end
+#
+#   # good - use a nested class instead
+#   class Order
+#     private
+#       class Calculator
+#         def total
+#           # ...
+#         end
+#       end
+#   end
+#
+#   # good - define module at top level
+#   module Order::Calculations
+#     def total
+#       # ...
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoNestedModulesInClasses < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Do not nest modules inside classes. Use a nested class or define the module at the top level."
+
+  def on_module(node)
+    report NestedModule.new(node)
+  end
+
+  alias on_casgn on_module
+
+  private
+    class NestedModule
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, MESSAGE) if declaration? && inside_class?
+      end
+
+      private
+        attr_reader :node
+
+        def declaration?
+          node.module_type? ||
+            RuboCop::Callbacksystems::ClassStructure::BuilderAssignment.new(node).builds_module?
+        end
+
+        def inside_class?
+          enclosing_class_or_module_of(node)&.class_type?
+        end
+    end
+end

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

@@ -0,0 +1,74 @@
+# Prohibits returning nil at the end of a method. A trailing `nil` is there to
+# hide the value of the statement above it, which means a caller reads the
+# method for a value it was never meant to give, so the method wants a shape
+# whose last statement is its result. A `nil` that is the only statement is
+# intentional, as in an interface method, and stays.
+#
+# @example
+#   # bad
+#   def process
+#     do_something
+#     nil
+#   end
+#
+#   # bad
+#   def process
+#     if condition
+#       do_something
+#     end
+#     nil
+#   end
+#
+#   # good - return value is implicit
+#   def process
+#     do_something
+#   end
+#
+#   # good - use early return if needed
+#   def process
+#     return unless condition
+#     do_something
+#   end
+#
+#   # good - nil is clearly intentional (only statement)
+#   def some_interface_method
+#     nil
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoNilAtEndOfMethod < RuboCop::Cop::Callbacksystems::Base
+  def on_def(node)
+    report TrailingNil.new(node)
+  end
+
+  alias on_defs on_def
+
+  private
+    class TrailingNil
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Avoid `nil` at the end of a method. Restructure the code to make it unnecessary."
+
+      def initialize(method_node)
+        @method_node = method_node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(last, MESSAGE) if trailing?
+      end
+
+      private
+        attr_reader :method_node
+
+        def trailing?
+          last&.nil_type? && previous
+        end
+
+        def last
+          @last ||= last_statement_in(method_node.body)
+        end
+
+        def previous
+          last.left_sibling if last.parent.type?(:begin, :kwbegin)
+        end
+    end
+end

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

@@ -0,0 +1,37 @@
+# A `validate` declaration already says what the callback does. Its name should
+# describe the condition it checks, so the declaration reads as a sentence.
+# Renaming needs an understanding of that condition and every caller, so this
+# cop reports the registration without changing the callback or its definition.
+#
+# @example
+#   # bad
+#   validate :validate_email
+#   validate :valid_membership
+#
+#   # good
+#   validate :ensure_deliverable_email
+#   validate :no_expired_membership
+#   validate :expiration_date_cannot_be_in_the_past
+#
+class RuboCop::Cop::Callbacksystems::NoRedundantValidationName < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Validation callback `%<name>s` repeats `validate`. Name the condition instead, like `ensure_*` or `no_*`."
+
+  def on_send(node)
+    if validation_registration?(node)
+      node.arguments.each do |argument|
+        add_offense(argument, message: format(MESSAGE, name: argument.value)) if redundant_name?(argument)
+      end
+    end
+  end
+
+  alias on_csend on_send
+
+  private
+    def validation_registration?(node)
+      node.method?(:validate) && call_on_self?(node) && !enclosing_method_of(node)
+    end
+
+    def redundant_name?(argument)
+      argument.sym_type? && argument.value.match?(/\A(?:valid|validate)(?:_|[!?]?\z)/)
+    end
+end