rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,286 @@
+# A class whose whole body is class-level code should be a module with
+# `extend self`. Classes are for making instances.
+#
+# `Style/StaticClass` covers the plain case, but it abstains as soon as the
+# singleton section has a private part, because the `module_function` it
+# corrects to stops copying methods to the singleton once `private` switches
+# the mode, which breaks every call to them. `extend self` carries the
+# visibility over untouched, so that case is reported here instead.
+#
+# @example
+#   # bad - class methods only, with a private helper
+#   class Architecture
+#     class << self
+#       def resolve(reports)
+#         normalize(reports)
+#       end
+#
+#       private
+#         def normalize(raw)
+#           raw.downcase
+#         end
+#     end
+#   end
+#
+#   # good
+#   module Architecture
+#     extend self
+#
+#     def resolve(reports)
+#       normalize(reports)
+#     end
+#
+#     private
+#       def normalize(raw)
+#         raw.downcase
+#       end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PreferModuleForStaticClass < RuboCop::Cop::Callbacksystems::Base
+  include RuboCop::Callbacksystems::ProjectIndex::Support
+
+  def on_class(node)
+    if project_index_reliable?
+      inspect_candidate StaticClass.new(node), node:
+    end
+  end
+
+  private
+    def inspect_candidate(analysis, node:)
+      declaration = convertible_declaration_of(node) if analysis.candidate?
+      report analysis if declaration && module_preferred?(analysis, declaration:)
+    end
+
+    def convertible_declaration_of(node)
+      declaration = resolve_constant_in_index(node.identifier)
+      declaration if declaration.is_a?(Rubydex::Class) && project_declaration_reliable?(declaration)
+    end
+
+    def module_preferred?(analysis, declaration:)
+      analysis.compatible_with_module?(declaration) && !class_required?(declaration)
+    end
+
+    def class_required?(declaration)
+      inherited_callback_observable? || definitions_in_other_files(declaration.definitions).any? ||
+        !declaration.definitions.one? ||
+        declaration.descendants.any? { it.name != declaration.name } ||
+        !project_references.compatible_with_module?(declaration)
+    end
+
+    def inherited_callback_observable?
+      [ project_index["Object"].singleton_class, project_index["Class"] ].compact.any? do |namespace|
+        namespace.find_member("inherited()")&.definitions&.any?
+      end
+    end
+
+    def project_references
+      ProjectReferences.for(project_index)
+    end
+
+    # Every reference must prove that replacing the declaration with a module preserves what that line does.
+    class ProjectReferences
+      extend RuboCop::Callbacksystems::ProjectIndex::Cache
+
+      def initialize(project_index)
+        @method_references_by_receiver = grouped_references(project_index.method_references) { receiver_name_of(it) }
+        @constant_references_by_owner = grouped_references(project_index.constant_references) { owner_name_of(it) }
+      end
+
+      def compatible_with_module?(declaration)
+        declaration.references.all? do |reference|
+          ReferenceUse.new(
+            reference,
+            declaration:,
+            method_references: method_references_for(declaration),
+            constant_references: constant_references_for(declaration)
+          ).compatible?
+        end
+      end
+
+      private
+        attr_reader :method_references_by_receiver, :constant_references_by_owner
+
+        def grouped_references(references)
+          references.each_with_object({}) do |reference, groups|
+            yield(reference)&.then do |group|
+              locations = groups[group] ||= {}
+              (locations[location_key(reference.location)] ||= []) << reference
+            end
+          end
+        end
+
+        def location_key(location)
+          [ location.uri, location.start_line, location.start_column ]
+        end
+
+        def receiver_name_of(reference)
+          receiver = reference.receiver
+          receiver.attached_class.name if receiver.is_a?(Rubydex::SingletonClass)
+        end
+
+        def owner_name_of(reference)
+          reference.declaration.owner.name if reference.is_a?(Rubydex::ResolvedConstantReference)
+        end
+
+        def method_references_for(declaration)
+          method_references_by_receiver.fetch(declaration.name) { {} }
+        end
+
+        def constant_references_for(declaration)
+          constant_references_by_owner.fetch(declaration.name) { {} }
+        end
+
+        class ReferenceUse
+          def initialize(reference, declaration:, method_references:, constant_references:)
+            @reference = reference
+            @declaration = declaration
+            @method_references = method_references
+            @constant_references = constant_references
+          end
+
+          def compatible?
+            direct_declared_method? || namespace_reference?
+          end
+
+          private
+            attr_reader :reference, :declaration, :method_references, :constant_references
+
+            def direct_declared_method?
+              adjacent_references_in(method_references).any? { declared_on_singleton?(it.name) }
+            end
+
+            def adjacent_references_in(references, separator_width: nil)
+              expected_columns(separator_width).flat_map do |column|
+                references.fetch(location_key(column)) { [] }
+              end
+            end
+
+            def expected_columns(separator_width)
+              widths = separator_width ? [ separator_width ] : [ 1, 2 ]
+              widths.to_set { reference.location.end_column + it }
+            end
+
+            def location_key(column)
+              [ reference.location.uri, reference.location.end_line, column ]
+            end
+
+            def declared_on_singleton?(method_name)
+              declaration.singleton_class.member("#{method_name}()").present?
+            end
+
+            def namespace_reference?
+              adjacent_references_in(constant_references, separator_width: 2).any?
+            end
+        end
+    end
+
+    class StaticClass
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Prefer a module with `extend self` to a class holding only class methods."
+      CLASS_ONLY_CALLBACKS = %i[ inherited ]
+      VISIBILITY_METHODS = %i[ private protected public ]
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, MESSAGE)
+      end
+
+      def candidate?
+        convertible? && private_singleton_section?
+      end
+
+      def compatible_with_module?(declaration)
+        !class_semantics_used? && singleton_calls_owned_by?(declaration)
+      end
+
+      private
+        attr_reader :node
+
+        def convertible?
+          node.parent_class.nil? && only_class_level_statements?
+        end
+
+        def only_class_level_statements?
+          statements.any? && statements.all? { class_level_statement?(it) }
+        end
+
+        def statements
+          @statements ||= statements_in(node.body)
+        end
+
+        def class_level_statement?(statement)
+          statement.type?(:casgn, :defs) || extend_call?(statement) || singleton_section?(statement)
+        end
+
+        def extend_call?(statement)
+          bare_send?(statement) && statement.method?(:extend)
+        end
+
+        def private_singleton_section?
+          statements.select { singleton_section?(it) }.any? { holds_private_section?(it) }
+        end
+
+        def holds_private_section?(section)
+          private_modifier_in(section.body).present?
+        end
+
+        def class_semantics_used?
+          class_only_callback_defined? || method_name_rebound? || singleton_super? || self_value_used?
+        end
+
+        def class_only_callback_defined?
+          nodes_in(node.body, :def, :defs).any? { CLASS_ONLY_CALLBACKS.include?(it.method_name) }
+        end
+
+        def method_name_rebound?
+          nodes_in(node.body, :alias, :undef).any? || nodes_in(node.body, :send, :csend).any? do |send_node|
+            send_node.method?(:alias_method) || send_node.method?(:undef_method)
+          end
+        end
+
+        def singleton_super?
+          nodes_in(node.body, :super, :zsuper).any?
+        end
+
+        def self_value_used?
+          nodes_in(node.body, :self).any? do |self_node|
+            enclosing_class_or_module_of(self_node).equal?(node) && !structural_self?(self_node)
+          end
+        end
+
+        def singleton_calls_owned_by?(declaration)
+          candidate_singleton_calls.all? do |send_node|
+            visibility_modifier?(send_node) || owned_method?(send_node.method_name, declaration:)
+          end
+        end
+
+        def candidate_singleton_calls
+          nodes_in(node.body, :send, :csend).select do |send_node|
+            call_on_self?(send_node) && candidate_singleton_domain?(send_node)
+          end
+        end
+
+        def candidate_singleton_domain?(send_node)
+          RuboCop::Callbacksystems::Methods::Domain.new(send_node).then do |domain|
+            (domain.container.equal?(node) && domain.identity.present? && domain.identity.all? { it == :self }) ||
+              opaque_block_in_candidate?(domain.container)
+          end
+        end
+
+        def opaque_block_in_candidate?(container)
+          any_block_type?(container) && enclosing_class_or_module_of(container).equal?(node)
+        end
+
+        def visibility_modifier?(send_node)
+          enclosing_method_of(send_node).nil? && VISIBILITY_METHODS.include?(send_node.method_name)
+        end
+
+        def owned_method?(method_name, declaration:)
+          declaration.singleton_class.member("#{method_name}()").present?
+        end
+    end
+end

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

