rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,269 @@
+# Detects public methods in visually private nested classes that are never
+# called from outside. When the project index confirms that no other file can
+# reach or subclass the class, a method none of its local callers names is an
+# implementation detail and belongs in the private section.
+#
+# @example
+#   # bad - unused_method is public but never called from outside
+#   class Foo
+#     def process
+#       Bar.new(node).used_method
+#       nil
+#     end
+#
+#     private
+#       class Bar
+#         def used_method; end
+#         def unused_method; end  # should be private
+#       end
+#   end
+#
+#   # good - internal methods are private
+#   class Foo
+#     def process
+#       Bar.new(node).used_method
+#       nil
+#     end
+#
+#     private
+#       class Bar
+#         def used_method; end
+#
+#         private
+#           def internal_method; end
+#       end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PrivateNestedClassMethodVisibility < RuboCop::Cop::Callbacksystems::Base
+  include RuboCop::Callbacksystems::ProjectIndex::Support
+
+  def on_new_investigation
+    @file_references = FileReferences.new(processed_source.ast) if project_index
+  end
+
+  def on_class(node)
+    if project_index_reliable?
+      private_nested_classes_in(node).select { confined_without_descendants?(it) }.each do |nested_class|
+        report_each UnusedPublicMethods.new(nested_class, references: file_references.for(nested_class))
+      end
+    end
+  end
+
+  alias on_module on_class
+
+  private
+    attr_reader :file_references
+
+    def confined_without_descendants?(nested_class)
+      confined_declaration_of(nested_class)&.then do |declaration|
+        declaration.descendants.none? { it.name != declaration.name }
+      end
+    end
+
+    # References in the whole file compared with those inside one nested class, indexed once for every reader.
+    class FileReferences
+      def initialize(root)
+        @root = root
+        @by_class = {}.compare_by_identity
+      end
+
+      def for(nested_class)
+        by_class[nested_class] ||= ClassReferences.new(all, References.new(nested_class))
+      end
+
+      private
+        attr_reader :root, :by_class
+
+        def all
+          @all ||= References.new(root)
+        end
+
+        class ClassReferences
+          delegate :public_visibility_uncertain?, to: :all
+
+          def initialize(all, inside)
+            @all = all
+            @inside = inside
+          end
+
+          def mentions_outside?(method_name)
+            all.call_count(method_name) > inside.call_count(method_name) ||
+              all.block_pass_count(method_name) > inside.block_pass_count(method_name) ||
+              all.delegation_count(method_name) > inside.delegation_count(method_name) ||
+              all.dynamic_delegation_count > inside.dynamic_delegation_count
+          end
+
+          def public_visibility_required?(method_name)
+            all.public_visibility_count(method_name).positive?
+          end
+
+          private
+            attr_reader :all, :inside
+        end
+    end
+
+    class References
+      include RuboCop::Callbacksystems::Helpers
+
+      PUBLIC_LOOKUPS = %i[ protected public public_method public_send respond_to? try try! ]
+      VISIBILITY_ENUMERATIONS = %i[
+        instance_methods methods private_instance_methods private_methods protected_instance_methods
+        protected_methods public_instance_methods public_methods singleton_methods
+      ]
+
+      def initialize(root)
+        @evidence = RuboCop::Callbacksystems::Methods::ReferenceEvidence.for(root)
+      end
+
+      def call_count(name)
+        call_counts.fetch(name, 0)
+      end
+
+      def public_visibility_count(name)
+        explicit_call_counts.fetch(name, 0) + block_pass_count(name) + delegation_count(name) +
+          public_lookup_counts.fetch(name, 0) + (evidence.literal_method_names.include?(name.to_s) ? 1 : 0)
+      end
+
+      def block_pass_count(name)
+        block_pass_counts.fetch(name, 0)
+      end
+
+      def delegation_count(name)
+        delegation_counts.fetch(name, 0)
+      end
+
+      def public_visibility_uncertain?
+        dynamic_public_lookup? || dynamic_block_pass? || dynamic_delegation_count.positive? ||
+          interpolated_name? || visibility_enumerated?
+      end
+
+      def dynamic_delegation_count
+        @dynamic_delegation_count ||= evidence.calls.count { dynamic_delegation?(it) }
+      end
+
+      private
+        attr_reader :evidence
+
+        def call_counts
+          @call_counts ||= evidence.calls.map(&:method_name).tally
+        end
+
+        def explicit_call_counts
+          @explicit_call_counts ||= evidence.calls.filter_map do |send_node|
+            send_node.method_name if send_node.receiver && !send_node.receiver.self_type?
+          end.tally
+        end
+
+        def block_pass_counts
+          @block_pass_counts ||= evidence.block_passes.filter_map { block_pass_name_of(it) }.tally
+        end
+
+        def block_pass_name_of(node)
+          node.children.first.value if node.children.first&.sym_type?
+        end
+
+        def delegation_counts
+          @delegation_counts ||= evidence.calls.flat_map { delegated_names_of(it) }.tally
+        end
+
+        def delegated_names_of(send_node)
+          if delegate_macro?(send_node)
+            RuboCop::Callbacksystems::Methods::DelegateMacro.new(send_node).target_method_names || []
+          else
+            []
+          end
+        end
+
+        def public_lookup_counts
+          @public_lookup_counts ||= public_lookups.filter_map { public_lookup_name_of(it) }.tally
+        end
+
+        def public_lookups
+          @public_lookups ||= evidence.calls.select { PUBLIC_LOOKUPS.include?(it.method_name) }
+        end
+
+        def public_lookup_name_of(send_node)
+          send_node.first_argument&.then do |argument|
+            if argument.type?(:sym, :str)
+              argument.value.to_sym if argument.value.to_s.valid_encoding?
+            elsif argument.any_def_type?
+              argument.method_name
+            end
+          end
+        end
+
+        def dynamic_public_lookup?
+          public_lookups.any? { public_lookup_name_of(it).nil? }
+        end
+
+        def dynamic_block_pass?
+          evidence.block_passes.any? do |block_pass|
+            block_pass.children.first && !block_pass.children.first.sym_type?
+          end
+        end
+
+        def dynamic_delegation?(send_node)
+          delegate_macro?(send_node) && RuboCop::Callbacksystems::Methods::DelegateMacro.new(send_node).target_method_names.nil?
+        end
+
+        def interpolated_name?
+          evidence.interpolated_literals.any?
+        end
+
+        def visibility_enumerated?
+          evidence.calls.any? { VISIBILITY_ENUMERATIONS.include?(it.method_name) }
+        end
+    end
+
+    class UnusedPublicMethods
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Method `%<method>s` in visually private nested class `%<class>s` is never called from outside. " \
+        "Make it private."
+
+      # Ruby calls these structurally (a double splat calls `to_hash`, `case` calls `===`), so no source names them.
+      PROTOCOL_METHODS = RuboCop::Callbacksystems::Methods::ImplicitInvocations::METHOD_NAMES
+
+      def initialize(nested_class, references:)
+        @nested_class = nested_class
+        @references = references
+      end
+
+      def each_offense
+        unused_public_methods.each { yield RuboCop::Callbacksystems::Offense.new(it, message_for(it)) }
+      end
+
+      private
+        attr_reader :nested_class, :references
+
+        def unused_public_methods
+          if references && !references.public_visibility_uncertain?
+            uncalled_public_methods
+          else
+            []
+          end
+        end
+
+        def uncalled_public_methods
+          public_methods_in(nested_class).reject { mentioned_outside?(it.method_name) }
+        end
+
+        # An instance travels beyond one file's reading, so any mention of the name outside the class counts as a use.
+        def mentioned_outside?(method_name)
+          PROTOCOL_METHODS.include?(method_name) || macro_referenced_methods.include?(method_name) ||
+            references.mentions_outside?(method_name) || references.public_visibility_required?(method_name)
+        end
+
+        def macro_referenced_methods
+          @macro_referenced_methods ||= RuboCop::Callbacksystems::Methods::MacroReferences.new(nested_class.body).to_a
+        end
+
+        def message_for(method_node)
+          format(MESSAGE, method: method_node.method_name, class: class_name)
+        end
+
+        def class_name
+          nested_class.identifier.short_name
+        end
+    end
+end

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

