rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,339 @@
+# Detects a set of parameter names that travel together across a class's or
+# module's private methods, suggesting they belong to an object of their own,
+# usually a private nested class holding them as instance state. Only private
+# methods are examined, since a public method's signature answers to an
+# interface, not internal threading, which is also why the JS rule no-data-clump
+# skips exported functions and public members. Methods under `class << self`
+# join the group of the class that holds them.
+#
+# The set is found as a connected component in the co-occurrence graph of shared
+# parameter names, meaning names used by two or more methods, linked whenever they
+# appear together in one method's signature. Because membership follows the
+# graph, not an exact repeated tuple, this catches names sharing *varying*
+# combinations, as in `m1(a, b)`, `m2(a, c)`, `m3(b, c)`, where no single pair
+# repeats. Only methods carrying two or more of the names count toward a set,
+# since one name is a value arriving, not a concept being passed, and counting
+# such bystanders would let a lone name clear the set threshold instead of its
+# own higher one.
+# A one-letter name is left out, since it is a placeholder `NoSingleLetterNames` already flags.
+#
+# How far a set has to spread depends on how much its shape already tells. A
+# signature repeated verbatim counts from `MinMethodsForRepeatedSignature`
+# methods, two by default, because nothing in those parameter lists explains the
+# co-occurrence except the concept itself. Names that come with extras of their
+# own might merely have met, so those need `MinMethods`, three by default, and a
+# lone name threaded through the class has to reach `MinMethodsForSingleParam`,
+# six by default. The recursion subject is exempt, since a name passed both as
+# itself and as a derivative of itself in the same call (`walk(node.child, node)`)
+# changes at every step and cannot become shared state.
+#
+# @example
+#   # bad - a signature repeated verbatim is telling from two methods already
+#   class Order
+#     private
+#       def validate(user, account); end
+#       def execute(user, account); end
+#   end
+#
+#   # bad - a shared core with extras of its own, once it reaches three methods
+#   class Order
+#     private
+#       def create(name, email, phone); end
+#       def validate(name, email, address); end
+#       def save(name, phone, address); end
+#   end
+#
+#   # bad - one value threaded through six methods
+#   class Visitor
+#     private
+#       def first(node); end
+#       def second(node); end
+#       def third(node); end
+#       def fourth(node); end
+#       def fifth(node); end
+#       def sixth(node); end
+#   end
+#
+#   # good - a private nested class holds the values as state
+#   class Order
+#     def process
+#       context = Context.new(user, account)
+#       context.validate
+#       context.execute
+#     end
+#
+#     private
+#       class Context
+#         def initialize(user, account)
+#           @user = user
+#           @account = account
+#         end
+#
+#         def validate; end
+#         def execute; end
+#       end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::DataClump < RuboCop::Cop::Callbacksystems::Base
+  def on_class(node)
+    report_each ParameterClumps.new(node, limits)
+  end
+
+  alias on_module on_class
+
+  private
+    def limits
+      Limits.new \
+        min_methods: cop_config["MinMethods"],
+        min_methods_for_repeated_signature: cop_config["MinMethodsForRepeatedSignature"],
+        min_methods_for_single_parameter: cop_config["MinMethodsForSingleParam"]
+    end
+
+    class ParameterClumps
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(node, limits)
+        @node = node
+        @limits = limits
+      end
+
+      def each_offense
+        clumps.each { yield RuboCop::Callbacksystems::Offense.new(it.location, it.message) }
+      end
+
+      private
+        attr_reader :node, :limits
+
+        def clumps
+          SignatureGroup.new(signatures, limits).clumps
+        end
+
+        def signatures
+          internal_methods.map { Signature.new(it, exempt_names) }.select { it.names.any? }
+        end
+
+        def internal_methods
+          @internal_methods ||= direct_method_nodes_in(node.body).select { internal_method?(it) }
+        end
+
+        def internal_method?(method_node)
+          private_nested_class?(node) || private_method?(method_node)
+        end
+
+        def exempt_names
+          @exempt_names ||= internal_methods.flat_map { recursion_subject_names_of(it) }.to_set
+        end
+
+        def recursion_subject_names_of(method_node)
+          RuboCop::Callbacksystems::Execution::Immediate.new(method_node.body).nodes_of_type(:send, :csend)
+            .flat_map { recursion_subjects_in(it) }
+        end
+    end
+
+    # Reads a method group's shared names as connected components, each its own hidden object.
+    class SignatureGroup
+      MIN_SHARING_METHODS = 2
+
+      def initialize(signatures, limits)
+        @signatures = signatures
+        @limits = limits
+      end
+
+      def clumps
+        candidates.select { limits.reached_by?(it) }
+      end
+
+      private
+        attr_reader :signatures, :limits
+
+        def candidates
+          graph.map { clump_for(it) }
+        end
+
+        def graph
+          Graph.new(shared_names, signatures)
+        end
+
+        def shared_names
+          name_counts.select { |_, count| count >= MIN_SHARING_METHODS }.keys
+        end
+
+        def name_counts
+          signatures.flat_map(&:names).tally
+        end
+
+        def clump_for(names)
+          Clump.new(signatures.select { it.counts_toward?(names) }, names)
+        end
+    end
+
+    # The shared names linked by the signatures they appear in together, read as its connected components.
+    class Graph
+      include Enumerable
+
+      delegate :each, to: :components
+
+      def initialize(shared_names, signatures)
+        @shared_names = shared_names
+        @signatures = signatures
+      end
+
+      private
+        attr_reader :shared_names, :signatures
+
+        def components
+          each_component.to_a
+        end
+
+        def each_component
+          if block_given?
+            remaining = shared_names.to_set
+            until remaining.empty?
+              component = component_of(remaining.first)
+              yield component
+              remaining.subtract(component)
+            end
+          else
+            enum_for(__method__)
+          end
+        end
+
+        def component_of(name)
+          closure_of(Set[name])
+        end
+
+        def closure_of(names)
+          names.dup.tap do |reached|
+            pending = names.to_a
+            position = 0
+            visited_signatures = {}.compare_by_identity
+
+            until position == pending.size
+              signatures_by_name.fetch(pending[position]).each do |signature|
+                next if visited_signatures.key?(signature)
+
+                visited_signatures[signature] = true
+                signature.names.each do |neighbor|
+                  pending << neighbor if shared_name?(neighbor) && reached.add?(neighbor)
+                end
+              end
+              position += 1
+            end
+          end
+        end
+
+        def signatures_by_name
+          @signatures_by_name ||= shared_names.index_with { [] }.tap do |index|
+            signatures.each do |signature|
+              signature.names.each { index.fetch(it) << signature if index.key?(it) }
+            end
+          end
+        end
+
+        def shared_name?(name)
+          shared_name_index.include?(name)
+        end
+
+        def shared_name_index
+          @shared_name_index ||= shared_names.to_set
+        end
+    end
+
+    class Clump < Data.define(:signatures, :names)
+      MESSAGE = "Parameters `%<parameters>s` travel together through %<count>d private methods (`%<methods>s`). " \
+        "Consider a private nested class holding them as instance state."
+      SINGLE_PARAMETER_MESSAGE = "Parameter `%<parameter>s` is threaded through %<count>d private methods " \
+        "(`%<methods>s`). Consider a private nested class holding it as instance state."
+
+      def message
+        lone_name? ? threaded_parameter_message : shared_parameters_message
+      end
+
+      def lone_name?
+        names.one?
+      end
+
+      # Stronger than a shared core, since the methods take the set and nothing besides.
+      def repeated_signature?
+        signatures.map(&:sorted_names).uniq.one?
+      end
+
+      def location
+        signatures.first.node.loc.name
+      end
+
+      def count
+        signatures.size
+      end
+
+      private
+        def threaded_parameter_message
+          format(SINGLE_PARAMETER_MESSAGE, parameter: sorted_parameter_names.first, count:, methods: method_names)
+        end
+
+        def sorted_parameter_names
+          names.sort
+        end
+
+        def method_names
+          signatures.map(&:method_name).join(", ")
+        end
+
+        def shared_parameters_message
+          format(MESSAGE, parameters: sorted_parameter_names.join(", "), count:, methods: method_names)
+        end
+    end
+
+    class Signature
+      include RuboCop::Callbacksystems::Helpers
+
+      attr_reader :node, :names
+
+      delegate :method_name, to: :node
+
+      def initialize(node, exempt_names)
+        @node = node
+        @names = parameter_names_of(node).uniq.reject { exempt_names.include?(it) || it.length == 1 }
+      end
+
+      # A method carrying one name of a set is a bystander, so a set needs two of its names to appear in a signature.
+      def counts_toward?(wanted)
+        shared_count_in(wanted) >= (wanted.many? ? 2 : 1)
+      end
+
+      def shared_count_in(wanted)
+        names.count { wanted.include?(it) }
+      end
+
+      # A one-letter name is a placeholder rather than a concept, and `NoSingleLetterNames` already asks for a word.
+      def sorted_names
+        @sorted_names ||= names.sort
+      end
+    end
+
+    # The thresholds mirror the JS rule no-data-clump, so the two configs agree on what qualifies.
+    class Limits
+      def initialize(min_methods:, min_methods_for_repeated_signature:, min_methods_for_single_parameter:)
+        @min_methods = min_methods
+        @min_methods_for_repeated_signature = min_methods_for_repeated_signature
+        @min_methods_for_single_parameter = min_methods_for_single_parameter
+      end
+
+      def reached_by?(clump)
+        clump.count >= reach_for(clump)
+      end
+
+      private
+        attr_reader :min_methods, :min_methods_for_repeated_signature, :min_methods_for_single_parameter
+
+        def reach_for(clump)
+          if clump.lone_name?
+            min_methods_for_single_parameter
+          elsif clump.repeated_signature?
+            min_methods_for_repeated_signature
+          else
+            min_methods
+          end
+        end
+    end
+end

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

