rubocop-dev_doc 0.1.0 → 0.2.0

data/lib/rubocop/cop/dev_doc/rails/application_record_transaction.rb

@@ -0,0 +1,56 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Use `ApplicationRecord.transaction` instead of `SomeModel.transaction` outside model files.
+        #
+        # ## Rationale
+        # When using `transaction` outside of a model, `SomeModel.transaction`
+        # reads as if there is a meaningful link to that model when there isn't.
+        # `ApplicationRecord.transaction` is functionally identical and makes
+        # it clear that the transaction has no special relationship to any
+        # particular model.
+        #
+        #   ❌  (in a controller or service)
+        #   Checklist.transaction do
+        #     ...
+        #   end
+        #
+        #   ✔️
+        #   ApplicationRecord.transaction do
+        #     ...
+        #   end
+        #
+        # @example
+        #   # bad (in a controller or service)
+        #   Order.transaction do
+        #     order.save!
+        #   end
+        #
+        #   # good
+        #   ApplicationRecord.transaction do
+        #     order.save!
+        #   end
+        class ApplicationRecordTransaction < Base
+          extend AutoCorrector
+
+          ALLOWED_RECEIVERS = %w[ApplicationRecord ActiveRecord::Base].freeze
+
+          MSG = 'Use `ApplicationRecord.transaction` instead of `%<receiver>s.transaction` outside model files.'.freeze
+          RESTRICT_ON_SEND = %i[transaction].freeze
+
+          def on_send(node)
+            receiver = node.receiver
+            return if receiver.nil?
+            return unless receiver.const_type?
+            return if ALLOWED_RECEIVERS.include?(receiver.source)
+
+            add_offense(receiver, message: format(MSG, receiver: receiver.source)) do |corrector|
+              corrector.replace(receiver, 'ApplicationRecord')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/rails/avoid_rails_callbacks.rb

