rubocop-callbacksystems 0.1.0

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

@@ -0,0 +1,52 @@
+# Keeps Turbo Stream markup out of controllers. A call on the `turbo_stream`
+# tag builder renders elements, and markup belongs to the view, where the same
+# `turbo_stream.replace` reads as a template while the controller only decides
+# what to render and with which status.
+#
+# @example
+#   # bad - the controller builds the stream
+#   class MessagesController < ApplicationController
+#     def update
+#       if @message.update(message_params)
+#         redirect_to @message
+#       else
+#         render turbo_stream: turbo_stream.replace(@message, partial: "messages/form")
+#       end
+#     end
+#   end
+#
+#   # good - the controller renders and the view builds the stream
+#   class MessagesController < ApplicationController
+#     def update
+#       if @message.update(message_params)
+#         redirect_to @message
+#       else
+#         respond_to do |format|
+#           format.turbo_stream { render status: :unprocessable_content }
+#         end
+#       end
+#     end
+#   end
+#
+#   # app/views/messages/update.turbo_stream.erb
+#   <%= turbo_stream.replace @message, partial: "messages/form" %>
+#
+class RuboCop::Cop::Callbacksystems::NoTurboStreamInControllers < RuboCop::Cop::Callbacksystems::Base
+  MESSAGE = "Build the Turbo Stream in a `.turbo_stream.erb` view instead of calling `turbo_stream.%<method>s` in " \
+    "the controller."
+
+  def on_send(node)
+    add_offense(node, message: format(MESSAGE, method: node.method_name)) if turbo_stream_builder_call?(node)
+  end
+
+  alias on_csend on_send
+
+  private
+    def turbo_stream_builder_call?(node)
+      controller_file?(processed_source.file_path) && turbo_stream_builder?(node.receiver)
+    end
+
+    def turbo_stream_builder?(receiver)
+      call_on_self?(receiver) && receiver.method?(:turbo_stream)
+    end
+end

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

@@ -0,0 +1,159 @@
+# AI agents (and pasting from formatted text) sneak typographic characters into
+# source: smart quotes, dashes, ellipses, invisible spaces. What counts as
+# clutter depends on where the character sits.
+#
+# A comment only describes the code, so a typographic spelling of punctuation is
+# noise there: it breaks grep and reads as sloppy review. A string shows the text
+# it holds, so a character a reader can see is content someone wrote on purpose.
+# Only the invisible marks are clutter inside a string, since those change what
+# the string compares as without showing it, so an equality that reads as true
+# comes out false and a `split` misses where you meant it to cut.
+#
+# Arrows, bullets, check marks and guillemets are left alone in both places. They
+# carry meaning of their own and no ASCII spelling replaces them.
+#
+# The characters below are written as escapes, since this file is checked too.
+#
+# @example
+#   # bad - an em dash in a comment
+#   # name \u2014 required
+#   name = params[:name]
+#
+#   # bad - a double hyphen (two `-` in a row) standing in for a dash
+#   # name \u002D\u002D required
+#
+#   # bad - a no-break space in a string, which compares unlike a plain space
+#   label = "first\u00A0name"
+#
+#   # good - plain ASCII punctuation in the comment
+#   # name, required
+#   name = params[:name]
+#
+#   # good - a visible character left as written inside the string
+#   label = "said \u201Cyes\u201D"
+#
+class RuboCop::Cop::Callbacksystems::NoTypographicClutter < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_new_investigation
+    prose_comments_in(processed_source).each do |comment|
+      report_each Clutter.new(comment.source_range, comment.text, clutter: COMMENT_CLUTTER), rewrites_comments: true
+      report_each DoubleHyphens.new(comment), rewrites_comments: true
+    end
+    string_ranges.each { report_each Clutter.new(it, it.source, clutter: STRING_CLUTTER) }
+  end
+
+  private
+    # Marks a reader cannot see: no-break space, soft hyphen, narrow no-break space, word joiner, BOM.
+    INVISIBLE_POINTS = [ 0x00A0, 0x00AD, 0x202F, 0x2060, 0xFEFF ]
+    COMMENT_CLUTTER = Set[*INVISIBLE_POINTS, 0x2013, 0x2014, 0x2026, 0x2212, *0x200B..0x200D, *0x2018..0x201F]
+    # Zero-width marks stay out of strings, since they join an emoji sequence and deleting one splits the emoji.
+    STRING_CLUTTER = Set[*INVISIBLE_POINTS]
+
+    def string_ranges
+      nodes_in(processed_source.ast, :str).map { string_range_of(it) }
+    end
+
+    def string_range_of(node)
+      node.loc?(:heredoc_body) ? node.loc.heredoc_body : node.source_range
+    end
+
+    class Clutter
+      def initialize(range, text, clutter:)
+        @range = range
+        @text = text
+        @clutter = clutter
+      end
+
+      def each_offense
+        occurrences.each { yield it.offense }
+      end
+
+      private
+        attr_reader :range, :text, :clutter
+
+        def occurrences
+          text.each_char.with_index.filter_map do |character, offset|
+            Occurrence.new(range, character, offset) if clutter.include?(character.ord)
+          end
+        end
+
+        class Occurrence
+          MESSAGE = "Remove typographic character `%<character>s` (U+%<code_point>s). Use ASCII equivalents."
+          # Only characters with one meaning-preserving ASCII spelling, keyed by escape so this file passes its own cop.
+          ASCII_EQUIVALENT = {
+            "\u2018" => "'", "\u2019" => "'",
+            "\u201C" => "\"", "\u201D" => "\"",
+            "\u2026" => "...",
+            "\u00A0" => " ", "\u202F" => " ",
+            "\u200B" => "", "\u200C" => "", "\u200D" => "", "\u2060" => "", "\uFEFF" => "",
+            "\u00AD" => ""
+          }
+
+          def initialize(source_range, character, offset)
+            @source_range = source_range
+            @character = character
+            @offset = offset
+          end
+
+          def offense
+            RuboCop::Callbacksystems::Offense.new(range, message, correcting: !replacement.nil?) { correct(it) }
+          end
+
+          private
+            attr_reader :source_range, :character, :offset
+
+            def range
+              source_range.with(begin_pos: source_range.begin_pos + offset, end_pos: range_end)
+            end
+
+            def range_end
+              source_range.begin_pos + offset + character.length
+            end
+
+            def message
+              format(MESSAGE, character: character, code_point: code_point)
+            end
+
+            def code_point
+              format("%04X", character.ord)
+            end
+
+            def replacement
+              ASCII_EQUIVALENT[character]
+            end
+
+            def correct(corrector)
+              corrector.replace(range, replacement)
+            end
+        end
+    end
+
+    # Double hyphens standing in for dashes. Which punctuation replaces one depends on the sentence, so there is no fix.
+    class DoubleHyphens
+      MESSAGE = "Avoid `--` in comments; use a comma, colon, or parentheses."
+
+      def initialize(comment)
+        @comment = comment
+      end
+
+      def each_offense
+        offsets.each { yield RuboCop::Callbacksystems::Offense.new(range_at(it), MESSAGE) }
+      end
+
+      private
+        attr_reader :comment
+
+        def offsets
+          comment.text.enum_for(:scan, /--/).map { Regexp.last_match.begin(0) }
+        end
+
+        def range_at(offset)
+          comment.source_range.with(begin_pos: comment.source_range.begin_pos + offset, end_pos: range_end(offset))
+        end
+
+        def range_end(offset)
+          comment.source_range.begin_pos + offset + 2
+        end
+    end
+end

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