@@ -0,0 +1,94 @@
+# Requires nested classes to be declared in the private section. A nested class
+# is an implementation detail, so the class holding one says as much by where it
+# puts it. One that other files build has no business being nested at all: it
+# goes in its own file, where Zeitwerk expects it.
+#
+# A constant assigned from `Data.define`, `Struct.new` or `Class.new` defines a
+# class in everything but syntax, so it reads under the same rule.
+#
+# A definition with no body is left alone. An error class or a bare list of
+# members declares what something is rather than how it works, and a file of its
+# own would cost more than it says.
+#
+# @example
+#   # bad - public nested class
+#   class Order
+#     class LineItem
+#       def total
+#       end
+#     end
+#   end
+#
+#   # bad - a constant that builds a class with behavior
+#   class Order
+#     LineItem = Data.define(:sku, :quantity) do
+#       def total
+#       end
+#     end
+#
+#     private
+#       def process
+#       end
+#   end
+#
+#   # good - nested class in private section
+#   class Order
+#     def process
+#     end
+#
+#     private
+#       class LineItem
+#         def total
+#         end
+#       end
+#   end
+#
+#   # good - declarations with no body, wherever they read best
+#   class Order
+#     class Rejected < StandardError; end
+#
+#     LineItem = Data.define(:sku, :quantity)
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PrivateNestedClasses < RuboCop::Cop::Callbacksystems::Base
+  def on_class(node)
+    report NestedClass.new(node)
+  end
+
+  alias on_casgn on_class
+
+  private
+    class NestedClass
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Nested class `%<name>s` should be in the private section, or live in its own file if it is part of " \
+        "the API."
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if outside_private_section?
+      end
+
+      private
+        attr_reader :node
+
+        def outside_private_section?
+          class_with_body?(node) && nested? && !in_private_section?(node, enclosing.body)
+        end
+
+        def nested?
+          enclosing.present?
+        end
+
+        def enclosing
+          @enclosing ||= enclosing_class_or_module_of(node)
+        end
+
+        def message
+          format(MESSAGE, name: class_name_of(node))
+        end
+    end
+end

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