@@ -0,0 +1,135 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Avoid Rails ActiveRecord callback DSL in model files.
+        #
+        # ## Rationale
+        # Rails callbacks (`after_create`, `before_save`, etc.) cause problems
+        # with transaction ordering, hidden side effects, and unclear control
+        # flow. When a callback fires is not always obvious to the reader, and
+        # callbacks can trigger unexpectedly during testing or data migrations.
+        #
+        # Instead, implement an explicit method that makes the side effect
+        # visible at the call site:
+        #
+        #   ❌
+        #   class Order < ApplicationRecord
+        #     after_create :send_confirmation_email
+        #   end
+        #
+        #   ✔️
+        #   class Order < ApplicationRecord
+        #     def save_with_confirmation_email
+        #       transaction do
+        #         save!
+        #         OrderMailer.confirmation(self).deliver_later
+        #       end
+        #     end
+        #   end
+        #
+        # ## When you have multiple call sites needing the same guard
+        # The single-method-per-place pattern above works when there is one
+        # natural call site. When several controllers/jobs/bulk operations all
+        # need to enforce the same invariant before destroying or saving, the
+        # temptation is to reach for `before_destroy` / `before_save` so
+        # nothing slips through. There is a cleaner pattern that gives the
+        # same guarantee without a callback — the **fence-and-helper**:
+        #
+        #   1. Alias the dangerous primitive as private, e.g.
+        #        alias _unguarded_hard_destroy hard_destroy
+        #        private :_unguarded_hard_destroy
+        #   2. Override the public name to raise with a pointer to the safe
+        #      method:
+        #        def hard_destroy
+        #          raise 'Use SomeModel#safely_hard_destroy — it keeps X in sync'
+        #        end
+        #   3. Expose a `safely_*` helper that does the guard, calls the
+        #      private alias, and runs any side effects, all wrapped in a
+        #      transaction so atomicity is a property of the helper rather
+        #      than of the caller:
+        #        def safely_hard_destroy
+        #          if invariant_would_be_violated?
+        #            errors.add(:base, '...')
+        #            return false
+        #          end
+        #          ApplicationRecord.transaction do
+        #            _unguarded_hard_destroy
+        #            cleanup_side_effects!
+        #          end
+        #          destroyed?
+        #        end
+        #
+        # Direct calls to the dangerous primitive now raise with a helpful
+        # message; the only legal path is the safe helper. Every existing
+        # caller updates to `safely_*` and inherits the guard automatically.
+        #
+        # Bonus property: ad-hoc bypass for ops/debugging is clean. Calling
+        # `model.send(:_unguarded_hard_destroy)` in the Rails console is
+        # scoped to the single call (no global state), self-documenting (you
+        # have to type "unguarded"), and greppable. This is intended for
+        # console / data-cleanup / debugging use only — if app code reaches
+        # for `send(:_unguarded_*)`, that's a design smell and should be
+        # solved by extending the helper instead.
+        #
+        # ## Inline disable
+        # We have not yet found a case in our codebases where a callback was
+        # the right answer — explicit methods or the fence-and-helper pattern
+        # have always covered the legitimate intent. If you think you have a
+        # genuine exception, disable this cop inline with a written
+        # justification — expect pushback in review:
+        #
+        #   after_create :some_callback # rubocop:disable DevDoc/Rails/AvoidRailsCallbacks
+        #   # Reason: <explanation>
+        #
+        # Both the symbol form and the block form are flagged:
+        #
+        #   ❌ Symbol form
+        #   after_create :send_confirmation_email
+        #
+        #   ❌ Block form
+        #   after_create { send_confirmation_email }
+        #
+        # @example
+        #   # bad
+        #   after_create :send_confirmation
+        #   before_save :normalize_name
+        #   around_update :wrap_in_audit_log
+        #
+        #   # bad (block form)
+        #   after_create { send_confirmation }
+        #
+        #   # good
+        #   def save_with_confirmation
+        #     transaction { save! }
+        #     send_confirmation
+        #   end
+        class AvoidRailsCallbacks < Base
+          CALLBACKS = %i[
+            after_create after_create_commit after_save after_update
+            after_destroy after_commit after_rollback after_initialize
+            after_find after_touch before_create before_save before_update
+            before_destroy before_validation after_validation
+            around_create around_save around_update around_destroy
+          ].freeze
+
+          MSG = 'Avoid `%<method>s` — extract an explicit method (e.g. `save_with_*`) ' \
+                'so the side effect is visible at the call site.'.freeze
+          RESTRICT_ON_SEND = CALLBACKS
+
+          def on_send(node)
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+
+          def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+            send_node = node.send_node
+            return unless CALLBACKS.include?(send_node.method_name)
+
+            add_offense(send_node.loc.selector, message: format(MSG, method: send_node.method_name))
+          end
+          alias on_numblock on_block
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/rails/enum_must_be_symbolized.rb

