rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,247 @@
+# A nested class with no body declares that something exists, most often an
+# error. Written as a constant it says so in one line and stops looking like a
+# class that lost its body.
+#
+# Only nested definitions are reported. A class living in its own file is that
+# file's subject, and `class` reads as the heading it is.
+#
+# @example
+#   # bad
+#   class Configuration
+#     class Error < StandardError; end
+#
+#     def call
+#     end
+#   end
+#
+#   # good
+#   class Configuration
+#     Error = Class.new(StandardError)
+#
+#     def call
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PreferClassNewForEmptyNestedClass < RuboCop::Cop::Callbacksystems::Base
+  include RuboCop::Callbacksystems::ProjectIndex::Support
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_class(node)
+    report EmptyNestedClass.new \
+      node,
+      RuboCop::Callbacksystems::Source::Comments.for(processed_source),
+      assignment_safe: assignment_safe?(node)
+  end
+
+  private
+    def assignment_safe?(node)
+      if node.identifier.namespace.nil? && project_index_reliable?
+        declaration = resolve_constant_in_index(node.identifier)
+
+        declaration.is_a?(Rubydex::Class) && DeclarationHistory.new(
+          declaration,
+          node,
+          file: processed_source.file_path
+        ).new_at_node?
+      else
+        false
+      end
+    end
+
+    # A class declaration can become an assignment only when this node creates the constant. Later declarations in the
+    # same file still see that class, while an earlier or externally ordered definition could be overwritten.
+    class DeclarationHistory
+      def initialize(declaration, node, file:)
+        @declaration = declaration
+        @node = node
+        @file = file
+      end
+
+      def new_at_node?
+        current_definition && owners_known? && definitions.all? do |definition|
+          definition.equal?(current_definition) || later_in_current_file?(definition)
+        end
+      end
+
+      private
+        attr_reader :declaration, :node, :file
+
+        def current_definition
+          @current_definition ||= definitions.find do |definition|
+            definition.is_a?(Rubydex::ClassDefinition) && same_location?(definition.location, node.source_range)
+          end
+        end
+
+        def definitions
+          @definitions ||= declaration.definitions.to_a
+        end
+
+        def same_location?(location, range)
+          same_file?(location) && RuboCop::Callbacksystems::ProjectIndex::Location.for_rubydex(location) ==
+            RuboCop::Callbacksystems::ProjectIndex::Location.for_ast(range, uri: location.uri)
+        end
+
+        def same_file?(location)
+          File.identical?(location.to_file_path, file)
+        rescue SystemCallError, Rubydex::Location::NotFileUriError
+          false
+        end
+
+        # A definition beneath a placeholder namespace can be real, but Rubydex cannot prove what an autoloader may
+        # already have installed there. Every owner up to Object therefore needs a declaration of its own.
+        def owners_known?
+          owner_chain_known_from?(declaration.owner)
+        end
+
+        def owner_chain_known_from?(owner)
+          owner.name == "Object" || (owner.definitions.any? && owner_chain_known_from?(owner.owner))
+        end
+
+        def later_in_current_file?(definition)
+          same_file?(definition.location) && after_current_definition?(definition.location)
+        end
+
+        def after_current_definition?(location)
+          ([ location.start_line, location.start_column ] <=> current_position).positive?
+        end
+
+        def current_position
+          @current_position ||= current_definition.location.then { [ it.start_line, it.start_column ] }
+        end
+    end
+
+    class EmptyNestedClass
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Declare `%<name>s` as `Class.new` instead of a class definition with no body."
+
+      def initialize(node, source_comments, assignment_safe:)
+        @node = node
+        @source_comments = source_comments
+        @assignment_safe = assignment_safe
+      end
+
+      def offense
+        if node.body.nil? && nested?
+          RuboCop::Callbacksystems::Offense.new(node, message, correcting: correctable?) { correct(it) }
+        end
+      end
+
+      private
+        attr_reader :node, :source_comments, :assignment_safe
+
+        def nested?
+          enclosing_class_or_module_of(node).present?
+        end
+
+        def message
+          format(MESSAGE, name: class_name_of(node))
+        end
+
+        def correctable?
+          assignment_safe && expression_result.discarded? && superclass_without_heredoc? &&
+            comments.none? { tooling_comment?(it) }
+        end
+
+        def expression_result
+          @expression_result ||= RuboCop::Callbacksystems::Execution::DiscardedExpression.new(node)
+        end
+
+        def superclass_without_heredoc?
+          node.parent_class.nil? || !carries_heredoc?(node.parent_class)
+        end
+
+        def comments
+          @comments ||= [ *source_comments.within(node), closing_comment ]
+            .compact.uniq.sort_by { it.source_range.begin_pos }
+        end
+
+        def closing_comment
+          @closing_comment ||= source_comments.trailing_comment_on(node.last_line)&.then do |comment|
+            comment if directly_trails_definition?(comment)
+          end
+        end
+
+        def directly_trails_definition?(comment)
+          node.source_range.with(begin_pos: node.source_range.end_pos, end_pos: comment.source_range.begin_pos)
+            .source.match?(/\A[ \t]*;?[ \t]*\z/)
+        end
+
+        def correct(corrector)
+          corrector.replace(correction_range, corrected_source)
+        end
+
+        def correction_range
+          closing_comment ? node.source_range.join(closing_comment.source_range) : node.source_range
+        end
+
+        def corrected_source
+          CommentedDeclaration.new(declaration, movable_comments, indentation:).source
+        end
+
+        def declaration
+          "#{class_name_of(node)} = Class.new#{inherited_class}"
+        end
+
+        def inherited_class
+          "(#{node.parent_class.source})" if node.parent_class
+        end
+
+        def movable_comments
+          comments.reject { superclass_contains?(it) }
+        end
+
+        def superclass_contains?(comment)
+          node.parent_class&.source_range&.contains?(comment.source_range)
+        end
+
+        def indentation
+          preceding = node.source_range.source_line[0...node.source_range.column]
+
+          preceding.strip.empty? ? preceding : " " * node.source_range.column
+        end
+
+        # Comments from the definition keep their order around the declaration, with one former trailing comment still
+        # trailing code and every other comment standing on its own line.
+        class CommentedDeclaration
+          include RuboCop::Callbacksystems::Helpers
+
+          def initialize(declaration, comments, indentation:)
+            @declaration = declaration
+            @comments = comments
+            @indentation = indentation
+          end
+
+          def source
+            [ *before, declaration_with_comment, *after ].join("\n#{indentation}")
+          end
+
+          private
+            attr_reader :declaration, :comments, :indentation
+
+            def before
+              comments.take(anchor_position).map(&:text)
+            end
+
+            def anchor_position
+              @anchor_position ||= comments.index { !own_line_comment?(it) } || comments.size
+            end
+
+            def declaration_with_comment
+              [ declaration, anchor&.text ].compact.join(" ")
+            end
+
+            def anchor
+              comments[anchor_position] unless anchor_position == comments.size
+            end
+
+            def after
+              comments.drop(anchor_position + anchor_count).map(&:text)
+            end
+
+            def anchor_count
+              anchor ? 1 : 0
+            end
+        end
+    end
+end

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

