rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,47 @@
+# Asks for singular scope names, except under the `with_` prefix. A scope reads
+# as an adjective on the relation, `Person.customer` the way `Person.active`
+# does, while a plural name restates the collection the relation already is. A
+# `with_` scope names what the records carry, and that is plural as often as
+# not.
+#
+# @example
+#   # bad - plural scope name
+#   scope :customers, -> { where(customer: true) }
+#   scope :admins, -> { where(role: :admin) }
+#
+#   # good - singular scope name
+#   scope :customer, -> { where(customer: true) }
+#   scope :admin, -> { where(role: :admin) }
+#
+#   # good - with_* prefix can be plural (for associations)
+#   scope :with_posts, -> { includes(:posts) }
+#   scope :with_comments, -> { preload(:comments) }
+#
+class RuboCop::Cop::Callbacksystems::SingularScopeNames < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Scope names should be singular. Use `%<singular>s` instead of `%<name>s`."
+
+  def on_send(node)
+    add_offense(node.first_argument, message: message_for(node.first_argument.value)) if plural_scope?(node)
+  end
+
+  alias on_csend on_send
+
+  private
+    ASSOCIATION_PREFIX = "with_"
+
+    def plural_scope?(node)
+      scope_definition?(node) && plural?(node.first_argument.value)
+    end
+
+    def plural?(name)
+      !name.start_with?(ASSOCIATION_PREFIX) && singular_of(name) != name.to_s
+    end
+
+    def singular_of(name)
+      name.to_s.singularize
+    end
+
+    def message_for(name)
+      format(MESSAGE, singular: singular_of(name), name:)
+    end
+end

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

@@ -0,0 +1,73 @@
+# Requires a space inside the delimiters of a percent literal, the way an array
+# literal carries one. `Layout/SpaceInsideArrayLiteralBrackets` asks for `[ a, b ]`
+# and `Layout/SpaceInsideHashLiteralBraces` for `{ a: 1 }`, while the core cop for
+# these literals can only forbid the space, so this one asks for it and that one
+# stays off.
+#
+# A literal spanning several lines is left alone, since the line breaks already
+# separate its elements, and so is an empty one, which has nothing to separate.
+#
+# @example
+#   # bad
+#   %i[save update]
+#   %w[a b]
+#
+#   # good
+#   %i[ save update ]
+#   %w[ a b ]
+#
+#   # good - the line breaks separate these
+#   %i[
+#     save update
+#     destroy
+#   ]
+#
+#   # good - nothing to separate
+#   %i[]
+#
+class RuboCop::Cop::Callbacksystems::SpaceInsidePercentLiteral < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_array(node)
+    report PercentLiteral.new(node) if node.percent_literal?
+  end
+
+  private
+    class PercentLiteral
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Add a space inside the delimiters, the way an array literal carries one."
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, MESSAGE) { correct(it) } if unspaced?
+      end
+
+      private
+        attr_reader :node
+
+        def unspaced?
+          eligible? && [ opening_gap, closing_gap ].any? { it.source != " " }
+        end
+
+        def eligible?
+          node.children.any? && same_line?(node.loc.begin, node.loc.end)
+        end
+
+        def opening_gap
+          node.loc.begin.end.join(node.children.first.source_range.begin)
+        end
+
+        def closing_gap
+          node.children.last.source_range.end.join(node.loc.end.begin)
+        end
+
+        def correct(corrector)
+          corrector.replace(opening_gap, " ")
+          corrector.replace(closing_gap, " ")
+        end
+    end
+end

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