@@ -0,0 +1,83 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Every Rails `enum` declaration must be paired with `enum_symbolize`
+        # so the reader returns a symbol instead of Rails' default string form.
+        #
+        # ## Rationale
+        # Strings and symbols are not equal in Ruby (`:foo == 'foo'` is `false`).
+        # Rails' `enum` macro defines a reader that returns the string form, so
+        # downstream comparisons like `record.status == :active` silently fail.
+        # Pairing `enum :status, …` with `enum_symbolize :status` overrides the
+        # reader to hand back a symbol, eliminating the footgun.
+        #
+        # See `best_practices/backend/en/01a_defensive_programming.md` item 7.
+        #
+        #   ❌
+        #   class Reimbursement < ApplicationRecord
+        #     enum :payment_status, { draft: 0, pending: 1, finalized: 2 }
+        #   end
+        #
+        #   ✔
+        #   class Reimbursement < ApplicationRecord
+        #     enum :payment_status, { draft: 0, pending: 1, finalized: 2 }
+        #
+        #     enum_symbolize :payment_status
+        #   end
+        #
+        # `enum_symbolize` accepts multiple names so several enums can be
+        # paired in one call:
+        #
+        #   ✔
+        #   enum_symbolize :payment_status, :finalize_intent
+        #
+        # @example
+        #   # bad
+        #   enum :status, { active: 0, archived: 1 }
+        #
+        #   # good
+        #   enum :status, { active: 0, archived: 1 }
+        #   enum_symbolize :status
+        class EnumMustBeSymbolized < Base
+          MSG = 'Pair `enum :%<name>s` with `enum_symbolize :%<name>s` so the reader returns a symbol ' \
+                '(see backend/01a_defensive_programming.md item 7).'.freeze
+
+          def_node_matcher :enum_call, <<~PATTERN
+            (send nil? :enum (sym $_) ...)
+          PATTERN
+
+          def_node_matcher :enum_symbolize_call, <<~PATTERN
+            (send nil? :enum_symbolize $...)
+          PATTERN
+
+          def on_class(node)
+            body = node.body
+            return unless body
+
+            statements = body.begin_type? ? body.children : [body]
+
+            enum_decls = []
+            symbolized = []
+
+            statements.each do |stmt|
+              next unless stmt.respond_to?(:send_type?) && stmt.send_type?
+
+              if (name = enum_call(stmt))
+                enum_decls << [name, stmt]
+              elsif (args = enum_symbolize_call(stmt))
+                symbolized.concat(args.select(&:sym_type?).map(&:value))
+              end
+            end
+
+            enum_decls.each do |name, decl|
+              next if symbolized.include?(name)
+
+              add_offense(decl, message: format(MSG, name: name))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/rails/no_deliver_later_in_transaction.rb

@@ -27,11 +27,12 @@ module RuboCop
         #     OrganizationMailer.with(organization: organization).deliver_later
         #   end
         #
-        # ## Watch out for indirect calls
+        # ## Configurable blocklist for library wrappers
         # Some libraries call `perform_later` / `deliver_later` behind the
-        # scenes — e.g. `@user.send_verification_email!` from the Devise gem.
-        # This cop cannot detect those wrappers; reviewers should still flag
-        # them when they appear inside a `transaction` block.
+        # scenes. Configure `KnownAsyncWrappers` to flag those methods too.
+        # Common Devise methods are included by default. This is a partial
+        # mitigation — reviewers must still catch unknown wrappers not in the
+        # list.
         #
         # @example
         #   # bad
@@ -40,6 +41,12 @@ module RuboCop
         #     OrganizationMailer.with(organization: organization).deliver_later
         #   end
         #
+        #   # bad (Devise wrapper, caught via KnownAsyncWrappers)
+        #   User.transaction do
+        #     @user.save!
+        #     @user.send_verification_email!
+        #   end
+        #
         #   # good
         #   organization.transaction do
         #     organization.save!
@@ -47,16 +54,26 @@ module RuboCop
         #   OrganizationMailer.with(organization: organization).deliver_later
         class NoDeliverLaterInTransaction < Base
           MSG = '`%<method>s` inside a `transaction` block may use stale data. Move it outside the transaction.'.freeze
-          RESTRICT_ON_SEND = %i[deliver_later perform_later].freeze
+
+          CORE_METHODS = %i[deliver_later perform_later].freeze
 
           def on_send(node)
             return unless inside_transaction?(node)
+            return unless tracked_method?(node.method_name)
 
             add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
           end
 
           private
 
+          def tracked_method?(name)
+            CORE_METHODS.include?(name) || known_async_wrappers.include?(name.to_s)
+          end
+
+          def known_async_wrappers
+            cop_config.fetch('KnownAsyncWrappers', [])
+          end
+
           def inside_transaction?(node)
             node.each_ancestor(:block).any? do |ancestor|
               ancestor.method_name == :transaction

data/lib/rubocop/cop/dev_doc/route/resources_require_only.rb

@@ -2,7 +2,7 @@ module RuboCop
   module Cop
     module DevDoc
       module Route
-        # Always use `only:` (or `except:`) for `resources` / `resource` in routes.rb.
+        # Always use `only:` for `resources` / `resource` in routes.rb.
         #
         # ## Rationale
         # When defining routes in routes.rb, it is important to explicitly