@@ -0,0 +1,136 @@
+# Detects array access with numeric indices that could use ordinal methods.
+# `items.second` says which element it wants, where `items[1]` makes the
+# reader count from zero.
+#
+# `[]` answers for a Hash, a MatchData and a String too, and the ordinal methods
+# come from Array alone, so a receiver we can read as one of those is left alone.
+# That includes a receiver read out of another `[]`, whose type the file never
+# shows, and a local variable whose assignment in the same scope hands it one of
+# those.
+#
+# @example
+#   # bad
+#   items[1]
+#   items[2]
+#   items[3]
+#   items[4]
+#   items[-2]
+#   items[-3]
+#
+#   # good
+#   items.second
+#   items.third
+#   items.fourth
+#   items.fifth
+#   items.second_to_last
+#   items.third_to_last
+#
+class RuboCop::Cop::Callbacksystems::PreferOrdinalArrayAccess < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_new_investigation
+    @local_variables = RuboCop::Callbacksystems::Execution::LocalVariableOccurrences.new(processed_source.ast)
+    @source_comments = RuboCop::Callbacksystems::Source::Comments.for(processed_source)
+  end
+
+  def on_send(node)
+    report IndexedRead.new(node, @local_variables, @source_comments)
+  end
+
+  alias on_csend on_send
+
+  private
+    ORDINAL_METHODS = {
+      1 => :second,
+      2 => :third,
+      3 => :fourth,
+      4 => :fifth,
+      -2 => :second_to_last,
+      -3 => :third_to_last
+    }
+
+    NON_ARRAY_LITERAL_TYPES = %i[ dsym hash int regexp sym ]
+    # `[]` reads out of anything, `match` and its friends answer a MatchData, and the rest answer a Hash.
+    NON_ARRAY_RESULT_METHODS = %i[
+      [] last_match match match? named_captures to_h to_hash group_by index_by index_with tally params
+    ]
+
+    # One `items[1]`, offending when an ordinal method names that position and nothing says the receiver is no array.
+    class IndexedRead
+      include RuboCop::Callbacksystems::Helpers
+      extend RuboCop::AST::NodePattern::Macros
+
+      MESSAGE = "Use `%<method>s` instead of `[%<index>s]`."
+
+      # @!method bracket_access_with_int?(node)
+      def_node_matcher :bracket_access_with_int?, <<~PATTERN
+        (call $_ :[] (int $_index))
+      PATTERN
+
+      def initialize(node, local_variables, source_comments)
+        @node = node
+        @local_variables = local_variables
+        @source_comments = source_comments
+      end
+
+      def offense
+        if ordinal_method && array_receiver?
+          RuboCop::Callbacksystems::Offense.new(node, message, correcting: correction_keeps_comments?) { correct(it) }
+        end
+      end
+
+      private
+        attr_reader :node, :local_variables, :source_comments
+
+        def ordinal_method
+          ORDINAL_METHODS[index] if captures
+        end
+
+        def captures
+          @captures ||= bracket_access_with_int?(node)
+        end
+
+        def index
+          captures.second
+        end
+
+        def array_receiver?
+          !non_array_value?(receiver) && !assigned_a_non_array?
+        end
+
+        def non_array_value?(value)
+          reads_as_string?(value) ||
+            reads_as?(value, literals: NON_ARRAY_LITERAL_TYPES, methods: NON_ARRAY_RESULT_METHODS)
+        end
+
+        def receiver
+          captures.first
+        end
+
+        def assigned_a_non_array?
+          receiver.lvar_type? && assignments.any? do |assignment|
+            assignment.match_var_type? || assignment.expression.nil? || non_array_value?(assignment.expression)
+          end
+        end
+
+        def assignments
+          local_variables.named(receiver.name, around: receiver).select { it.type?(:lvasgn, :match_var) }
+        end
+
+        def message
+          format(MESSAGE, method: ordinal_method, index: index)
+        end
+
+        def correction_keeps_comments?
+          !source_comments.any_within?(node)
+        end
+
+        def correct(corrector)
+          corrector.replace(node, "#{receiver.source}#{call_operator}#{ordinal_method}")
+        end
+
+        def call_operator
+          node.csend_type? ? "&." : "."
+        end
+    end
+end

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