@@ -0,0 +1,30 @@
+# Keeps system tests on a real browser driver.
+# `rack_test` skips JavaScript entirely, so a Hotwire application under it
+# exercises pages that never behave like production. Integration tests
+# already cover the fast no-browser path.
+#
+# @example
+#   # bad - system tests without a browser
+#   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+#     driven_by :rack_test
+#   end
+#
+#   # good - headless browser
+#   class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+#     driven_by :selenium, using: :headless_chrome
+#   end
+#
+class RuboCop::Cop::Callbacksystems::SystemTestBrowserDriver < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "System tests must drive a real browser. Replace `:rack_test` with `:selenium, using: :headless_chrome`."
+
+  # @!method rack_test_driver?(node)
+  def_node_matcher :rack_test_driver?, <<~PATTERN
+    (call {nil? (self)} :driven_by (sym :rack_test) ...)
+  PATTERN
+
+  def on_send(node)
+    add_offense(node, message: MESSAGE) if rack_test_driver?(node)
+  end
+
+  alias on_csend on_send
+end

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

@@ -0,0 +1,86 @@
+# Asks for `test "description" do` over `def test_*`, and for `setup` and
+# `teardown` blocks over methods of those names. A description in plain words
+# says more than an underscored method name, and a `setup` block runs beside
+# the ones a parent class declares, where a `setup` method replaces them unless
+# it remembers to call `super`.
+#
+# @example
+#   # bad
+#   def test_something
+#     assert true
+#   end
+#
+#   # good
+#   test "something" do
+#     assert true
+#   end
+#
+#   # bad
+#   def setup
+#     @user = users(:bruno)
+#   end
+#
+#   # good
+#   setup do
+#     @user = users(:bruno)
+#   end
+#
+#   # bad
+#   def teardown
+#     cleanup
+#   end
+#
+#   # good
+#   teardown do
+#     cleanup
+#   end
+#
+class RuboCop::Cop::Callbacksystems::TestMethodDefinition < RuboCop::Cop::Callbacksystems::Base
+  TEST_MESSAGE = "Use `test \"description\" do` instead of `def %<method>s`."
+  BLOCK_MESSAGE = "Use `%<method>s do` block instead of `def %<method>s`."
+
+  def on_def(node)
+    report MethodDefinition.new(node)
+  end
+
+  private
+    class MethodDefinition
+      include RuboCop::Callbacksystems::Helpers
+
+      TEST_PREFIX = "test_"
+      HOOK_METHODS = %i[ setup teardown ]
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if inside_test_class? && message
+      end
+
+      private
+        attr_reader :node
+
+        def inside_test_class?
+          class_node = enclosing_class_or_module_of(node)
+          direct_method_definition?(node) && class_node.class_type? && (class_name_of(class_node).end_with?("Test") ||
+            rails_test_base_class?(class_node.parent_class))
+        end
+
+        def message
+          if test_method?
+            format(TEST_MESSAGE, method: node.method_name)
+          elsif hook_method?
+            format(BLOCK_MESSAGE, method: node.method_name)
+          end
+        end
+
+        def test_method?
+          node.method_name.start_with?(TEST_PREFIX)
+        end
+
+        def hook_method?
+          HOOK_METHODS.include?(node.method_name)
+        end
+    end
+end

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