@@ -12,45 +12,59 @@ module RuboCop
         # exposes routes the application has no controller action for, or
         # routes that probably should be locked down.
         #
+        # `only:` is preferred over `except:` because it is explicit about
+        # what is exposed. `except:` exposes everything *not* in the list,
+        # which is easier to misread when the action set changes.
+        #
+        # Set `RequireOnly: false` to accept both `only:` and `except:`.
+        #
         #   ✔️
         #   resources :job_applications, only: [:index, :new, :create]
         #
-        # In this example, only three actions are exposed for
-        # `job_applications`: index, new, and create. This is safer because
-        # only the needed actions are declared and accessible.
+        # @example EnforcedStyle: RequireOnly (default)
+        #   # bad
+        #   resources :users
+        #   resources :users, except: [:destroy]
         #
-        # `except:` is also acceptable, but `only:` is preferred because it
-        # is more explicit about what is being exposed.
+        #   # good
+        #   resources :users, only: %i[index show]
         #
-        # @example
+        # @example EnforcedStyle: RequireOnly: false
         #   # bad
         #   resources :users
-        #   resource :profile
         #
         #   # good
         #   resources :users, only: %i[index show]
-        #   resource :profile, only: %i[show edit update]
         #   resources :users, except: [:destroy]
         class ResourcesRequireOnly < Base
           MSG = 'Specify `only:` or `except:` for `%<method>s :%<name>s` to avoid exposing unintended actions.'.freeze
+          MSG_REQUIRE_ONLY = 'Specify `only:` for `%<method>s :%<name>s` ' \
+                             '(`except:` is allowed only with `RequireOnly: false`).'.freeze
           RESTRICT_ON_SEND = %i[resources resource].freeze
 
           def on_send(node)
-            return if only_or_except?(node)
+            has_only = key_present?(node, :only)
+            has_except = key_present?(node, :except)
+
+            return if has_only
+            return if has_except && !require_only?
 
             name = node.first_argument&.value || '?'
-            add_offense(node.loc.selector, message: format(MSG, method: node.method_name, name: name))
+            msg = has_except && require_only? ? MSG_REQUIRE_ONLY : MSG
+            add_offense(node.loc.selector, message: format(msg, method: node.method_name, name: name))
           end
 
           private
 
-          def only_or_except?(node)
+          def require_only?
+            cop_config.fetch('RequireOnly', true)
+          end
+
+          def key_present?(node, key)
             options = node.arguments.find(&:hash_type?)
             return false unless options
 
-            options.pairs.any? do |pair|
-              pair.key.sym_type? && %i[only except].include?(pair.key.value)
-            end
+            options.pairs.any? { |pair| pair.key.sym_type? && pair.key.value == key }
           end
         end
       end

data/lib/rubocop/cop/dev_doc/style/avoid_head_response.rb

@@ -2,17 +2,18 @@ module RuboCop
   module Cop
     module DevDoc
       module Style
-        # Avoid `head()` responses in controllers.
+        # Avoid `head()` with error status codes in controllers.
         #
         # ## Rationale
-        # `head()` returns an empty body with no useful information for the
-        # client. Its presence is usually a sign that error handling should be
-        # delegated to Rails exceptions (e.g. `ActiveRecord::RecordNotFound`)
-        # or model validations instead.
+        # Using `head()` for error responses returns an empty body with no
+        # useful information for the client. Error handling should be delegated
+        # to Rails exceptions (e.g. `ActiveRecord::RecordNotFound`) or model
+        # validations instead, which give the client more context.
         #
-        # If you find yourself reaching for `head()`, consider whether a
-        # well-known Rails exception or a model validation can handle the
-        # case more cleanly:
+        # Success statuses like `:ok`, `:no_content`, and `:accepted` are
+        # legitimate uses of `head()` and are not flagged.
+        #
+        # The set of flagged statuses is configurable via `FlaggedStatuses:`.
         #
         #   ❌ Manually returns 404 with no body
         #   def show
