rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,255 @@
+# Orders the nested classes of a body by reference: one that names another reads
+# before the one it names, the way `MethodInvocationOrder` reads a caller before
+# its callees.
+#
+# Only a class or module carrying a body counts. A constant built in a line
+# (`Row = Data.define(:name)`, `Error = Class.new(StandardError)`) is a
+# declaration, and `BodyOrder` reads those with the values at the top.
+#
+# Where the nested classes sit is `BodyOrder`'s business, which keeps them last.
+# This one only orders them among themselves, inside the run they already form.
+#
+# @example
+#   # bad - Row names Cell, so Row reads first
+#   class Report
+#     class Cell
+#       def value; end
+#     end
+#
+#     class Row
+#       def cells
+#         [ Cell.new ]
+#       end
+#     end
+#   end
+#
+#   # good
+#   class Report
+#     class Row
+#       def cells
+#         [ Cell.new ]
+#       end
+#     end
+#
+#     class Cell
+#       def value; end
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NestedClassOrder < RuboCop::Cop::Callbacksystems::Base
+  include RuboCop::Callbacksystems::ProjectIndex::Support
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_new_investigation
+    report_each Bodies.new(processed_source, constant_references:) if project_index_reliable?
+  end
+
+  private
+    def constant_references
+      RuboCop::Callbacksystems::ProjectIndex::ConstantReferences.for(project_index).within(processed_source)
+    end
+
+    class Bodies
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(processed_source, constant_references:)
+        @processed_source = processed_source
+        @constant_references = constant_references
+      end
+
+      def each_offense(&block)
+        runs.each do |run|
+          NestedClasses.new(run, processed_source, constant_references:, permit:).each_offense(&block)
+        end
+      end
+
+      private
+        attr_reader :processed_source, :constant_references
+
+        def runs
+          @runs ||= definition_nodes_in(processed_source.ast).flat_map { runs_of(it) }.select(&:many?)
+        end
+
+        def runs_of(node)
+          runs_in(node.body) { declared_class?(it) }
+        end
+
+        # A constant built from a builder stays out, since `BodyOrder` already places it among the values or the nested
+        # classes.
+        def declared_class?(node)
+          node.type?(:class, :module) && node.body.present?
+        end
+
+        def permit
+          @permit ||= RuboCop::Callbacksystems::Autocorrection::RewritePermit.new
+        end
+    end
+
+    # One run of nested classes written together, read for the first that sits before a class naming it.
+    class NestedClasses
+      MESSAGE = "Class `%<expected>s` should be defined before `%<actual>s`, since it names it."
+
+      def initialize(nodes, processed_source, constant_references:, permit:)
+        @nodes = nodes
+        @processed_source = processed_source
+        @constant_references = constant_references
+        @permit = permit
+      end
+
+      def each_offense
+        yield offense if reportable?
+      end
+
+      private
+        attr_reader :nodes, :processed_source, :constant_references, :permit
+        delegate :rewrite, to: :statement_run, private: true
+
+        def reportable?
+          analyzable? && ordered_safely?
+        end
+
+        # Reopening gives one declaration several load positions, so no single reference order can place it truthfully.
+        def analyzable?
+          classes.all?(&:uniquely_declared?) && identities.uniq.size == identities.size
+        end
+
+        def classes
+          @classes ||= nodes.map { NestedClass.new(it, processed_source, constant_references:) }
+        end
+
+        def identities
+          @identities ||= classes.map(&:identity)
+        end
+
+        def ordered_safely?
+          divergence.found? && load_order_kept?
+        end
+
+        def divergence
+          @divergence ||= RuboCop::Callbacksystems::ClassStructure::Divergence.new(identities, from: canonical_order)
+        end
+
+        def canonical_order
+          @canonical_order ||= RuboCop::Callbacksystems::ClassStructure::ReferenceOrder.new(seeds, reference_graph).to_a
+        end
+
+        def seeds
+          identities.reject { referenced.include?(it) } + identities
+        end
+
+        def referenced
+          @referenced ||= reference_graph.values.flatten.to_set
+        end
+
+        def reference_graph
+          @reference_graph ||= graph_of(:reads)
+        end
+
+        def graph_of(reading)
+          classes.to_h { [ it.identity, it.public_send(reading).intersection(identities) ] }
+        end
+
+        # A superclass or a name read outside a method runs as the body loads, so an order breaking one is refused.
+        def load_order_kept?
+          dependency_graph.all? { |name, required| required.all? { loaded_before?(dependency: it, dependent: name) } }
+        end
+
+        def dependency_graph
+          @dependency_graph ||= graph_of(:dependencies)
+        end
+
+        def loaded_before?(dependency:, dependent:)
+          canonical_positions.fetch(dependency) < canonical_positions.fetch(dependent)
+        end
+
+        def canonical_positions
+          @canonical_positions ||= canonical_order.each_with_index.to_h
+        end
+
+        def offense
+          RuboCop::Callbacksystems::Offense.new(nodes[divergence.index], message,
+            correcting: correctable?) { rewrite(it) }
+        end
+
+        def message
+          format(MESSAGE, expected: name_of(divergence.expected), actual: name_of(divergence.actual))
+        end
+
+        def name_of(identity)
+          classes_by_identity.fetch(identity).name
+        end
+
+        def classes_by_identity
+          @classes_by_identity ||= classes.index_by(&:identity)
+        end
+
+        def correctable?
+          uninterrupted? && statement_run.reorderable? && permit.claim
+        end
+
+        # A comment unattached to either class is an intentional boundary, not source for a sortable run.
+        def uninterrupted?
+          classes.each_cons(2).none? { |above, below| above.range.end.join(below.range.begin).source.strip.present? }
+        end
+
+        def statement_run
+          @statement_run ||= RuboCop::Callbacksystems::ClassStructure::StatementRun.new \
+            classes, order: canonical_order, &:identity
+        end
+    end
+
+    class NestedClass
+      include RuboCop::Callbacksystems::Helpers
+
+      delegate :range, :source, :contains_tooling_comment?, to: :block
+
+      def initialize(node, processed_source, constant_references:)
+        @node = node
+        @processed_source = processed_source
+        @constant_references = constant_references
+      end
+
+      def reads
+        referenced_identities_of(constants.select { enclosing_method_of(it).present? })
+      end
+
+      def name
+        node.identifier.short_name
+      end
+
+      def identity
+        declaration&.name
+      end
+
+      def uniquely_declared?
+        declaration.is_a?(Rubydex::Namespace) && declaration.definitions.one?
+      end
+
+      def dependencies
+        referenced_identities_of(superclass_constants + constants.reject { enclosing_method_of(it).present? })
+      end
+
+      private
+        attr_reader :node, :processed_source, :constant_references
+
+        def block
+          @block ||= RuboCop::Callbacksystems::Source::StatementWithComments.new(node, processed_source)
+        end
+
+        def referenced_identities_of(found)
+          found.filter_map { constant_references.referenced_declaration_for(it)&.name }.uniq.excluding(identity)
+        end
+
+        def constants
+          @constants ||= node.each_descendant(:const).to_a
+        end
+
+        def declaration
+          @declaration ||= constant_references.declaration_named(node.identifier.const_name, beside: node.identifier)
+        end
+
+        def superclass_constants
+          node.class_type? && node.parent_class ? node.parent_class.each_node(:const).to_a : []
+        end
+    end
+end

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