@@ -0,0 +1,124 @@
+# A `Data.define`, `Struct.new` or `Class.new` given a block defines a class
+# with behavior, so it reads better as the class it is.
+#
+# The block form also changes what the code inside it means. A constant
+# declared there lands in the enclosing namespace instead of the new class,
+# `Module.nesting` never mentions the class, and the rules that govern a class
+# body do not reach inside a block.
+#
+# A builder with no block only lists its members and stays as it is.
+#
+# @example
+#   # bad
+#   Route = Data.define(:host) do
+#     def matches?(other)
+#       host == other
+#     end
+#   end
+#
+#   # good
+#   class Route < Data.define(:host)
+#     def matches?(other)
+#       host == other
+#     end
+#   end
+#
+#   # good - nothing but its members
+#   Entry = Data.define(:sku, :quantity)
+#
+class RuboCop::Cop::Callbacksystems::PreferClassOverBuilderBlock < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_casgn(node)
+    report BuilderBlock.new(node)
+  end
+
+  private
+    class BuilderBlock
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Define `%<name>s` as a class instead of a block given to `%<builder>s`."
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        if class_with_body?(node)
+          RuboCop::Callbacksystems::Offense.new(node, message, correcting: rewritable?) { correct(it) }
+        end
+      end
+
+      private
+        attr_reader :node
+
+        def message
+          format(MESSAGE, name: assigned_name, builder: builder_name)
+        end
+
+        def assigned_name
+          node.source_range.with(end_pos: node.loc.operator.begin_pos).source.rstrip
+        end
+
+        def builder_name
+          "#{builder_call.receiver.source}.#{builder_call.method_name}"
+        end
+
+        def builder_call
+          block.send_node
+        end
+
+        def block
+          node.expression
+        end
+
+        # Only `do ... end` is rewritten, since anything else needs the body moved onto its own lines to stay valid.
+        def rewritable?
+          block.multiline? && block.loc.begin.source == "do" && block.argument_list.empty? &&
+            !captures_local_variable? && !reads_or_assigns_constant? && !reads_or_assigns_class_variable? &&
+            !builder_control_flow?
+        end
+
+        def captures_local_variable?
+          nodes_in(block.body, :lvar).any? do |read|
+            read.each_ancestor(:any_def).none? &&
+              !name_rebound_between?(read.name, node: read, boundary: block)
+          end
+        end
+
+        def reads_or_assigns_constant?
+          nodes_in(block.body, :const, :casgn).any?
+        end
+
+        def reads_or_assigns_class_variable?
+          nodes_in(block.body, :cvar, :cvasgn).any?
+        end
+
+        def builder_control_flow?
+          nodes_in(block.body, :break, :next, :redo).any? do |flow|
+            flow.each_ancestor(*BLOCK_NODE_TYPES).first.equal?(block)
+          end
+        end
+
+        def correct(corrector)
+          corrector.replace(header, "class #{assigned_name}#{inheritance}")
+        end
+
+        def header
+          node.source_range.with(end_pos: block.loc.begin.end_pos)
+        end
+
+        # `Class.new(Base)` is a plain subclass of `Base`, while `Data.define` and `Struct.new` build the superclass.
+        def inheritance
+          plain_subclass? ? argument_inheritance : " < #{builder_call.source}"
+        end
+
+        def plain_subclass?
+          builder_call.receiver.short_name == :Class
+        end
+
+        def argument_inheritance
+          " < #{builder_call.first_argument.source}" if builder_call.first_argument
+        end
+    end
+end

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