@@ -25,30 +26,63 @@ module RuboCop
         #     @user = User.find(params[:id])
         #   end
         #
-        # NOTE: The cop flags every bare `head(...)` call. Some legitimate uses
-        # (e.g. `head :no_content` for a successful DELETE, or simple webhook
-        # acknowledgements) still get flagged — disable per-line in those cases.
+        #   ✔️ Success response — empty body is correct here
+        #   def destroy
+        #     @resource.destroy!
+        #     head :no_content
+        #   end
         #
         # @example
         #   # bad
-        #   def glib_load_resource
-        #     @user = User.find_by(id: params[:id])
-        #     head(:not_found) unless @user
-        #   end
+        #   head(:not_found)
         #
-        #   # good
-        #   def glib_load_resource
-        #     @user = User.find(params[:id])
-        #   end
+        #   # bad
+        #   head(:unprocessable_entity)
+        #
+        #   # good (success status — not flagged)
+        #   head(:no_content)
+        #
+        #   # good (success status — not flagged)
+        #   head(:ok)
+        #
+        #   # good (dynamic status — not flagged to avoid false positives)
+        #   head(status_code)
         class AvoidHeadResponse < Base
-          MSG = 'Avoid `head()`. Delegate error handling to Rails exceptions ' \
-                '(e.g. use `find` instead of `find_by` + `head(:not_found)`) or model validations.'.freeze
+          MSG = 'Avoid `head(%<status>s)` for error handling. ' \
+                'Delegate to Rails exceptions or model validations instead.'.freeze
+
           RESTRICT_ON_SEND = %i[head].freeze
 
+          DEFAULT_FLAGGED_STATUSES = %w[
+            not_found unprocessable_entity forbidden unauthorized
+            bad_request conflict gone method_not_allowed
+            404 422 403 401 400 409 410 405
+          ].freeze
+
           def on_send(node)
             return unless node.receiver.nil?
 
-            add_offense(node.loc.selector)
+            status_node = node.arguments.first
+            return unless status_node
+            return unless flagged_literal?(status_node)
+
+            add_offense(node.loc.selector, message: format(MSG, status: status_display(status_node)))
+          end
+
+          private
+
+          def flagged_literal?(node)
+            return false unless node.sym_type? || node.int_type?
+
+            flagged_statuses.include?(node.value.to_s)
+          end
+
+          def status_display(node)
+            node.sym_type? ? ":#{node.value}" : node.value.to_s
+          end
+
+          def flagged_statuses
+            cop_config.fetch('FlaggedStatuses', DEFAULT_FLAGGED_STATUSES).map(&:to_s)
           end
         end
       end

data/lib/rubocop/cop/dev_doc/style/avoid_options_hash.rb