@@ -0,0 +1,265 @@
+# A negative `return unless` guard followed by a happy path reads more naturally
+# as `if condition; ...; end`. The wrap adds one `if` block, so it is only applied when
+# the happy path's own nesting plus that extra level still fits inside the
+# configured `Metrics/BlockNesting` limit; anything past that would push the
+# method past the nesting limit. Method-length rules already cap how long a
+# happy path can be, so the only real cost of the wrap is the indent level it adds.
+#
+# @example
+#   # bad - leading negative guard
+#   def label
+#     return unless ready?
+#     compute_label
+#   end
+#
+#   # good - positive wrap
+#   def label
+#     if ready?
+#       compute_label
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PreferPositiveWrap < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_def(node)
+    report Guard.new(node.body, processed_source, nesting: block_nesting)
+  end
+
+  alias on_defs on_def
+
+  private
+    def block_nesting
+      BlockNesting.new(config.for_cop("Metrics/BlockNesting"))
+    end
+
+    # The configured core metric, reduced to the one question this rewrite needs to ask.
+    class BlockNesting
+      NESTING_TYPES = %i[ case case_match if while while_post until until_post for resbody ].to_set
+
+      def initialize(config)
+        @max = config["Max"]
+        @count_blocks = config.fetch("CountBlocks", false)
+        @count_modifier_forms = config.fetch("CountModifierForms", false)
+      end
+
+      def allows_wrap?(nodes)
+        nodes.map { depth_of(it) }.max.to_i + 1 <= max
+      end
+
+      private
+        attr_reader :max, :count_blocks, :count_modifier_forms
+
+        def depth_of(node)
+          {}.compare_by_identity.then do |depths|
+            Descendants.new(node).to_a.reverse_each do |descendant|
+              depths[descendant] = (counts?(descendant) ? 1 : 0) +
+                descendant.each_child_node.map { depths.fetch(it) }.max.to_i
+            end
+            depths.fetch(node)
+          end
+        end
+
+        def counts?(node)
+          NESTING_TYPES.include?(node.type) ? counts_control_flow?(node) : count_blocks && node.any_block_type?
+        end
+
+        def counts_control_flow?(node)
+          !node.if_type? || counts_if?(node)
+        end
+
+        def counts_if?(node)
+          !node.elsif? && (!node.modifier_form? || count_modifier_forms)
+        end
+
+        class Descendants
+          include Enumerable
+
+          def initialize(root)
+            @root = root
+          end
+
+          def each
+            if block_given?
+              pending = [ root ]
+              until pending.empty?
+                node = pending.pop
+                yield node
+                pending.concat(node.each_child_node.to_a.reverse)
+              end
+            else
+              to_enum(__method__)
+            end
+          end
+
+          private
+            attr_reader :root
+        end
+    end
+
+    # The leading negative guard inside a method body, plus the happy path that follows it.
+    class Guard
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Wrap positively: `if condition; ...; end` instead of a leading negative guard."
+
+      def initialize(body, processed_source, nesting:)
+        @body = body
+        @processed_source = processed_source
+        @source_comments = RuboCop::Callbacksystems::Source::Comments.for(processed_source)
+        @nesting = nesting
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(guard, MESSAGE, correcting: correctable?) { correct(it) } if wrappable?
+      end
+
+      private
+        attr_reader :body, :processed_source, :source_comments, :nesting
+
+        def wrappable?
+          statements.size >= 2 && negative_return_guard?(guard) && nesting.allows_wrap?(happy)
+        end
+
+        def statements
+          statements_in(body)
+        end
+
+        def negative_return_guard?(node)
+          node.if_type? && node.unless? && node.if_branch&.return_type?
+        end
+
+        def guard
+          statements.first
+        end
+
+        def happy
+          statements.drop(1)
+        end
+
+        # An existing `else` is observable on the positive path and cannot be folded into this rewrite.
+        def correctable?
+          guard_shape_correctable? && rewrite_preserves_source?
+        end
+
+        def guard_shape_correctable?
+          guard.else_branch.nil? && guard_value_stands_alone?
+        end
+
+        def guard_value_stands_alone?
+          guard_values.size != 1 || !unpackaged_splat?(guard_values.first)
+        end
+
+        def guard_values
+          guard.if_branch.children
+        end
+
+        def unpackaged_splat?(value)
+          value.splat_type? || (value.hash_type? && !value.braces?)
+        end
+
+        def rewrite_preserves_source?
+          comments_preserved? && heredocs_preserved?
+        end
+
+        def comments_preserved?
+          comments_in_replacement.all? { preserved_comment?(it) }
+        end
+
+        def comments_in_replacement
+          source_comments.within(replacement_range)
+        end
+
+        def replacement_range
+          guard.source_range.with(end_pos: happy_range.end_pos)
+        end
+
+        def happy_range
+          @happy_range ||= first_happy_block.range.with(end_pos: last_happy_block.range.end_pos)
+        end
+
+        def first_happy_block
+          @first_happy_block ||= statement_block_for(happy.first)
+        end
+
+        def statement_block_for(node)
+          RuboCop::Callbacksystems::Source::StatementWithComments.new(node, processed_source)
+        end
+
+        def last_happy_block
+          @last_happy_block ||= statement_block_for(happy.last)
+        end
+
+        def preserved_comment?(comment)
+          comment.equal?(guard_trailing_comment) || preserved_comment_ranges.any? { it.contains?(comment.source_range) }
+        end
+
+        def guard_trailing_comment
+          @guard_trailing_comment ||= source_comments.trailing_comment_on(guard.last_line)
+        end
+
+        def preserved_comment_ranges
+          [ happy_range, guard.condition.source_range, *guard_values.map(&:source_range) ]
+        end
+
+        def heredocs_preserved?
+          !carries_heredoc?(guard) && happy_heredocs.all? { it.source.start_with?("<<~") }
+        end
+
+        def happy_heredocs
+          happy.flat_map { it.each_node(:str, :dstr, :xstr).select { it.loc?(:heredoc_body) } }
+        end
+
+        def correct(corrector)
+          corrector.replace(replacement_range, wrapped_source)
+        end
+
+        def wrapped_source
+          "#{guard_header}\n#{indented_happy}\n#{else_branch}#{indent}end"
+        end
+
+        def guard_header
+          "if #{guard.condition.source}#{guard_comment_source}"
+        end
+
+        def guard_comment_source
+          guard_trailing_comment&.then { " #{it.text}" }.to_s
+        end
+
+        def indented_happy
+          [ "#{first_line_indent}#{happy_lines.first}", *happy_lines.drop(1).map { indented_line(it) } ].join
+        end
+
+        def first_line_indent
+          happy_range.column.zero? ? "  " : "#{indent}  "
+        end
+
+        def indent
+          indentation_of(guard)
+        end
+
+        def happy_lines
+          @happy_lines ||= happy_source.lines
+        end
+
+        def happy_source
+          happy_range.source
+        end
+
+        def indented_line(line)
+          line.strip.empty? ? line : "  #{line}"
+        end
+
+        def else_branch
+          guard_value_source ? "#{indent}else\n#{indent}  #{guard_value_source}\n" : ""
+        end
+
+        def guard_value_source
+          case guard_values
+          in [] then nil
+          in [ value ] then value.source
+          else "[ #{guard_values.map(&:source).join(", ")} ]"
+          end
+        end
+    end
+end