rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,93 @@
+# Ensures methods that enqueue jobs follow the `_later` naming convention.
+# This cop only flags when there's a corresponding method that does the actual work.
+#
+# The convention is to have paired methods:
+# - `process` - does the actual work
+# - `process_later` - enqueues a job that calls `process`
+#
+# @example
+#   # bad - work method exists, job method should be named process_later
+#   def enqueue_process
+#     ProcessJob.perform_later(self)
+#   end
+#
+#   def process
+#     # actual work
+#   end
+#
+#   # good - follows naming convention
+#   def process_later
+#     ProcessJob.perform_later(self)
+#   end
+#
+#   def process
+#     # actual work
+#   end
+#
+#   # good - no corresponding work method, so no flag
+#   def notify
+#     NotificationJob.perform_later(self)
+#   end
+#
+class RuboCop::Cop::Callbacksystems::JobEnqueueMethods < RuboCop::Cop::Callbacksystems::Base
+  def on_new_investigation
+    @sibling_methods = RuboCop::Callbacksystems::Methods::Siblings.new
+  end
+
+  def on_def(node)
+    report EnqueueMethod.new(node, sibling_methods:) unless node.method_name.to_s.end_with?("_later")
+  end
+
+  alias on_defs on_def
+
+  private
+    attr_reader :sibling_methods
+
+    # A method enqueuing a job, read for the work method its job is named after.
+    class EnqueueMethod
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Rename `%<name>s` to `%<expected>s` to follow the _later convention."
+
+      def initialize(node, sibling_methods:)
+        @node = node
+        @sibling_methods = sibling_methods
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if pairs_with_work_method?
+      end
+
+      private
+        attr_reader :node, :sibling_methods
+
+        def pairs_with_work_method?
+          base_name && sibling_methods.named(base_name, beside: node).any?
+        end
+
+        def base_name
+          @base_name ||= job_class_name.delete_suffix("Job").underscore.to_sym if job_class_name.end_with?("Job")
+        end
+
+        def job_class_name
+          @job_class_name ||= class_name_of(perform_later_call&.receiver).to_s
+        end
+
+        def class_name_of(receiver)
+          case receiver&.type
+          when :const then receiver.short_name
+          when :send then receiver.method_name
+          end
+        end
+
+        def perform_later_call
+          RuboCop::Callbacksystems::Execution::Immediate.new(node.body).find do |candidate|
+            candidate.call_type? && candidate.method?(:perform_later)
+          end
+        end
+
+        def message
+          format(MESSAGE, name: node.method_name, expected: :"#{base_name}_later")
+        end
+    end
+end

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

@@ -0,0 +1,118 @@
+# Deeply chained safe navigation (`a&.b&.c&.d&.e`) signals deep coupling or
+# poor data modeling. Refactor: pre-validate, restructure the object, or
+# extract an intermediate.
+#
+# @example MaxDepth: 3 (default)
+#   # bad - four safe-navigation links
+#   value = account&.owner&.address&.city
+#
+#   # good - extract an intermediate
+#   owner = account&.owner
+#   value = owner&.address&.city
+#
+class RuboCop::Cop::Callbacksystems::MaxSafeNavigationDepth < RuboCop::Cop::Callbacksystems::Base
+  def on_new_investigation
+    @navigation_context = NavigationContext.new
+  end
+
+  def on_csend(node)
+    report NavigationChain.new(node, navigation_context, max_depth: cop_config["MaxDepth"])
+  end
+
+  private
+    attr_reader :navigation_context
+
+    # The chain a safe-navigation call sits in, measured once from its outermost link so every chain is reported once.
+    class NavigationChain
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Safe-navigation depth %<depth>d exceeds maximum %<maximum>d. Restructure or extract intermediates."
+
+      def initialize(node, navigation_context, max_depth:)
+        @node = node
+        @navigation_context = navigation_context
+        @max_depth = max_depth
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if outermost?(node) && depth > max_depth
+      end
+
+      private
+        attr_reader :node, :navigation_context, :max_depth
+        delegate :outermost?, :top_of, to: :navigation_context, private: true
+
+        # Every link in the chain counts, not just a consecutive run (`a&.b.c&.d` is depth 2), matching the JS rule.
+        def depth
+          @depth ||= links_down_from(top_of(node)).count(&:csend_type?)
+        end
+
+        def links_down_from(link)
+          if block_given?
+            while link&.call_type?
+              yield link
+              link = link.receiver
+            end
+          else
+            to_enum(__method__, link)
+          end
+        end
+
+        def message
+          format(MESSAGE, depth:, maximum: max_depth)
+        end
+    end
+
+    # Receiver-chain ancestry shared by every safe link in one investigation, with iterative path compression.
+    class NavigationContext
+      Facts = Data.define(:top, :safe_link)
+      NO_FACTS = Facts.new(nil, nil)
+
+      def initialize
+        @facts_by_link = {}.compare_by_identity
+      end
+
+      def outermost?(node)
+        safe_link_at_or_above(chained_parent_of(node)).nil?
+      end
+
+      def top_of(node)
+        facts_for(node).top
+      end
+
+      private
+        attr_reader :facts_by_link
+
+        def safe_link_at_or_above(node)
+          node&.then { facts_for(it).safe_link }
+        end
+
+        def facts_for(node)
+          path = uncached_path_from(node)
+          facts = inherited_facts_of(path)
+          path.reverse_each do |link|
+            facts = Facts.new(facts.top || link, link.csend_type? ? link : facts.safe_link)
+            facts_by_link[link] = facts
+          end
+          facts_by_link.fetch(node)
+        end
+
+        def uncached_path_from(node)
+          [].then do |path|
+            while node && !facts_by_link.key?(node)
+              path << node
+              node = chained_parent_of(node)
+            end
+            path
+          end
+        end
+
+        def chained_parent_of(link)
+          link.parent&.then { it if it.call_type? && it.receiver.equal?(link) }
+        end
+
+        def inherited_facts_of(path)
+          path.last&.then { facts_by_link.fetch(chained_parent_of(it), NO_FACTS) } || NO_FACTS
+        end
+    end
+end

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