@@ -0,0 +1,319 @@
+# Ensures tests follow the order of the methods they cover in the source file.
+# A test file read beside its source then walks the class top to bottom, and a
+# reader looking for the tests of a method finds them where the method sits
+# instead of scanning the whole file for its name.
+#
+# A test names its method with the first word of its description, so only the
+# tests opening with a method of the source are read, and the cop runs on test
+# files whose source file exists.
+#
+# @example
+#   # Source file (app/models/user.rb):
+#   # def name; end
+#   # def email; end
+#   # def admin?; end
+#
+#   # bad - tests not in method order
+#   test "email returns formatted email" do
+#   end
+#
+#   test "name returns full name" do
+#   end
+#
+#   # good - tests follow method order
+#   test "name returns full name" do
+#   end
+#
+#   test "email returns formatted email" do
+#   end
+#
+#   test "admin? returns true for admins" do
+#   end
+#
+class RuboCop::Cop::Callbacksystems::TestMethodOrder < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+  include RuboCop::Callbacksystems::Testing::CopHelpers
+
+  def external_dependency_checksum
+    RuboCop::Callbacksystems::Source::FilesChecksum.for([ "app/**/*.rb", "lib/**/*.rb" ], root: project_root)
+  end
+
+  def on_new_investigation
+    @method_positions = nil
+    @path_mapping = nil
+
+    report_each TestOrder.new(processed_source, blocks: test_blocks, positions: method_positions)
+  end
+
+  private
+    def method_positions
+      @method_positions ||= checkable? ? source_methods.each_with_index.to_a.uniq(&:first).to_h : {}
+    end
+
+    def checkable?
+      test_file?(processed_source.file_path) && path_mapping.source_path && File.exist?(path_mapping.source_path)
+    end
+
+    def path_mapping
+      @path_mapping ||= RuboCop::Callbacksystems::Testing::PathMapping.new(processed_source.file_path)
+    end
+
+    def source_methods
+      source_methods_for(path_mapping.source_path)
+    end
+
+    def source_methods_for(source_path)
+      source = RuboCop::Callbacksystems::Source::FileAst.processed_source \
+        source_path, ruby_version: processed_source.ruby_version
+
+      source&.valid_syntax? ? RuboCop::Callbacksystems::Methods::Definitions.new(source.ast).map(&:name) : []
+    end
+
+    class TestOrder
+      Test = Data.define(:node, :name, :position)
+
+      def initialize(processed_source, blocks:, positions:)
+        @processed_source = processed_source
+        @blocks = blocks
+        @positions = positions
+      end
+
+      # Only the first offense carries the correction, since rewriting puts every test in order at once.
+      def each_offense
+        correction_available = reordering.applicable?
+        offenses.each do |offense|
+          yield correction_available ? correcting(offense) : offense
+          correction_available = false
+        end
+      end
+
+      private
+        attr_reader :processed_source, :blocks, :positions
+
+        delegate :rewrite, to: :reordering, private: true
+
+        def reordering
+          @reordering ||= Reordering.new(processed_source, blocks:, tests:)
+        end
+
+        def tests
+          @tests ||= blocks.filter_map { test_for(it) }
+        end
+
+        def test_for(block)
+          Description.new(block, positions).method_name&.then { Test.new(block, it, positions.fetch(it)) }
+        end
+
+        def offenses
+          placements.filter_map(&:offense)
+        end
+
+        def placements
+          Placements.new(tests)
+        end
+
+        def correcting(offense)
+          RuboCop::Callbacksystems::Offense.new(offense.range, offense.message) { rewrite(it) }
+        end
+    end
+
+    # Any executable statement between two tests is a hard boundary, so a correction cannot move a test across setup.
+    class Reordering
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(processed_source, blocks:, tests:)
+        @processed_source = processed_source
+        @blocks = blocks
+        @tests = tests
+      end
+
+      def rewrite(corrector)
+        runs.select(&:reorderable?).each { it.rewrite(corrector) }
+      end
+
+      def applicable?
+        runs.any?(&:reorderable?)
+      end
+
+      private
+        attr_reader :processed_source, :blocks, :tests
+
+        def runs
+          @runs ||= blocks.sort_by { it.source_range.begin_pos }
+            .slice_when { |left, right| interrupted_between?(left, right) }
+            .map { Run.new(it, tests, processed_source) }
+        end
+
+        def interrupted_between?(left, right)
+          left_end = statement_of(left).range.end_pos
+          right_start = statement_of(right).begin_position
+          right_start < left_end || content_in?(range_between(left_end, right_start).source)
+        end
+
+        def statement_of(node)
+          RuboCop::Callbacksystems::Source::StatementWithComments.new(node, processed_source)
+        end
+
+        def content_in?(source)
+          source.lines.any? { it.strip.present? }
+        end
+    end
+
+    # One uninterrupted run of test blocks, where a test the source does not know keeps its slot.
+    class Run
+      def initialize(blocks, tests, processed_source)
+        @blocks = blocks
+        @tests = tests
+        @processed_source = processed_source
+      end
+
+      def rewrite(corrector)
+        moved_indexes.each { corrector.replace(statement_of(recognized[it]).range, statement_of(ordered[it]).source) }
+      end
+
+      def reorderable?
+        recognized != ordered && tooling_scope_kept?
+      end
+
+      private
+        attr_reader :blocks, :tests, :processed_source
+
+        def moved_indexes
+          recognized.each_index.reject { recognized[it].equal?(ordered[it]) }
+        end
+
+        def recognized
+          @recognized ||= blocks.filter_map { tests_by_node[it] }
+        end
+
+        def tests_by_node
+          @tests_by_node ||= {}.compare_by_identity.tap do |index|
+            tests.each { index[it.node] = it }
+          end
+        end
+
+        def ordered
+          @ordered ||= recognized.sort_by.with_index { |test, index| [ test.position, index ] }
+        end
+
+        def statement_of(test)
+          statement_for(test.node)
+        end
+
+        def statement_for(node)
+          RuboCop::Callbacksystems::Source::StatementWithComments.new(node, processed_source)
+        end
+
+        def tooling_scope_kept?
+          blocks.none? { statement_for(it).contains_tooling_comment? }
+        end
+    end
+
+    class Description
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(block, positions)
+        @block = block
+        @positions = positions
+      end
+
+      def method_name
+        candidates.find { positions.key?(it) }
+      end
+
+      private
+        attr_reader :block, :positions
+
+        # A scope is named bare where a method might carry a `?` or `!`, so the word after the name tells the two apart.
+        def candidates
+          if first_word.nil? then []
+          elsif scope? then [ first_word.to_sym ]
+          else [ first_word.to_sym, :"#{first_word}?", :"#{first_word}!" ]
+          end
+        end
+
+        def first_word
+          words.first
+        end
+
+        def words
+          @words ||= block.send_node.first_argument.value.split(/\s+/)
+        end
+
+        def scope?
+          words.second == "scope"
+        end
+    end
+
+    # Placements read the prefix once, carrying exactly the facts the next test needs.
+    class Placements
+      include Enumerable
+
+      delegate :each, to: :placements
+
+      def initialize(tests)
+        @tests = tests
+        @seen_names = Set.new
+      end
+
+      private
+        attr_reader :tests, :seen_names, :previous, :anchor
+
+        def placements
+          @placements ||= tests.map { |test| placement_for(test).tap { remember(test) } }
+        end
+
+        def placement_for(test)
+          Placement.new(test, repeated: seen_names.include?(test.name), grouped: previous&.name == test.name, anchor:)
+        end
+
+        def remember(test)
+          seen_names << test.name
+          @previous = test
+          @anchor = test if anchor.nil? || test.position > anchor.position
+        end
+    end
+
+    class Placement
+      GROUPING_MESSAGE = "Tests for `%<method>s` should be grouped together."
+      ORDER_MESSAGE = "Test for `%<method>s` appears after `%<previous>s`, but `%<method>s` is defined first in source."
+
+      def initialize(test, repeated:, grouped:, anchor:)
+        @test = test
+        @repeated = repeated
+        @grouped = grouped
+        @anchor = anchor
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(test.node, message) if separated? || out_of_order?
+      end
+
+      private
+        attr_reader :test, :anchor, :repeated, :grouped
+
+        def separated?
+          repeated? && !grouped?
+        end
+
+        def repeated?
+          repeated
+        end
+
+        def grouped?
+          grouped
+        end
+
+        def out_of_order?
+          !repeated? && anchor && test.position < anchor.position
+        end
+
+        def message
+          separated? ? format(GROUPING_MESSAGE, method: test.name) : order_message
+        end
+
+        def order_message
+          format(ORDER_MESSAGE, method: test.name, previous: anchor.name)
+        end
+    end
+end

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