@@ -0,0 +1,350 @@
+# A method that returns a value should be named for the value it hands back
+# (`total`, `user_by_id`), not for the imperative action it performs
+# (`compute_total`, `get_user`). The imperative name reads as a command when the
+# thing is really a query. We flag a method whose name leads with a producer verb
+# and carries a noun we can rename it to (`compute_total` -> `total`). A bare verb
+# (`fetch`) is left alone: with no noun there is nothing to rename to. A verb
+# followed straight by a connector (`find_in_scope`, `load_for`) is left alone
+# too: the phrase that remains (`in_scope`, `for`) names no value on its own, and
+# the leading word often reads as a noun in context (`load_for person` is "the
+# load for a person"), so the rename is too contextual to pick. With arguments and
+# no connector in the name we only flag it (`get_user(id)`): a bare noun beside an
+# argument (`user(id)`) relates nothing, and the relator is the author's call.
+#
+# The verb list is curated, not taken from a lexicon: `get`/`find`/`build` are not
+# dropped from any dictionary, but are bad as method prefixes by code convention.
+# Excluded on purpose: noun-verbs that name a value fine (`count`, `name`,
+# `value`, `order`, `state`...) and command verbs that act rather than produce
+# (`save`, `render`, `update`, `send`, `handle`, `process`...).
+#
+# We flag a producer-verb method only when it just *delivers* a value: it
+# changes no state, calls no mutator, does no I/O. A method that *does* something
+# earns its verb and is left alone, even named with a producer verb: `create_user`
+# that calls `save!`, an association `build` that mutates the collection.
+# Construction is delivery, not doing: `Foo.new(args)` only hands a value back, so
+# a pure factory is flagged. Building a collaborator and then asking it for
+# something is a third case: what happens inside is not readable here, so
+# `Commenter.new(card).comment` leaves the name alone.
+#
+# Two more cases are left alone, both signs the name is intentional rather than
+# careless. A method that delegates within its own verb family (`format_money`
+# calling `format_short`, `find_account_by_cookie` calling `find_by`) mirrors a
+# real operation of the same name, so renaming it would break the family. And a
+# method whose suggested noun already names a sibling (`build_prices` beside
+# `attr_reader :prices`, `lookup_key` beside `key`) is the separate-builder
+# pattern: the value already has its declarative name, this is its helper.
+#
+# Ruby divergence from the JS rule: JS can gate on "returns a value" because a
+# function can fall off the end returning `undefined`. In Ruby every method
+# returns its last expression, so "delivers" is the *absence of effects*, not the
+# presence of a return. Predicates (`valid?`), bang methods (`save!`), setters
+# (`foo=`), operators, and `initialize` stay exempt by Ruby convention.
+#
+# @example
+#   # bad - imperative name for a value (no arguments): name it for the value
+#   def compute_total
+#     line_items.sum(&:price)
+#   end
+#
+#   # bad - imperative name for a value built from an argument
+#   def get_user(id)
+#     users[id]
+#   end
+#
+#   # good - the bare verb is allowed: there is no noun to rename it to
+#   def compute
+#     heavy_work
+#   end
+#
+#   # good - verb followed straight by a connector names no value to rename to
+#   def load_for(person)
+#     events_for(person) + blocks_for(person)
+#   end
+#
+#   # good - delegates within its own verb family: it mirrors a real operation
+#   def format_money(money)
+#     Worldwide.currency(money).format_short(money)
+#   end
+#
+#   # good - the suggested noun already names a sibling (`attr_reader :prices`)
+#   def build_prices
+#     properties.to_h { |currency, cents| [ currency, Money.new(cents) ] }
+#   end
+#
+#   # good - named for the value it returns
+#   def total
+#     line_items.sum(&:price)
+#   end
+#
+#   # good - noun-verb reads as a noun
+#   def count
+#     items.length
+#   end
+#
+#   # good - predicates, bang methods, and setters are exempt by convention
+#   def valid?
+#     errors.empty?
+#   end
+#
+class RuboCop::Cop::Callbacksystems::DeclarativeMethodNaming < RuboCop::Cop::Callbacksystems::Base
+  def on_new_investigation
+    @declared_values = DeclaredValues.new
+  end
+
+  def on_def(node)
+    report MethodName.new(node, declared_values:)
+  end
+
+  alias on_defs on_def
+
+  private
+    PRODUCER_VERBS = %w[
+      get fetch retrieve obtain acquire load
+      compute calculate derive determine evaluate deduce infer
+      generate produce fabricate assemble construct build make create
+      convert transform translate cast coerce
+      serialize deserialize stringify normalize denormalize parse extract
+      format summarize aggregate tabulate
+      find lookup locate search select pick choose
+      collect gather accumulate compile
+      resolve
+    ].to_set
+
+    CONNECTORS = %w[
+      for of from at in on by with within without
+      into onto over under above below beneath behind
+      beside before after between across through throughout
+      toward towards alongside during via to per until
+      since against among around near beyond
+    ].to_set
+
+    EFFECTS = %i[
+      save update create build destroy delete insert
+      insert_all upsert upsert_all update_all delete_all destroy_all
+      push pop shift unshift prepend concat append << store replace add clear
+      each each_with_index puts print pp write
+      touch mkdir mkdir_p mkpath makedirs rm rm_f rm_rf rmdir remove_entry remove_dir
+      cp cp_r mv ln_s chmod chown
+    ].to_set
+
+    READER_MACROS = %i[ attr_reader attr_accessor attr_writer ].to_set
+    SIDE_EFFECT_NODE_TYPES = %i[ casgn cvasgn gvasgn ivasgn super xstr yield zsuper ]
+    NETWORK_METHODS = %i[ get post put patch delete request start ].to_set
+    FILESYSTEM_RECEIVERS = %w[ File IO ].to_set
+    FILESYSTEM_METHODS = %i[ binread foreach open read readlines sysopen ].to_set
+
+    attr_reader :declared_values
+
+    # Value names indexed once for each body whose methods ask whether their suggested noun is already taken.
+    class DeclaredValues
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize
+        @sibling_methods = RuboCop::Callbacksystems::Methods::Siblings.new
+        @reader_names_by_container = {}.compare_by_identity
+      end
+
+      def include?(name, beside:)
+        sibling_methods.named(name.to_sym, beside:).any? || reader_names_beside(beside).include?(name)
+      end
+
+      private
+        attr_reader :sibling_methods, :reader_names_by_container
+
+        def reader_names_beside(method)
+          domain = RuboCop::Callbacksystems::Methods::Domain.new(method)
+          reader_names_in(domain.container).fetch(domain.identity) { Set.new }
+        end
+
+        def reader_names_in(container)
+          if container
+            reader_names_by_container[container] ||=
+              ReaderMacros.new(container.body).each_with_object({}) do |macro, names|
+                (names[declaration_domain_of(macro)] ||= Set.new)
+                  .merge(macro.arguments.select(&:sym_type?).map { it.value.to_s })
+              end
+          else
+            {}
+          end
+        end
+
+        def declaration_domain_of(macro)
+          identity = RuboCop::Callbacksystems::Methods::Domain.new(macro).identity
+          identity.take(identity.size.pred).freeze
+        end
+
+        # Reader declarations reached through body sequences, singleton sections, and nested call arguments.
+        class ReaderMacros
+          include Enumerable
+          include RuboCop::Callbacksystems::Helpers
+
+          def initialize(body)
+            @body = body
+          end
+
+          def each
+            if block_given?
+              @pending = [ body ].compact
+              until pending.empty?
+                advance
+                visit { yield it }
+              end
+            else
+              to_enum(__method__)
+            end
+          end
+
+          private
+            attr_reader :body, :pending, :current
+
+            def advance
+              @current = pending.pop
+            end
+
+            def visit
+              case current.type
+              when :begin, :kwbegin then queue current.each_child_node
+              when :sclass then queue [ current.body ].compact
+              when :send then visit_send { yield it }
+              end
+            end
+
+            def queue(nodes)
+              pending.concat(nodes.to_a.reverse)
+            end
+
+            def visit_send
+              yield current if reader_macro?
+              queue current.arguments
+            end
+
+            def reader_macro?
+              bare_send?(current) && READER_MACROS.include?(current.method_name)
+            end
+        end
+    end
+
+    class MethodName
+      include RuboCop::Callbacksystems::Helpers
+
+      IMPERATIVE_NAME = "Rename `%<name>s` to `%<suggestion>s`: name it for the value, not the action `%<verb>s`."
+      IMPERATIVE_NAME_RELATE = "Rename `%<name>s` for the value, related to its argument, not the action `%<verb>s`."
+
+      def initialize(node, declared_values:)
+        @node = node
+        @declared_values = declared_values
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node.loc.name, message) if imperatively_named?
+      end
+
+      private
+        attr_reader :node, :declared_values
+
+        def imperatively_named?
+          eligible? && imperative_producer? && delivers_only? &&
+            !delegates_within_verb_family? && !value_already_named?
+        end
+
+        def eligible?
+          !node.predicate_method? && !node.bang_method? && !node.assignment_method? &&
+            !node.operator_method? && !node.method?(:initialize)
+        end
+
+        def imperative_producer?
+          PRODUCER_VERBS.include?(verb) && !noun.nil?
+        end
+
+        def verb
+          segments.first
+        end
+
+        def segments
+          @segments ||= node.method_name.to_s.split("_")
+        end
+
+        # A rest led by a connector (`find_in_block`) is a prepositional phrase naming nothing, so it yields no noun.
+        def noun
+          rest.join("_") if rest.any? && CONNECTORS.exclude?(rest.first)
+        end
+
+        def rest
+          segments.drop(1)
+        end
+
+        def delivers_only?
+          RuboCop::Callbacksystems::Execution::Immediate.new(node.body).none? do |descendant|
+            descendant.type?(*SIDE_EFFECT_NODE_TYPES, :call) && SideEffect.new(descendant).present?
+          end
+        end
+
+        def delegates_within_verb_family?
+          node.each_descendant(:call).any? { it.method_name.to_s.split("_").first == verb }
+        end
+
+        def value_already_named?
+          declared_values.include?(noun, beside: node)
+        end
+
+        def message
+          format(message_template, name: node.method_name, verb: verb, suggestion: noun)
+        end
+
+        def message_template
+          needs_relator? ? IMPERATIVE_NAME_RELATE : IMPERATIVE_NAME
+        end
+
+        def needs_relator?
+          arguments? && !carries_connector?
+        end
+
+        def arguments?
+          node.arguments.any?
+        end
+
+        def carries_connector?
+          rest.any? { CONNECTORS.include?(it) }
+        end
+    end
+
+    class SideEffect
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(node)
+        @node = node
+      end
+
+      def present?
+        !node.call_type? || mutating_call?
+      end
+
+      private
+        attr_reader :node
+
+        def mutating_call?
+          node.bang_method? || node.setter_method? || EFFECTS.include?(node.method_name) ||
+            asks_a_built_collaborator? || performs_io?
+        end
+
+        def asks_a_built_collaborator?
+          node.receiver&.call_type? && node.receiver.method?(:new)
+        end
+
+        def performs_io?
+          performs_network_io? || performs_filesystem_io?
+        end
+
+        def performs_network_io?
+          receiver_constant.to_s.start_with?("Net::HTTP") && NETWORK_METHODS.include?(node.method_name)
+        end
+
+        def receiver_constant
+          @receiver_constant ||= constant_name_of(node.receiver)&.delete_prefix("::")
+        end
+
+        def performs_filesystem_io?
+          FILESYSTEM_RECEIVERS.include?(receiver_constant) && FILESYSTEM_METHODS.include?(node.method_name)
+        end
+    end
+end