@@ -0,0 +1,190 @@
+# Ensures every public method of a class or module has a test, found by the
+# convention that a test description opens with the name of the method it
+# covers. A public method is the API of the class, so one without a test is a
+# promise nothing checks, and the naming convention is what lets a reader go
+# from the method to its tests and back.
+#
+# Methods of private nested classes are implementation details and stay out,
+# and so do methods a macro references (callbacks, delegates), since the macro
+# is what exercises them. A method returning a plain literal needs no test that
+# would only restate the literal. Scopes and methods in `class_methods` blocks
+# count.
+#
+# Test files are located based on the source file path:
+# - lib/foo/bar.rb -> test/lib/foo/bar_test.rb or test/foo/bar_test.rb
+# - app/models/user.rb -> test/models/user_test.rb
+#
+# @example
+#   # bad - public method without test
+#   class User
+#     def full_name
+#       "#{first_name} #{last_name}"
+#     end
+#   end
+#   # And test file has no test "full_name ..." block
+#
+#   # good - public method has test
+#   class User
+#     def full_name
+#       "#{first_name} #{last_name}"
+#     end
+#   end
+#   # test "full_name returns concatenated names" do ... end
+#
+#   # good - method returning a plain literal needs no test
+#   class User
+#     def role
+#       "member"
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PublicMethodsMustHaveTests < RuboCop::Cop::Callbacksystems::Base
+  def external_dependency_checksum
+    [
+      RuboCop::Callbacksystems::Source::FilesChecksum.for("test/**/*_test.rb", root: project_root),
+      RuboCop::Callbacksystems::Source::FilesChecksum.for("*.gemspec", root: project_root, include_contents: false)
+    ].join
+  end
+
+  def on_new_investigation
+    @path_mapping = RuboCop::Callbacksystems::Testing::PathMapping.new(processed_source.file_path)
+    @tested_methods = path_mapping.test_path ? TestedMethods.new(path_mapping.test_path, ruby_version:) : Set.new
+  end
+
+  def on_class(node)
+    unless private_nested_class?(node)
+      report_each TestCoverage.new(node, processed_source, path_mapping:, tested_methods:)
+    end
+  end
+
+  alias on_module on_class
+
+  private
+    attr_reader :path_mapping, :tested_methods
+    delegate :ruby_version, to: :processed_source, private: true
+
+    class TestCoverage
+      MESSAGE = "Public method `%<method>s` has no test. " \
+        "Convention: tests begin with the method name followed by what it does, " \
+        "e.g. `test \"%<method>s returns the expected value\" do`"
+      EXCLUDED_METHODS = %i[ initialize ].to_set
+
+      def initialize(node, processed_source, path_mapping:, tested_methods:)
+        @node = node
+        @processed_source = processed_source
+        @path_mapping = path_mapping
+        @tested_methods = tested_methods
+      end
+
+      def each_offense
+        untested_methods.each { yield RuboCop::Callbacksystems::Offense.new(it.node, message_for(it)) }
+      end
+
+      private
+        attr_reader :node, :processed_source, :path_mapping, :tested_methods
+
+        delegate :file_path, to: :processed_source, private: true
+
+        def untested_methods
+          checked? ? testable_public_methods.reject { covered?(it) } : []
+        end
+
+        def checked?
+          file_path.exclude?("/test/") && !lib_file_in_non_gem_project? && test_source_valid?
+        end
+
+        def lib_file_in_non_gem_project?
+          file_path.match?(%r{(^|/)lib/}) && !path_mapping.gem_project?
+        end
+
+        def test_source_valid?
+          path_mapping.test_path.nil? || tested_methods.valid?
+        end
+
+        def testable_public_methods
+          RuboCop::Callbacksystems::Methods::Definitions.new(node).reject { exempt?(it) }
+        end
+
+        def exempt?(definition)
+          EXCLUDED_METHODS.include?(definition.name) || returns_literal?(definition.node)
+        end
+
+        def returns_literal?(method_node)
+          method_node.type?(:any_def) && method_node.body&.recursive_literal?
+        end
+
+        def covered?(definition)
+          MethodCoverage.new(definition, tested: tested_methods, macro_referenced: macro_referenced_methods).covered?
+        end
+
+        def macro_referenced_methods
+          @macro_referenced_methods ||= RuboCop::Callbacksystems::Methods::MacroReferences.new(node.body).to_set
+        end
+
+        def message_for(definition)
+          format(MESSAGE, method: definition.name)
+        end
+
+        # A scope a macro names is still API a test reads, so the macro exempts every method but a scope.
+        class MethodCoverage
+          def initialize(definition, tested:, macro_referenced:)
+            @definition = definition
+            @tested = tested
+            @macro_referenced = macro_referenced
+          end
+
+          def covered?
+            tested? || macro_referenced_non_scope?
+          end
+
+          private
+            attr_reader :definition, :tested, :macro_referenced
+
+            def tested?
+              tested.include?(definition.name.to_s)
+            end
+
+            def macro_referenced_non_scope?
+              macro_referenced.include?(definition.name) && !scope?
+            end
+
+            def scope?
+              definition.node.send_type? && definition.node.method?(:scope)
+            end
+        end
+    end
+
+    class TestedMethods
+      extend RuboCop::AST::NodePattern::Macros
+      include Enumerable
+      include RuboCop::Callbacksystems::Testing::CopHelpers
+      include RuboCop::Callbacksystems::Helpers
+
+      delegate :each, to: :names
+
+      def initialize(test_file_path, ruby_version:)
+        @test_file_path = test_file_path
+        @ruby_version = ruby_version
+      end
+
+      def valid?
+        processed_test_source&.valid_syntax? || false
+      end
+
+      private
+        attr_reader :test_file_path, :ruby_version
+
+        def names
+          @names ||= descriptions.filter_map { it.split(/\s+/).first }
+        end
+
+        def descriptions
+          nodes_in(processed_test_source&.ast, :any_block).filter_map { test_block?(it) }
+        end
+
+        def processed_test_source
+          @processed_test_source ||= RuboCop::Callbacksystems::Source::FileAst.processed_source \
+            test_file_path, ruby_version:
+        end
+    end
+end

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