@@ -0,0 +1,149 @@
+# Keeps GET actions free of writes and enqueued side effects. HTTP promises a
+# GET changes nothing, and browsers, crawlers and link previews act on that
+# promise by prefetching, retrying and replaying it, so a write in `show` runs
+# as many times as the page is opened and by clients that never meant to act.
+# Only applies to index, show, new, and edit in controller classes, and only
+# to calls made directly in the action body, so a write pushed into a model
+# method stays a deliberate choice.
+#
+# @example
+#   # bad - GET action persists a change
+#   class MessagesController < ApplicationController
+#     def show
+#       @message = Message.find(params[:id])
+#       @message.update!(read_at: Time.current)
+#     end
+#   end
+#
+#   # bad - GET action enqueues a side effect
+#   class MessagesController < ApplicationController
+#     def show
+#       ReadReceiptJob.perform_later(params[:id])
+#     end
+#   end
+#
+#   # good - the write moves behind a non-GET action
+#   class Messages::ReadingsController < ApplicationController
+#     def create
+#       Message.find(params[:message_id]).update!(read_at: Time.current)
+#     end
+#   end
+#
+class RuboCop::Cop::Callbacksystems::NoWritesInGetActions < RuboCop::Cop::Callbacksystems::Base
+  def on_def(node)
+    report_each GetAction.new(node)
+  end
+
+  private
+    class GetAction
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "`%<action>s` serves GET requests, so it must not call `%<method>s`. Move the write behind a non-GET " \
+        "action."
+      GET_ACTIONS = %i[ index show new edit ]
+      WRITE_METHODS = %i[
+        create create! save save! update update! update_attribute update_column update_columns
+        destroy destroy! destroy_all delete delete_all update_all touch increment! decrement! toggle!
+        find_or_create_by find_or_create_by! create_or_find_by create_or_find_by!
+        first_or_create first_or_create! increment_counter decrement_counter update_counters
+        insert_all insert_all! upsert upsert_all deliver_now perform_now
+      ]
+      DEFERRED_SUFFIX = "_later"
+      REQUEST_STATE_RECEIVERS = %i[ session cookies flash params headers request response ]
+
+      def initialize(node)
+        @node = node
+      end
+
+      def each_offense
+        writes.each { yield RuboCop::Callbacksystems::Offense.new(it, message_for(it)) }
+      end
+
+      private
+        attr_reader :node
+
+        def writes
+          if get_action?
+            node.each_node(:call).select { write?(it) && !inside_deferred_callable?(it) }
+          else
+            []
+          end
+        end
+
+        def get_action?
+          GET_ACTIONS.include?(node.method_name) && direct_method_definition?(node) && instance_method? &&
+            enclosing_controller_class? && public_method?(node)
+        end
+
+        def instance_method?
+          RuboCop::Callbacksystems::Methods::Domain.new(node).scope == :instance
+        end
+
+        def enclosing_controller_class?
+          controller_class?(enclosing_class_or_module_of(node))
+        end
+
+        def write?(call)
+          write_name?(call.method_name) && !RequestStateReceiver.new(call.receiver).request_state?
+        end
+
+        def write_name?(name)
+          WRITE_METHODS.include?(name) || name.end_with?(DEFERRED_SUFFIX)
+        end
+
+        def inside_deferred_callable?(call)
+          call.each_ancestor.take_while { !it.equal?(node) }.any? do |ancestor|
+            ancestor.any_def_type? || deferred_callable_block?(ancestor)
+          end
+        end
+
+        def message_for(write)
+          format(MESSAGE, action: node.method_name, method: write.method_name)
+        end
+
+        class RequestStateReceiver
+          def initialize(receiver)
+            @receiver = receiver
+          end
+
+          def request_state?
+            ReceiverPath.new(receiver).any? { request_state_reader?(it) }
+          end
+
+          private
+            attr_reader :receiver
+
+            def request_state_reader?(candidate)
+              candidate.call_type? && REQUEST_STATE_RECEIVERS.include?(candidate.method_name) &&
+                (candidate.receiver.nil? || candidate.receiver.self_type?)
+            end
+
+            class ReceiverPath
+              include Enumerable
+
+              def initialize(receiver)
+                @receiver = receiver
+              end
+
+              def each
+                if block_given?
+                  current = receiver
+                  until current.nil?
+                    yield current
+                    current = if current.begin_type? && current.children.one?
+                      current.children.first
+                    elsif current.call_type?
+                      current.receiver
+                    end
+                  end
+                else
+                  to_enum(__method__)
+                end
+              end
+
+              private
+                attr_reader :receiver
+            end
+        end
+    end
+end

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