@@ -0,0 +1,78 @@
+# Flags private methods with too many instance variable assignments.
+# Too many instance variable assignments often indicates a method is doing too much.
+# The `initialize` method and public methods are excluded.
+# Public methods (like controller actions) often need multiple instance variables.
+#
+# @example MaxAssignments: 2 (default)
+#   # bad - too many instance variable assignments in private method
+#   private
+#     def setup_request
+#       @user = find_user
+#       @account = find_account
+#       @permissions = load_permissions
+#     end
+#
+#   # good - single responsibility
+#   private
+#     def set_user
+#       @user = find_user
+#     end
+#
+#   # good - public methods can have many (e.g., controller actions)
+#   def show
+#     @user = find_user
+#     @account = find_account
+#     @permissions = load_permissions
+#   end
+#
+#   # good - initialize can have many
+#   def initialize(user, account)
+#     @user = user
+#     @account = account
+#     @created_at = Time.current
+#   end
+#
+class RuboCop::Cop::Callbacksystems::TooManyInstanceVariables < RuboCop::Cop::Callbacksystems::Base
+  def on_def(node)
+    report InstanceVariableAssignments.new(node, max: cop_config["MaxAssignments"])
+  end
+
+  alias on_defs on_def
+
+  private
+    class InstanceVariableAssignments
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Method has %<count>d instance variable assignments (max %<max>d). " \
+        "Consider splitting into separate methods."
+
+      def initialize(node, max:)
+        @node = node
+        @max = max
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if private_non_initializer? && count > max
+      end
+
+      private
+        attr_reader :node, :max
+
+        def private_non_initializer?
+          direct_method_definition?(node) && !node.method?(:initialize) && !public_method?(node)
+        end
+
+        def count
+          @count ||= instance_assignments.to_set(&:name).size
+        end
+
+        def instance_assignments
+          RuboCop::Callbacksystems::Execution::Immediate.new(node.body).nodes_of_type(:ivasgn)
+            .select { self_preserved_between?(it, boundary: node) }
+        end
+
+        def message
+          format(MESSAGE, count:, max:)
+        end
+    end
+end

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