@@ -0,0 +1,261 @@
+# Ensures methods are ordered by invocation: callers before callees, and a
+# caller's callees in the order it first invokes them (depth-first). Public
+# methods are ordered before private ones. A macro, block, or lambda that names a
+# method (a callback, a delegate target, a validation) calls it too, and it reads
+# at the top of the class, so a method reached only that way leads its visibility
+# group in the order the macros mention it (a guard before its action, since the
+# guard is evaluated first). A method a real method body calls follows that caller
+# instead.
+#
+# The actions of a controller are the exception: `Rails/ActionOrder` owns their
+# order, so they lead their group in the order that cop asks for and the walk
+# places everything else. A macro naming an action (a `rate_limit :create`) would
+# otherwise pull it to the top and the two cops would undo each other forever.
+#
+# @example
+#   # bad - called method defined before caller
+#   def helper
+#   end
+#
+#   def process
+#     helper
+#   end
+#
+#   # bad - sibling callees defined out of invocation order
+#   def process
+#     helper_b
+#     helper_a
+#   end
+#
+#   def helper_a
+#   end
+#
+#   def helper_b
+#   end
+#
+#   # good - caller before callee, callees in first-invocation order
+#   def process
+#     helper_a
+#     helper_b
+#   end
+#
+#   def helper_a
+#   end
+#
+#   def helper_b
+#   end
+#
+#   # good - with private section
+#   def process
+#     helper
+#   end
+#
+#   private
+#     def helper
+#     end
+#
+#   # good - a callback method leads: its macro calls it and reads at the top
+#   after_commit :notify_later
+#
+#   def notify_later
+#     NotifyJob.perform_later(self)
+#   end
+#
+#   def process
+#     compute
+#   end
+#
+#   def compute
+#   end
+#
+#   # good - `Rails/ActionOrder` places the actions, whatever a macro names
+#   rate_limit :create, to: 10, within: 30.minutes
+#
+#   def new
+#   end
+#
+#   def create
+#   end
+#
+class RuboCop::Cop::Callbacksystems::MethodInvocationOrder < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_class(node)
+    analyze(node, direct_definitions_in(node.body, :def), macro_references: true, actions: actions_of(node))
+    analyze(node, direct_definitions_in(node.body, :defs), macro_references: false, actions: [])
+  end
+
+  alias on_module on_class
+
+  def on_sclass(node)
+    analyze(node, direct_definitions_in(node.body, :def), macro_references: true, actions: [])
+  end
+
+  private
+    def analyze(node, methods, macro_references:, actions:)
+      report_each InvocationOrder.new(processed_source, node, methods, macro_references:, actions:)
+    end
+
+    # Read from `Rails/ActionOrder`, since two cops ordering the same methods by different rules undo each other.
+    def actions_of(node)
+      controller_class?(node) ? expected_action_order : []
+    end
+
+    def expected_action_order
+      if config.cop_enabled?("Rails/ActionOrder")
+        Array(config.for_cop("Rails/ActionOrder")["ExpectedOrder"]).map(&:to_sym)
+      else
+        []
+      end
+    end
+
+    class InvocationOrder
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Method `%<expected>s` should be defined before `%<actual>s` to keep callers before callees."
+
+      def initialize(processed_source, node, methods, macro_references:, actions:)
+        @processed_source = processed_source
+        @node = node
+        @methods = methods
+        @macro_references = macro_references
+        @actions = actions
+      end
+
+      def each_offense
+        yield offense if analyzable? && divergence.found?
+      end
+
+      private
+        attr_reader :processed_source, :node, :methods, :macro_references, :actions
+
+        def analyzable?
+          node.body && methods.size >= 2 && method_names.uniq.size == method_names.size
+        end
+
+        def method_names
+          @method_names ||= methods.map(&:method_name)
+        end
+
+        def divergence
+          @divergence ||= RuboCop::Callbacksystems::ClassStructure::Divergence.new(method_names, from: canonical_order)
+        end
+
+        def canonical_order
+          @canonical_order ||= LEVELS.flat_map { ordered_by_visibility(it) }
+        end
+
+        def ordered_by_visibility(visibility)
+          leading_first(full_order.select { visibilities[it] == visibility })
+        end
+
+        def leading_first(names)
+          leading = leading_order.select { names.include?(it) }
+
+          leading + (names - leading)
+        end
+
+        def leading_order
+          [ :initialize, *actions ]
+        end
+
+        def full_order
+          @full_order ||= RuboCop::Callbacksystems::ClassStructure::ReferenceOrder.new(ordering_seeds, call_graph).to_a
+        end
+
+        def ordering_seeds
+          macro_led + real_roots + method_names
+        end
+
+        def macro_led
+          if macro_references
+            reference_order.reject { called_methods.include?(it) }
+          else
+            []
+          end
+        end
+
+        def reference_order
+          @reference_order ||= macro_methods.select { known_method_names.include?(it) }
+        end
+
+        def macro_methods
+          @macro_methods ||= RuboCop::Callbacksystems::Methods::MacroReferences.new(node.body)
+        end
+
+        def known_method_names
+          @known_method_names ||= Set.new(method_names)
+        end
+
+        def called_methods
+          @called_methods ||= Set.new(call_graph.values.flatten)
+        end
+
+        def call_graph
+          @call_graph ||= methods.to_h { [ it.method_name, calls_from(it) ] }
+        end
+
+        def calls_from(method)
+          if method.body
+            receiverless_method_names_in(method.body).uniq.select { places?(method.method_name, it) }
+          else
+            []
+          end
+        end
+
+        # A private caller places no public callee, since the public methods lead whatever reads them from below.
+        def places?(caller_name, callee_name)
+          known_method_names.include?(callee_name) && level_of(callee_name) >= level_of(caller_name)
+        end
+
+        def level_of(name)
+          LEVELS.index(visibilities[name])
+        end
+
+        def visibilities
+          @visibilities ||= methods.to_h { [ it.method_name, visibility_of(it) ] }
+        end
+
+        def real_roots
+          method_names.reject { called_methods.include?(it) }
+        end
+
+        def offense
+          RuboCop::Callbacksystems::Offense.new(methods_by_name[divergence.expected], message,
+            correcting: method_runs.any?(&:reorderable?)) { reorder(it) }
+        end
+
+        def methods_by_name
+          @methods_by_name ||= methods.index_by(&:method_name)
+        end
+
+        def message
+          format(MESSAGE, expected: divergence.expected, actual: divergence.actual)
+        end
+
+        def method_runs
+          @method_runs ||= runs_in(node.body) { methods.include?(it) }.filter_map { run_of(it) }
+        end
+
+        def run_of(members)
+          statements = statements_of(members)
+
+          if uninterrupted?(statements)
+            RuboCop::Callbacksystems::ClassStructure::StatementRun.new(statements, order: canonical_order) { it.node.method_name }
+          end
+        end
+
+        def statements_of(members)
+          members.map { RuboCop::Callbacksystems::Source::StatementWithComments.new(it, processed_source) }
+        end
+
+        # A comment unattached to either method is an intentional boundary, not source for a sortable run.
+        def uninterrupted?(statements)
+          statements.each_cons(2).none? { |above, below| above.range.end.join(below.range.begin).source.strip.present? }
+        end
+
+        def reorder(corrector)
+          method_runs.each { it.rewrite(corrector) }
+        end
+    end
+end