@@ -0,0 +1,78 @@
+# Ensures mixin arguments are sorted alphabetically.
+#
+# When including, extending, or prepending multiple modules on the same line,
+# they should be sorted alphabetically for consistency and easier scanning.
+#
+# The order of one `include` decides which module wins when two define the same
+# method, so sorting can change what the class does. The fix runs under `-A`
+# rather than `-a` for that reason. Write the modules on separate lines when the
+# order between them matters.
+#
+# @example
+#   # bad - unsorted
+#   include Searchable, Confirmable, Accessible
+#
+#   # good - sorted alphabetically
+#   include Accessible, Confirmable, Searchable
+#
+#   # good - single module (nothing to sort)
+#   include Searchable
+#
+#   # good - separate lines (each line is independent)
+#   include Searchable
+#   include Confirmable  # depends on Searchable
+#
+class RuboCop::Cop::Callbacksystems::OrderedMixinArguments < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_send(node)
+    report MixinCall.new(node, processed_source)
+  end
+
+  alias on_csend on_send
+
+  private
+    class MixinCall
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Sort mixin arguments alphabetically: `%<sorted>s`."
+
+      def initialize(node, processed_source)
+        @node = node
+        @processed_source = processed_source
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message, correcting: uncommented?) { correct(it) } if unsorted?
+      end
+
+      private
+        attr_reader :node, :processed_source
+        delegate :arguments, to: :node, private: true
+
+        def unsorted?
+          mixin_macro?(node) && arguments.many? && names != sorted_names
+        end
+
+        def names
+          @names ||= arguments.map(&:source)
+        end
+
+        def sorted_names
+          @sorted_names ||= names.sort
+        end
+
+        def message
+          format(MESSAGE, sorted: sorted_names.join(", "))
+        end
+
+        # Once arguments move, a comment on their lines no longer names the element or precedence it was written for.
+        def uncommented?
+          processed_source.comments.none? { it.loc.line.between?(node.first_line, node.last_line) }
+        end
+
+        def correct(corrector)
+          corrector.replace(range_spanning(arguments), sorted_names.join(", "))
+        end
+    end
+end

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

