rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,137 @@
+# A long comment block is prose doing work the code should do. Inside a class
+# body, two lines are enough for the non-obvious why. A block sitting
+# immediately above a top-level class or module sometimes holds two of those
+# whys, so it gets four. A block inside a `test` block narrates the scenario,
+# so it has no limit there. Shortening prose is human judgment, so there is no
+# autocorrection.
+#
+# @example
+#   # bad - a three-line block inside a class body
+#   class Widget
+#     # The cache is warmed by the nightly job, and a miss here
+#     # means the job never ran, so we raise instead of recomputing
+#     # to surface the broken schedule.
+#     def price
+#     end
+#   end
+#
+#   # good - two lines say the non-obvious why
+#   class Widget
+#     # A cache miss means the nightly job never ran, so we raise
+#     # to surface the broken schedule instead of recomputing.
+#     def price
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::CommentBlockLength < RuboCop::Cop::Callbacksystems::Base
+  def on_new_investigation
+    @comment_context = CommentContext.new(processed_source.ast)
+    comment_blocks_in(processed_source).each { report measured_block_of(it) }
+  end
+
+  private
+    attr_reader :comment_context
+
+    def measured_block_of(comments)
+      MeasuredBlock.new(comments, comment_context, max: cop_config["Max"], header_max: cop_config["HeaderMax"])
+    end
+
+    class MeasuredBlock
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "This comment block spans %d lines where %d is the limit. Keep the non-obvious why and drop any " \
+        "narration of the what."
+
+      def initialize(comments, context, max:, header_max:)
+        @comments = comments
+        @context = context
+        @max = max
+        @header_max = header_max
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(range, message) if comments.size > limit && !inside_test?(range)
+      end
+
+      private
+        attr_reader :comments, :context, :max, :header_max
+        delegate :inside_test?, to: :context, private: true
+
+        def limit
+          top_level_header? ? header_max : max
+        end
+
+        def top_level_header?
+          context.top_level_header_on?(comments.last.source_range.line)
+        end
+
+        def range
+          range_spanning(comments)
+        end
+
+        def message
+          format(MESSAGE, comments.size, limit)
+        end
+    end
+
+    # File-wide comment contexts indexed once for all blocks in the investigation.
+    class CommentContext
+      extend RuboCop::AST::NodePattern::Macros
+      include RuboCop::Callbacksystems::Testing::CopHelpers
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(ast)
+        @ast = ast
+      end
+
+      def top_level_header_on?(line)
+        top_level_header_lines.include?(line)
+      end
+
+      def inside_test?(range)
+        test_ranges.include?(range)
+      end
+
+      private
+        attr_reader :ast
+
+        def top_level_header_lines
+          @top_level_header_lines ||= nodes_in(ast, :class, :module).filter_map do |node|
+            node.first_line.pred if enclosing_class_or_module_of(node).nil?
+          end.to_set
+        end
+
+        def test_ranges
+          @test_ranges ||= ContainingRanges.new(test_blocks(ast).map(&:source_range))
+        end
+
+        # Source ranges supporting containment queries in logarithmic time, including nested ranges.
+        class ContainingRanges
+          def initialize(ranges)
+            @ranges = ranges.sort_by(&:begin_pos)
+          end
+
+          def include?(range)
+            candidate = first_range_after(range.begin_pos).pred
+            candidate >= 0 && maximum_end_positions[candidate] >= range.end_pos
+          end
+
+          private
+            attr_reader :ranges
+
+            def first_range_after(position)
+              begin_positions.bsearch_index { it > position } || ranges.size
+            end
+
+            def begin_positions
+              @begin_positions ||= ranges.map(&:begin_pos)
+            end
+
+            def maximum_end_positions
+              @maximum_end_positions ||= ranges.each_with_object([]) do |range, positions|
+                positions << [ positions.last || 0, range.end_pos ].max
+              end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,75 @@
+# Detects complex conditionals with too many boolean operators. A condition
+# chaining several operators has to be read term by term to know what it asks,
+# while a predicate method names the question and holds the terms where they
+# read on their own.
+#
+# @example MaxOperators: 1 (default)
+#   # bad - too many operators
+#   if a && b && c
+#     # ...
+#   end
+#
+#   # good - extract to predicate method
+#   if complex_condition?
+#     # ...
+#   end
+#
+#   def complex_condition?
+#     a && b && c
+#   end
+#
+#   # good - single operator
+#   if a && b
+#     # ...
+#   end
+#
+class RuboCop::Cop::Callbacksystems::ComplexConditional < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Conditional has %<count>d boolean operators (max %<max>d). Extract to a predicate method."
+
+  def on_if(node)
+    check_condition(node.condition)
+  end
+
+  alias on_while on_if
+  alias on_until on_if
+  alias on_while_post on_if
+  alias on_until_post on_if
+
+  private
+    def check_condition(condition)
+      count = OperatorCount.new(condition).value
+      add_offense(condition, message: format(MESSAGE, count: count, max: max_operators)) if count > max_operators
+    end
+
+    def max_operators
+      cop_config["MaxOperators"]
+    end
+
+    # The top-level boolean spine, walked iteratively so arbitrarily deep parser output cannot exhaust the call stack.
+    class OperatorCount
+      def initialize(node)
+        @pending = [ node ]
+        @count = 0
+      end
+
+      def value
+        visit(pending.pop) until pending.empty?
+        count
+      end
+
+      private
+        attr_reader :pending, :count
+
+        def visit(node)
+          case node&.type
+          when :and, :or then count_operator(node)
+          when :begin, :kwbegin then pending << node.children.last
+          end
+        end
+
+        def count_operator(node)
+          @count += 1
+          pending.concat(node.children)
+        end
+    end
+end

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