@@ -0,0 +1,225 @@
+# Detects a parameter given its fallback value at the top of the method. A
+# `||=` or a `nil?` guard opening the body makes the reader work out what the
+# parameter really is, where a default in the signature says it right where the
+# parameter is declared, so the body starts with the work.
+#
+# The cop recommends the change for a positional parameter and a keyword
+# declared as `name: nil`. It leaves a required keyword alone, since a default
+# would change what callers must pass, as well as a fallback reading a parameter
+# declared to its right, which a default cannot see. Only the run of fallbacks
+# opening the body counts: one that follows other statements may depend on them.
+#
+# The offense has no automatic correction. A default only runs when an argument
+# is omitted, while these fallbacks also run for an explicit `nil` or `false`;
+# making a required positional parameter optional changes its observable arity
+# too. Choosing the new calling contract belongs to the author.
+#
+# @example
+#   # bad
+#   def deliver(recipients)
+#     recipients ||= [ owner ]
+#     recipients.each { mail(it) }
+#   end
+#
+#   # bad
+#   def deliver(recipients: nil)
+#     recipients = [ owner ] if recipients.nil?
+#     recipients.each { mail(it) }
+#   end
+#
+#   # good
+#   def deliver(recipients = [ owner ])
+#     recipients.each { mail(it) }
+#   end
+#
+#   # good
+#   def deliver(recipients: [ owner ])
+#     recipients.each { mail(it) }
+#   end
+#
+#   # good - a default cannot read a parameter to its right
+#   def deliver(recipients, sender)
+#     recipients ||= [ sender ]
+#     recipients.each { mail(it) }
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PreferDefaultArgument < RuboCop::Cop::Callbacksystems::Base
+  def on_def(node)
+    report_each LeadingFallbacks.new(node)
+  end
+
+  alias on_defs on_def
+
+  private
+    # The fallbacks opening a method body, one per parameter, narrowed to those expressible as a signature default.
+    class LeadingFallbacks
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(method_node)
+        @method_node = method_node
+      end
+
+      def each_offense
+        reportable.each { yield it.offense } if followed_by_work?
+      end
+
+      private
+        attr_reader :method_node
+
+        def followed_by_work?
+          statements.size > leading.size
+        end
+
+        def statements
+          statements_in(method_node.body)
+        end
+
+        def leading
+          @leading ||= statements.map { Fallback.new(it, method_node) }.take_while(&:fallback?).uniq(&:name)
+        end
+
+        # Ruby allows one group of optional positional parameters, so a recommendation must not open a second one.
+        def reportable
+          optional_group_stays_contiguous? ? candidates : candidates.select(&:keyword?)
+        end
+
+        def optional_group_stays_contiguous?
+          optional_runs.size <= 1
+        end
+
+        def optional_runs
+          positional_parameters
+            .chunk_while { |left, right| optional_with_candidate?(left) == optional_with_candidate?(right) }
+            .select { optional_with_candidate?(it.first) }
+        end
+
+        def positional_parameters
+          method_node.arguments.select { it.type?(:arg, :optarg) }
+        end
+
+        def optional_with_candidate?(parameter)
+          parameter.optarg_type? || candidates.any? { it.parameter.equal?(parameter) }
+        end
+
+        def candidates
+          @candidates ||= leading.select(&:reportable?)
+        end
+    end
+
+    class Fallback
+      include RuboCop::Callbacksystems::Helpers
+      extend RuboCop::AST::NodePattern::Macros
+
+      MESSAGE = "Give `%<name>s` its default in the signature instead of a fallback in the body."
+
+      # @!method fallback_of(node)
+      def_node_matcher :fallback_of, <<~PATTERN
+        {
+          (or_asgn (lvasgn $_name) $_value)
+          (if (send (lvar $_name) :nil?) (lvasgn _name $_value) nil?)
+          (if (lvar $_name) nil? (lvasgn _name $_value))
+        }
+      PATTERN
+
+      def initialize(statement, method_node)
+        @statement = statement
+        @method_node = method_node
+      end
+
+      def fallback?
+        parameter.present?
+      end
+
+      def parameter
+        @parameter ||= named_parameters.find { it.name == name } if name
+      end
+
+      def name
+        captures&.first
+      end
+
+      def keyword?
+        parameter.kwoptarg_type?
+      end
+
+      def reportable?
+        defaultable? && value.single_line? && !carries_heredoc?(value) && !reads_parameter_from_itself_on? &&
+          alone_on_its_lines?
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(statement, format(MESSAGE, name:))
+      end
+
+      private
+        attr_reader :statement, :method_node
+
+        def captures
+          @captures ||= fallback_of(statement)
+        end
+
+        def named_parameters
+          method_node.arguments.reject(&:mlhs_type?)
+        end
+
+        def defaultable?
+          (parameter.arg_type? && !positional_parameter_after_rest?) ||
+            (keyword? && parameter.default_value.nil_type?)
+        end
+
+        def positional_parameter_after_rest?
+          method_node.arguments.take_while { !it.equal?(parameter) }.any?(&:restarg_type?)
+        end
+
+        def value
+          captures.second
+        end
+
+        def reads_parameter_from_itself_on?
+          nodes_in(value, :lvar).any? do |read|
+            parameter_names_from_itself_on.include?(read.name) &&
+              !name_rebound_between?(read.name, node: read, boundary: method_node)
+          end
+        end
+
+        def parameter_names_from_itself_on
+          method_node.arguments.drop_while { !it.equal?(parameter) }.flat_map { ParameterNames.new(it).to_a }
+        end
+
+        def alone_on_its_lines?
+          statement.first_line > method_node.first_line && statement.last_line < next_code_line
+        end
+
+        def next_code_line
+          statement.right_sibling.first_line
+        end
+    end
+
+    # Names introduced by one argument, including the leaves of a destructured positional argument.
+    class ParameterNames
+      include Enumerable
+
+      def initialize(parameter)
+        @parameter = parameter
+      end
+
+      def each
+        if block_given?
+          pending = [ parameter ]
+          until pending.empty?
+            current = pending.pop
+            if current.mlhs_type?
+              pending.concat(current.each_child_node.to_a.reverse)
+            elsif current.respond_to?(:name) && current.name
+              yield current.name
+            end
+          end
+        else
+          to_enum(__method__)
+        end
+      end
+
+      private
+        attr_reader :parameter
+    end
+end