@@ -0,0 +1,197 @@
+# Prohibits common abbreviations in declared names, including CamelCase. A
+# full word costs a few keystrokes once and reads at a glance every time after,
+# while an abbreviation makes every reader expand it.
+#
+# @example
+#   # bad
+#   def calc_total
+#   end
+#
+#   # bad
+#   attrs = {}
+#
+#   # bad
+#   USER_ATTRS = %i[name email]
+#
+#   # bad
+#   class UserAttrs
+#   end
+#
+#   # good
+#   def calculate_total
+#   end
+#
+#   # good
+#   attributes = {}
+#
+#   # good
+#   USER_ATTRIBUTES = %i[name email]
+#
+#   # good
+#   class UserAttributes
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoAbbreviations < RuboCop::Cop::Callbacksystems::Base
+  def on_class(node)
+    on_def(node.identifier)
+  end
+
+  alias on_module on_class
+
+  def on_def(node)
+    report_each AbbreviatedName.new(node.loc.name)
+  end
+
+  alias on_defs on_def
+  alias on_lvasgn on_def
+  alias on_match_var on_def
+  alias on_ivasgn on_def
+  alias on_cvasgn on_def
+  alias on_gvasgn on_def
+  alias on_casgn on_def
+  alias on_arg on_def
+  alias on_optarg on_def
+  alias on_restarg on_def
+  alias on_kwarg on_def
+  alias on_kwoptarg on_def
+  alias on_kwrestarg on_def
+  alias on_blockarg on_def
+  alias on_shadowarg on_def
+
+  private
+    # Ruby and Rails conventions stay readable: params, args, id, ids, config, env, info, lib, max, min,
+    # proc(s), temp, sync, and the attr_reader, attr_writer, and attr_accessor APIs.
+    ABBREVIATIONS = {
+      "abbrev" => "abbreviation",
+      "amt" => "amount",
+      "arr" => "array",
+      "attr" => "attribute",
+      "attrs" => "attributes",
+      "btn" => "button",
+      "buf" => "buffer",
+      "calc" => "calculate",
+      "cb" => "callback",
+      "cfg" => "configuration",
+      "cmd" => "command",
+      "conf" => "configuration",
+      "ctx" => "context",
+      "curr" => "current",
+      "decl" => "declaration",
+      "decls" => "declarations",
+      "dep" => "dependency",
+      "deps" => "dependencies",
+      "dest" => "destination",
+      "doc" => "document",
+      "docs" => %w[ documentation documents ],
+      "elem" => "element",
+      "elems" => "elements",
+      "err" => "error",
+      "errs" => "errors",
+      "evt" => "event",
+      "expr" => "expression",
+      "exprs" => "expressions",
+      "func" => "function",
+      "funcs" => "functions",
+      "ident" => "identifier",
+      "idents" => "identifiers",
+      "idx" => "index",
+      "impl" => "implementation",
+      "init" => "initialize",
+      "len" => "length",
+      "libs" => "libraries",
+      "msg" => "message",
+      "msgs" => "messages",
+      "num" => "number",
+      "nums" => "numbers",
+      "obj" => "object",
+      "objs" => "objects",
+      "opt" => "option",
+      "opts" => "options",
+      "org" => "organization",
+      "orgs" => "organizations",
+      "perf" => "performance",
+      "pkg" => "package",
+      "pkgs" => "packages",
+      "pos" => "position",
+      "prev" => "previous",
+      "prop" => "property",
+      "props" => "properties",
+      "ref" => "reference",
+      "refs" => "references",
+      "repo" => "repository",
+      "repos" => "repositories",
+      "req" => "request",
+      "reqs" => "requests",
+      "res" => %w[ resource response result ],
+      "resp" => "response",
+      "sep" => "separator",
+      "src" => "source",
+      "stmt" => "statement",
+      "stmts" => "statements",
+      "str" => "string",
+      "strs" => "strings",
+      "tbl" => "table",
+      "tmp" => "temporary",
+      "val" => "value",
+      "vals" => "values",
+      "var" => "variable",
+      "vars" => "variables",
+      "ver" => "version"
+    }
+
+    # Word boundaries preserve acronyms and source offsets while recognizing both snake_case and CamelCase names.
+    class AbbreviatedName
+      MESSAGE = "Avoid abbreviation `%<abbreviation>s`. Use %<full>s instead."
+      WORD_PATTERN = /[[:upper:]]+(?=[[:upper:]][[:lower:]]|[^[:alpha:]]|\z)|[[:upper:]]?[[:lower:]]+/
+      NEXT_WORD_PATTERN = /\A_?(#{WORD_PATTERN})/
+      ATTRIBUTE_ACCESSORS = %w[ accessor reader writer ]
+
+      def initialize(range)
+        @range = range
+      end
+
+      def each_offense
+        range&.source&.scan(WORD_PATTERN) do
+          match = Regexp.last_match
+          if abbreviation_at?(match)
+            yield RuboCop::Callbacksystems::Offense.new(location_of(match), message_for(match.to_s))
+          end
+        end
+      end
+
+      private
+        attr_reader :range
+
+        def abbreviation_at?(match)
+          ABBREVIATIONS.key?(match.to_s.downcase) && !attribute_accessor_at?(match)
+        end
+
+        def attribute_accessor_at?(match)
+          match.to_s.casecmp?("attr") && range.source[match.end(0)..].match(NEXT_WORD_PATTERN)&.then do |following|
+            ATTRIBUTE_ACCESSORS.include?(following.captures.first.downcase)
+          end
+        end
+
+        def location_of(match)
+          range.with(begin_pos: range.begin_pos + match.begin(0), end_pos: range.begin_pos + match.end(0))
+        end
+
+        def message_for(word)
+          format(MESSAGE, abbreviation: word, full: replacements_for(word))
+        end
+
+        def replacements_for(word)
+          Array(ABBREVIATIONS[word.downcase]).map { "`#{replacement_for(word, with: it)}`" }.join(" or ")
+        end
+
+        def replacement_for(word, with:)
+          if word == word.upcase
+            with.upcase
+          elsif word.start_with?(/[[:upper:]]/)
+            with.capitalize
+          else
+            with
+          end
+        end
+    end
+end

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

@@ -0,0 +1,101 @@
+# Detects private methods that only delegate to a newly created object.
+# Such methods add indirection without value and should be inlined or reconsidered.
+# Public methods and predicates are excluded as they often provide semantic value.
+#
+# @example
+#   # bad - private method only creates object and calls single method
+#   private
+#     def eager_loading_association(body)
+#       ScopeBody.new(body).eager_loading_association
+#     end
+#
+#   # good - inline the call
+#   ScopeBody.new(body).eager_loading_association
+#
+#   # good - public method (may be API)
+#   def eager_loading_association(body)
+#     ScopeBody.new(body).eager_loading_association
+#   end
+#
+#   # good - predicate adds semantic meaning
+#   def valid?
+#     Validator.new(self).valid?
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoAnemicDelegation < RuboCop::Cop::Callbacksystems::Base
+  def on_def(node)
+    report MethodDelegation.new(node)
+  end
+
+  alias on_defs on_def
+
+  private
+    class MethodDelegation
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Method `%<method>s` only delegates to `%<class>s.new(...).%<target>s`. Consider inlining or " \
+        "removing this method."
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if anemic_delegation?
+      end
+
+      private
+        attr_reader :node
+        delegate :body, to: :node, private: true
+
+        def anemic_delegation?
+          eligible_method? && delegates_only_parameters?
+        end
+
+        def eligible_method?
+          single_send_private_non_predicate?(node) && direct_method_declaration?
+        end
+
+        def direct_method_declaration?
+          owner && transparent_parents?
+        end
+
+        def owner
+          @owner ||= enclosing_class_or_module_of(node)
+        end
+
+        def transparent_parents?
+          node.each_ancestor.take_while { !it.equal?(owner) }.all? { transparent_method_parent?(it) }
+        end
+
+        def transparent_method_parent?(parent)
+          parent.type?(:begin, :kwbegin, :sclass) || visibility_applied_to(parent, node)
+        end
+
+        def delegates_only_parameters?
+          receiver_is_new_instance? && passes_only_parameters?
+        end
+
+        def receiver_is_new_instance?
+          body.receiver&.send_type? &&
+            body.receiver.method?(:new) &&
+            body.receiver.receiver&.const_type?
+        end
+
+        def passes_only_parameters?
+          invocation_arguments.all? { it.lvar_type? && parameter_names.include?(it.name) }
+        end
+
+        def invocation_arguments
+          body.receiver.arguments + body.arguments
+        end
+
+        def parameter_names
+          @parameter_names ||= node.arguments.children.filter_map { it.name if it.respond_to?(:name) }
+        end
+
+        def message
+          format(MESSAGE, method: node.method_name, class: body.receiver.receiver.short_name, target: body.method_name)
+        end
+    end
+end