@@ -0,0 +1,105 @@
+# In controller tests, every test that makes an HTTP request must assert the response.
+# Testing only side effects without verifying the response status or redirect
+# leaves the controller's behavior unverified.
+#
+# @example
+#   # bad - no response assertion
+#   test "create creates a user" do
+#     post users_url, params: { name: "John" }
+#     assert_equal 1, User.count
+#   end
+#
+#   # good - asserts response status
+#   test "create creates a user" do
+#     post users_url, params: { name: "John" }
+#     assert_response :created
+#     assert_equal 1, User.count
+#   end
+#
+#   # good - asserts redirect
+#   test "create redirects" do
+#     post users_url, params: { name: "John" }
+#     assert_redirected_to users_path
+#   end
+#
+#   # good - no HTTP request (not a controller action test)
+#   test "helper works" do
+#     assert_equal "expected", helper_method
+#   end
+#
+class RuboCop::Cop::Callbacksystems::ControllerTestResponseAssertion < RuboCop::Cop::Callbacksystems::Base
+  include RuboCop::Callbacksystems::Testing::CopHelpers
+
+  def on_block(node)
+    report_each RequestResponses.new(node)
+  end
+
+  alias on_numblock on_block
+  alias on_itblock on_block
+
+  private
+    REQUEST_ABORTING_ASSERTIONS = %i[ assert_raises ]
+
+    class RequestResponses
+      extend RuboCop::AST::NodePattern::Macros
+      include RuboCop::Callbacksystems::Testing::CopHelpers
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Controller test makes an HTTP request but has no response assertion (assert_response or " \
+        "assert_redirected_to)."
+
+      def initialize(node)
+        @node = node
+      end
+
+      def each_offense
+        missing_requests.each { yield RuboCop::Callbacksystems::Offense.new(it, MESSAGE) }
+      end
+
+      private
+        attr_reader :node
+
+        def missing_requests
+          if test_block?(node)
+            request_runs.filter_map do |run|
+              request = run.first
+              request if request_statement?(request) && !request_answered_in?(run)
+            end
+          else
+            []
+          end
+        end
+
+        def request_runs
+          statements.slice_before { request_statement?(it) }
+        end
+
+        def statements
+          @statements ||= statements_in(node.body)
+        end
+
+        def request_statement?(statement)
+          immediate_calls_in(statement).any? { http_request?(it) }
+        end
+
+        def request_answered_in?(run)
+          run.any? { response_assertion_in?(it) } || request_aborted_in?(run.first)
+        end
+
+        def response_assertion_in?(statement)
+          immediate_calls_in(statement).any? { response_assertion?(it) }
+        end
+
+        def request_aborted_in?(statement)
+          immediate_calls_in(statement).select { http_request?(it) }.all? do |request|
+            request.each_ancestor(:any_block)
+              .take_while { it.equal?(statement) || statement.source_range.contains?(it.source_range) }
+              .any? { request_aborting_assertion?(it.send_node) }
+          end
+        end
+
+        def request_aborting_assertion?(send_node)
+          call_on_self?(send_node) && REQUEST_ABORTING_ASSERTIONS.include?(send_node.method_name)
+        end
+    end
+end

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