@@ -0,0 +1,103 @@
+# Ensures controller names are plural. A controller stands for the collection
+# its routes address, `/users` and `/users/1` alike, so the plural is the name
+# Rails derives the route and the resource from, and a singular one reads as a
+# model where a reader expects a resource.
+#
+# @example
+#   # bad
+#   class UserController < ApplicationController
+#   end
+#
+#   # good
+#   class UsersController < ApplicationController
+#   end
+#
+#   # good - already plural
+#   class PeopleController < ApplicationController
+#   end
+#
+#   # good - ignored names (configurable)
+#   class ApplicationController < ActionController::Base
+#   end
+#
+#   class BaseController < ApplicationController
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PluralControllerNames < RuboCop::Cop::Callbacksystems::Base
+  def on_class(node)
+    report ControllerClass.new(node, ignored_names: cop_config["IgnoredNames"])
+  end
+
+  private
+    class ControllerClass
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Controller names should be plural. Use `%<plural>sController` instead of `%<singular>sController`."
+
+      def initialize(node, ignored_names:)
+        @node = node
+        @ignored_names = ignored_names
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node.loc.name, message) if singular?
+      end
+
+      private
+        attr_reader :node, :ignored_names
+
+        def singular?
+          controller_class?(node) && named_controller? && !resource_name.excluded?
+        end
+
+        def named_controller?
+          class_name.end_with?("Controller")
+        end
+
+        def class_name
+          constant_name_of(node.identifier)
+        end
+
+        def resource_name
+          @resource_name ||= ResourceName.new(class_name.delete_suffix("Controller").split("::").last, ignored_names:)
+        end
+
+        def message
+          format(MESSAGE, plural: resource_name.plural, singular: resource_name)
+        end
+    end
+
+    class ResourceName
+      def initialize(name, ignored_names:)
+        @name = name
+        @ignored_names = ignored_names
+      end
+
+      def excluded?
+        ignored? || plural?
+      end
+
+      def to_s
+        name
+      end
+
+      def plural
+        name.pluralize
+      end
+
+      private
+        attr_reader :name, :ignored_names
+
+        def ignored?
+          ignored_names.include?(name)
+        end
+
+        def plural?
+          singular != name || singular.pluralize == name
+        end
+
+        def singular
+          @singular ||= name.singularize
+        end
+    end
+end

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

@@ -0,0 +1,86 @@
+# Detects direct use of instance variables that were assigned in initialize.
+# Reading `@node` where `node` would do ties the method to how the value is
+# stored, so a getter that later computes or memoizes it has to touch every
+# reader. Behind an `attr_reader` the method reads the name and nothing else.
+#
+# This cop only applies to instance variables assigned in the constructor.
+# Instance variables assigned elsewhere (like in controllers) are not flagged.
+#
+# @example
+#   # bad - using @node directly when it was set in initialize
+#   class Foo
+#     def initialize(node)
+#       @node = node
+#     end
+#
+#     def process
+#       @node.children
+#     end
+#   end
+#
+#   # good - using attr_reader
+#   class Foo
+#     def initialize(node)
+#       @node = node
+#     end
+#
+#     def process
+#       node.children
+#     end
+#
+#     private
+#       attr_reader :node
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PreferAttrReaderOverInstanceVariable < RuboCop::Cop::Callbacksystems::Base
+  def on_class(node)
+    report_each InstanceVariableReads.new(node)
+  end
+
+  alias on_module on_class
+
+  private
+    class InstanceVariableReads
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Use `%<name>s` (via attr_reader) instead of `@%<name>s` for instance variables assigned in initialize."
+
+      def initialize(class_node)
+        @class_node = class_node
+      end
+
+      def each_offense
+        reads_of_constructor_variables.each { yield offense_for(it) }
+      end
+
+      private
+        attr_reader :class_node
+
+        def reads_of_constructor_variables
+          reads_outside_constructor.select { constructor_variable_names.include?(it.name) }
+        end
+
+        def reads_outside_constructor
+          nodes_in(class_node.body, :ivar).select { instance_method_read?(it) }
+        end
+
+        def instance_method_read?(read)
+          method = enclosing_method_of(read)
+          method&.def_type? && direct_method_definition?(method) && !method.method?(:initialize) &&
+            enclosing_class_or_module_of(read) == class_node && self_preserved_between?(read, boundary: method)
+        end
+
+        def constructor_variable_names
+          @constructor_variable_names ||= nodes_in(initialize_method&.body, :ivasgn)
+            .select { self_preserved_between?(it, boundary: initialize_method) }.to_set(&:name)
+        end
+
+        def initialize_method
+          direct_method_nodes_in(class_node.body).find { it.method?(:initialize) }
+        end
+
+        def offense_for(read)
+          RuboCop::Callbacksystems::Offense.new(read, format(MESSAGE, name: name_without_sigil(read.name)))
+        end
+    end
+end