@@ -0,0 +1,102 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Avoid `**options`-style kwargs in method signatures; use explicit keyword args.
+        #
+        # ## Rationale
+        # Keyword args raise `ArgumentError` on typos, are self-labeled at the
+        # call site, and get IDE autocomplete. Options hashes (via `**opts`)
+        # silently swallow misspelled keys, hide what's accepted, and depend on
+        # doc/source-reading to use correctly.
+        #
+        #   ❌ Options hash — typos pass silently
+        #   def configure(name:, **options)
+        #     title = options[:title]
+        #     color = options[:color]
+        #   end
+        #   configure(name: 'x', titel: 'wrong')   # silently ignored — title is nil
+        #
+        #   ✔️ Keyword args — typo raises immediately
+        #   def configure(name:, title: nil, color: nil)
+        #   end
+        #   configure(name: 'x', titel: 'wrong')   # ArgumentError: unknown keyword: :titel
+        #
+        # Pure-forwarding kwargs are exempt — when the only use of the kwrestarg
+        # is to splat it into another call, there is no options-hash behaviour:
+        #
+        #   ✔️ Pure forwarding — exempt
+        #   def foo(**args)
+        #     other(**args)
+        #   end
+        #
+        # Anonymous double-splat (`**`) is also always exempt.
+        #
+        # @example
+        #   # bad
+        #   def configure(name:, **options)
+        #     options[:title]
+        #   end
+        #
+        #   # good
+        #   def configure(name:, title: nil, color: nil)
+        #   end
+        #
+        #   # good (pure forwarding)
+        #   def foo(**args)
+        #     other(**args)
+        #   end
+        class AvoidOptionsHash < Base
+          MSG = 'Use keyword arguments instead of `**%<name>s` — ' \
+                'typos in keyword args raise `ArgumentError`; options hashes swallow them silently.'.freeze
+
+          def on_def(node)
+            check_method(node)
+          end
+          alias on_defs on_def
+
+          private
+
+          def check_method(node)
+            kwrestarg = find_kwrestarg(node)
+            return unless kwrestarg
+
+            kwrest_name = kwrestarg.node_parts[0]
+            return if kwrest_name.nil?
+
+            body = node.body
+            return if pure_forwarding?(body, kwrest_name)
+
+            add_offense(kwrestarg, message: format(MSG, name: kwrest_name))
+          end
+
+          def find_kwrestarg(node)
+            args_node = node.arguments
+            args_node.each_child_node(:kwrestarg).first
+          end
+
+          def pure_forwarding?(body, kwrest_name)
+            return true if body.nil?
+
+            lvar_refs = collect_lvar_refs(body, kwrest_name)
+            return true if lvar_refs.empty?
+
+            lvar_refs.all? { |lvar| under_kwsplat?(lvar) }
+          end
+
+          def collect_lvar_refs(node, name)
+            refs = []
+            node.each_descendant(:lvar) do |lvar|
+              refs << lvar if lvar.node_parts[0] == name
+            end
+            refs
+          end
+
+          def under_kwsplat?(node)
+            node.parent&.kwsplat_type?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/style/avoid_send.rb

@@ -2,14 +2,16 @@ module RuboCop
   module Cop
     module DevDoc
       module Style
-        # Avoid `send` and `public_send` with an explicit receiver.
+        # Avoid dynamic `send` and `public_send` with an explicit receiver.
         #
         # ## Rationale
         # `send()` can call *any* method, including destructive ones like
-        # `destroy`. When the method name is dynamic, this is a real risk — a
-        # crafted parameter can invoke methods the developer never intended to
-        # expose. If `send()` is unavoidable, add safeguards to restrict which
-        # methods can be called.
+        # `destroy`. The risk is specifically with **dynamic** method names —
+        # when the argument is a variable or interpolated string, a crafted
+        # value could invoke methods the developer never intended to expose.
+        #
+        # **Literal symbol arguments are exempt** — the method name is fixed at
+        # code-write time and visible to reviewers, equivalent to a direct call.
         #
         # ## Safer alternatives
         #
@@ -34,23 +36,26 @@ module RuboCop
         #   ✔️ Restricted — only methods with the prefix can be called
         #   obj.send("export_#{method_name}")
         #
-        # **c) For known methods — call directly instead of via `send`.**
-        #
         # @example
         #   # bad
         #   @user.send(method_name)
         #   obj.public_send(action)
+        #   obj.send("export_#{x}")
+        #
+        #   # good — literal symbol: method name is statically visible
+        #   instance.send(:private_helper, arg)
         #
         #   # good
         #   @user[attribute_name]
         #   obj.send("export_#{method_name}")
         class AvoidSend < Base
-          MSG = 'Avoid `%<method>s` with an explicit receiver. ' \
-                'Use bracket notation for model attributes, or restrict callable methods with a prefix.'.freeze
+          MSG = "Avoid dynamic `%<method>s` — use bracket notation for model attributes, " \
+                "or a prefix (`obj.send(\"export_\#{x}\")`) to restrict callable methods.".freeze
           RESTRICT_ON_SEND = %i[send public_send].freeze
 
           def on_send(node)
             return if node.receiver.nil?
+            return if node.first_argument&.sym_type?
 
             add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
           end