@@ -0,0 +1,123 @@
+# In controller tests, the first assertion after an HTTP request must be a
+# response assertion (assert_response or assert_redirected_to). The response is
+# what the request produced, so it is read first: when the controller fails, a
+# side-effect assertion placed before it fails on a symptom (a missing record)
+# and hides the status that explains it. Non-assertion code between the request
+# and the response assertion is allowed, and so are ActiveJob and ActionMailer
+# assertions (assert_enqueued_jobs, assert_enqueued_emails, etc.).
+#
+# @example
+#   # bad - first assertion is not about the response
+#   test "create" do
+#     post users_url, params: { name: "John" }
+#     assert_equal 1, User.count
+#     assert_response :created
+#   end
+#
+#   # good - response assertion comes first
+#   test "create" do
+#     post users_url, params: { name: "John" }
+#     assert_response :created
+#     assert_equal 1, User.count
+#   end
+#
+#   # good - non-assertion code before response assertion is fine
+#   test "create" do
+#     post users_url, params: { name: "John" }
+#     user = User.last
+#     assert_response :created
+#     assert_equal "John", user.name
+#   end
+#
+#   # good - assert_difference wrapping request, then response assertion
+#   test "create" do
+#     assert_difference("User.count", 1) do
+#       post users_url, params: { name: "John" }
+#     end
+#     assert_response :created
+#   end
+#
+#   # good - ActiveJob/ActionMailer assertions before response assertion
+#   test "create sends email" do
+#     post users_url, params: { name: "John" }
+#     assert_enqueued_emails 1
+#     assert_response :created
+#   end
+#
+class RuboCop::Cop::Callbacksystems::ControllerTestResponseFirstAssertion < RuboCop::Cop::Callbacksystems::Base
+  include RuboCop::Callbacksystems::Testing::CopHelpers
+
+  def on_block(node)
+    report_each RequestAssertions.new(node) if test_block?(node)
+  end
+
+  alias on_numblock on_block
+  alias on_itblock on_block
+
+  private
+    SIDE_EFFECT_ASSERTIONS = %i[
+      assert_enqueued_jobs assert_no_enqueued_jobs assert_performed_jobs assert_no_performed_jobs
+      assert_enqueued_with assert_performed_with
+      assert_emails assert_no_emails assert_enqueued_emails assert_no_enqueued_emails assert_enqueued_email_with
+    ]
+
+    # The assertions a test reads first after each of its requests, kept when one is not about the response.
+    class RequestAssertions
+      extend RuboCop::AST::NodePattern::Macros
+      include RuboCop::Callbacksystems::Testing::CopHelpers
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "The first assertion after an HTTP request must be `assert_response` or `assert_redirected_to`, not " \
+        "`%<method>s`."
+
+      def initialize(node)
+        @node = node
+      end
+
+      def each_offense
+        misplaced_assertions.each { yield RuboCop::Callbacksystems::Offense.new(it, message_for(it)) }
+      end
+
+      private
+        attr_reader :node
+
+        def misplaced_assertions
+          waiting_for_assertion = false
+          statements.filter_map do |statement|
+            if http_request_statement?(statement)
+              waiting_for_assertion = true
+              nil
+            elsif waiting_for_assertion
+              first_assertion_in(statement)&.then do |assertion|
+                waiting_for_assertion = false
+                assertion unless response_assertion?(assertion)
+              end
+            end
+          end
+        end
+
+        def statements
+          @statements ||= statements_in(node.body)
+        end
+
+        def http_request_statement?(statement)
+          immediate_calls_in(statement).any? { http_request?(it) }
+        end
+
+        def first_assertion_in(statement)
+          immediate_calls_in(statement).find { assertion?(it) && !side_effect_assertion?(it) }
+        end
+
+        def assertion?(send_node)
+          call_on_self?(send_node) && send_node.method_name.to_s.start_with?("assert", "refute")
+        end
+
+        def side_effect_assertion?(send_node)
+          call_on_self?(send_node) && SIDE_EFFECT_ASSERTIONS.include?(send_node.method_name)
+        end
+
+        def message_for(assertion)
+          format(MESSAGE, method: assertion.method_name)
+        end
+    end
+end