@@ -0,0 +1,157 @@
+# Detects an `extend ActiveSupport::Concern` the module never uses. The extend
+# promises `included`, `class_methods` or `prepended` hooks, or concern
+# dependencies declared with `include` or `prepend`, so a reader goes looking
+# for them. A module with none is a plain mixin carrying a promise it never
+# keeps.
+#
+# @example
+#   # bad - extend without using concern features
+#   module Searchable
+#     extend ActiveSupport::Concern
+#
+#     def search
+#       # ...
+#     end
+#   end
+#
+#   # good - using included block
+#   module Searchable
+#     extend ActiveSupport::Concern
+#
+#     included do
+#       scope :search, -> { ... }
+#     end
+#   end
+#
+#   # good - using class_methods
+#   module Searchable
+#     extend ActiveSupport::Concern
+#
+#     class_methods do
+#       def search(query)
+#         # ...
+#       end
+#     end
+#   end
+#
+#   # good - no extend needed for simple module
+#   module Searchable
+#     def search
+#       # ...
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::RedundantConcernExtend < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_module(node)
+    report ConcernModule.new(node, source_comments:)
+  end
+
+  private
+    class ConcernModule
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Unnecessary `extend ActiveSupport::Concern`. " \
+        "Remove it or use concern hooks or dependencies."
+      CONCERN_CONSTANTS = %w[ ActiveSupport::Concern Concern ]
+      CONCERN_METHODS = %i[ included class_methods prepended ]
+      DEPENDENCY_METHODS = %i[ include prepend ]
+
+      def initialize(node, source_comments:)
+        @node = node
+        @source_comments = source_comments
+      end
+
+      def offense
+        if redundant?
+          RuboCop::Callbacksystems::Offense.new \
+            concern_extend, MESSAGE, correcting: correction_uncommented? do |corrector|
+              correct(corrector)
+            end
+        end
+      end
+
+      private
+        attr_reader :node, :source_comments
+
+        def redundant?
+          concern_extend && !uses_concern_features?
+        end
+
+        def concern_extend
+          @concern_extend ||= statements_in(node.body).find { concern_extend?(it) }
+        end
+
+        def concern_extend?(statement)
+          statement.send_type? && statement.method?(:extend) && statement.arguments.any? { concern_constant?(it) }
+        end
+
+        def concern_constant?(argument)
+          CONCERN_CONSTANTS.include?(constant_name_of(argument)&.delete_prefix("::"))
+        end
+
+        def uses_concern_features?
+          concern_hooks.any? || concern_dependencies.any? || class_methods_module?
+        end
+
+        def concern_hooks
+          nodes_in(node.body, :any_block).select do |block|
+            bare_send?(block.send_node) && CONCERN_METHODS.include?(block.method_name)
+          end
+        end
+
+        def concern_dependencies
+          nodes_in(node.body, :send).select do |call|
+            bare_send?(call) && DEPENDENCY_METHODS.include?(call.method_name) &&
+              call.each_ancestor(:def, :defs, :class, :module).first.equal?(node)
+          end
+        end
+
+        def class_methods_module?
+          statements_in(node.body).any? do |statement|
+            statement.module_type? && constant_name_of(statement.identifier) == "ClassMethods"
+          end
+        end
+
+        def correction_uncommented?
+          !source_comments.any_within?(correction_range)
+        end
+
+        def correction_range
+          concern_extend.arguments.one? ? statement_removal_range_for(concern_extend) : concern_argument_removal_range
+        end
+
+        def concern_argument_removal_range
+          if argument_after_concern
+            concern_argument.source_range.with(end_pos: argument_after_concern.source_range.begin_pos)
+          else
+            argument_before_concern.source_range.end.join(concern_argument.source_range.end)
+          end
+        end
+
+        def argument_after_concern
+          concern_extend.arguments[concern_argument_index + 1]
+        end
+
+        def concern_argument_index
+          concern_extend.arguments.index(concern_argument)
+        end
+
+        def concern_argument
+          @concern_argument ||= concern_extend.arguments.find { concern_constant?(it) }
+        end
+
+        def argument_before_concern
+          concern_extend.arguments[concern_argument_index - 1]
+        end
+
+        def correct(corrector)
+          if concern_extend.arguments.one?
+            corrector.remove(statement_removal_range_for(concern_extend))
+          else
+            corrector.remove(concern_argument_removal_range)
+          end
+        end
+    end
+end