@@ -0,0 +1,77 @@
+# Flags methods with too many local variable assignments.
+# Too many local variables often indicates imperative code that could
+# be made more declarative by extracting methods.
+#
+# @example MaxAssignments: 3 (default)
+#   # bad - imperative with local variables
+#   def process
+#     user = find_user
+#     account = user.account
+#     plan = account.plan
+#     features = plan.features
+#     # ...
+#   end
+#
+#   # good - declarative with methods
+#   def process
+#     apply_features
+#   end
+#
+#   def features
+#     plan.features
+#   end
+#
+#   def plan
+#     account.plan
+#   end
+#
+#   def account
+#     user.account
+#   end
+#
+#   def user
+#     User.find(user_id)
+#   end
+#
+#   # good - attribute assignments don't count
+#   def configure
+#     config.timeout = 30
+#     config.retries = 3
+#     config.verbose = true
+#   end
+#
+class RuboCop::Cop::Callbacksystems::TooManyLocalVariables < RuboCop::Cop::Callbacksystems::Base
+  def on_def(node)
+    report LocalVariableAssignments.new(node, max: cop_config["MaxAssignments"])
+  end
+
+  alias on_defs on_def
+
+  private
+    class LocalVariableAssignments
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Method has %<count>d local variable assignments (max %<max>d). " \
+        "Extract methods instead of using local variables."
+
+      def initialize(node, max:)
+        @node = node
+        @max = max
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if count > max
+      end
+
+      private
+        attr_reader :node, :max
+
+        def count
+          @count ||= assignment_count(node.body, :lvasgn, :match_var)
+        end
+
+        def message
+          format(MESSAGE, count:, max:)
+        end
+    end
+end