rubocop-dev_doc 0.1.0 → 0.3.0

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/rails/strong_parameters_expect.rb

@@ -0,0 +1,137 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Flag `params.require(:foo).permit(...)` and the reverse form
+        # `params.permit(foo: ...).require(:foo)` — use `params.expect(foo: [...])`
+        # instead.
+        #
+        # ## Rationale
+        # The upstream `Rails/StrongParametersExpect` autocorrects two distinct
+        # patterns: the hash-form rewrite (`require.permit` → `expect`) and the
+        # scalar form (`params[:id]` inside find-method chains). The scalar form
+        # fires false positives on optional query params (e.g.
+        # `params[:status]&.to_sym || :draft`) and forces scattered per-line
+        # disables — the typical workaround is to disable the upstream cop
+        # entirely, losing the hash-form benefit too.
+        #
+        # This cop targets **only** the hash-form rewrite, so projects can keep
+        # `Rails/StrongParametersExpect: Enabled: false` and still enforce the
+        # safe `params.expect` pattern.
+        #
+        # `params.expect` raises `ActionController::ParameterMissing` for scalar
+        # values where `permit` would silently return `nil`, and it makes the
+        # permitted-attribute shape explicit in one call.
+        #
+        # ## Patterns detected
+        #
+        #   ❌ require → permit chain
+        #   params.require(:user).permit(:name, :email)
+        #
+        #   ❌ permit → require chain (less common)
+        #   params.permit(user: %i[name email]).require(:user)
+        #
+        #   ✔️
+        #   params.expect(user: [:name, :email])
+        #
+        # ## Not flagged
+        # Scalar `params[:foo]` in any context — leave that to per-project
+        # decision or the upstream cop.
+        #
+        # @example
+        #   # bad
+        #   params.require(:user).permit(:name, :email)
+        #
+        #   # bad
+        #   params.require(:user).permit(:name, profile_attributes: [:bio])
+        #
+        #   # bad
+        #   params.permit(user: %i[name email]).require(:user)
+        #
+        #   # good
+        #   params.expect(user: [:name, :email])
+        #
+        #   # good
+        #   params.expect(user: [:name, { profile_attributes: [:bio] }])
+        class StrongParametersExpect < Base
+          extend AutoCorrector
+
+          MSG_REQUIRE_PERMIT = 'Use `params.expect(%<key>s: [...])` instead of ' \
+                               '`params.require(:%<key>s).permit(...)`.'
+          MSG_PERMIT_REQUIRE = 'Use `params.expect(%<key>s: ...)` instead of ' \
+                               '`params.permit(%<key>s: ...).require(:%<key>s)`.'
+
+          RESTRICT_ON_SEND = %i[permit require].freeze
+
+          def on_send(node)
+            check_require_permit(node) if node.method_name == :permit
+            check_permit_require(node) if node.method_name == :require
+          end
+
+          private
+
+          # Match: params.require(:foo).permit(...)
+          def check_require_permit(permit_node)
+            require_node = permit_node.receiver
+            return unless require_node&.send_type? && require_node.method_name == :require
+            return unless params_receiver?(require_node.receiver)
+            return unless require_node.arguments.one? && require_node.first_argument.sym_type?
+
+            key = require_node.first_argument.value
+            add_offense(permit_node, message: format(MSG_REQUIRE_PERMIT, key: key)) do |corrector|
+              replacement = build_require_permit_replacement(
+                require_node.receiver, key, permit_node.arguments
+              )
+              corrector.replace(permit_node, replacement)
+            end
+          end
+
+          # Match: params.permit(foo: ...).require(:foo)
+          def check_permit_require(require_node)
+            permit_node = require_node.receiver
+            return unless permit_node&.send_type? && permit_node.method_name == :permit
+            return unless params_receiver?(permit_node.receiver)
+            return unless require_node.arguments.one? && require_node.first_argument.sym_type?
+
+            key = require_node.first_argument.value
+            pair = permit_hash_pair_for_key(permit_node, key)
+            return unless pair
+
+            add_offense(require_node, message: format(MSG_PERMIT_REQUIRE, key: key)) do |corrector|
+              params_src = permit_node.receiver.source
+              corrector.replace(require_node, "#{params_src}.expect(#{key}: #{pair.value.source})")
+            end
+          end
+
+          def params_receiver?(node)
+            node&.send_type? && node.method_name == :params && node.receiver.nil?
+          end
+
+          # Find the first hash pair whose key matches `key` in permit's arguments.
+          def permit_hash_pair_for_key(permit_node, key)
+            permit_node.arguments.each do |arg|
+              next unless arg.hash_type?
+
+              arg.pairs.each do |pair|
+                return pair if pair.key.sym_type? && pair.key.value == key
+              end
+            end
+            nil
+          end
+
+          # Build the replacement for `params.require(:key).permit(*args)`.
+          # Symbol args stay as-is; hash args are wrapped in `{ }` since they
+          # need explicit braces when placed inside an array literal.
+          def build_require_permit_replacement(params_node, key, permit_args)
+            inner = permit_args.map { |arg| permit_arg_source(arg) }.join(', ')
+            "#{params_node.source}.expect(#{key}: [#{inner}])"
+          end
+
+          def permit_arg_source(arg)
+            arg.hash_type? ? "{ #{arg.source} }" : arg.source
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Route
+        # Avoid custom `member` / `collection` actions; model them as RESTful
+        # sub-resources instead.
+        #
+        # ## Rationale
+        # Follow Rails' standard REST principles as much as possible. A resource
+        # exposes seven standard actions (`index`, `show`, `new`, `create`,
+        # `edit`, `update`, `destroy`); anything declared through a `member` or
+        # `collection` block is a custom verb bolted onto the resource. Each one
+        # is better expressed as its own RESTful sub-resource — the action then
+        # reads as a noun being created/destroyed, scopes cleanly under Pundit
+        # policies, and keeps every controller a thin CRUD controller.
+        #
+        #   ❌ POST /products/3/activate
+        #   resources :products, only: [:show] do
+        #     member { post :activate }
+        #   end
+        #
+        #   ✔️ POST /products/3/activations  (create an activation)
+        #   resources :products, only: [:show] do
+        #     resources :activations, only: [:create]
+        #   end
+        #
+        #   ✔️ a mode on the standard edit/update, when it's really one resource
+        #   PATCH /products/3?mode=activate
+        #
+        # A reversible pair (`activate` / `deactivate`, `lock` / `unlock`,
+        # `archive` / `restore`) maps naturally onto `create` / `destroy` of one
+        # sub-resource.
+        #
+        # ## Exception
+        # The doc says "as much as possible" — some custom actions are genuinely
+        # awkward to model as a sub-resource (a multi-step wizard step, a
+        # non-CRUD report endpoint). For those, disable the cop on the line with
+        # a written reason, e.g.:
+        #
+        #   member do
+        #     # rubocop:disable DevDoc/Route/NoCustomActions
+        #     get :balance # multi-step finalize wizard; not a persisted resource
+        #     # rubocop:enable DevDoc/Route/NoCustomActions
+        #   end
+        #
+        # This cop flags every form a custom resource action takes:
+        #   - inside a `member` / `collection` block
+        #   - the inline `on: :member` / `on: :collection` option
+        #     (`get :activate, on: :member`)
+        #   - a bare verb directly inside a `resources` / `resource` block,
+        #     which Rails treats as a collection route (`resources :x do
+        #     get :search end`)
+        #   - a bare verb inside a `concern` block (its routes are mixed into
+        #     resources, so a custom verb there is a custom resource action)
+        #
+        # `constraints` / `defaults` wrappers between the verb and its resource
+        # are transparent — a custom action nested inside them is still caught.
+        #
+        # NOTE: Stand-alone non-resource routes (`get 'sitemap.xml'`,
+        # `get 'proxy'`) and verbs scoped by a `namespace` / `scope` block are
+        # not resourceful, and are intentionally left alone. A custom action
+        # written as a flat top-level route (`get 'photos/search', to:
+        # 'photos#search'`) is indistinguishable from such a route and cannot be
+        # flagged without false positives — that case is left to review.
+        #
+        # @example
+        #   # bad
+        #   resources :products, only: [:show] do
+        #     member do
+        #       post :activate
+        #       post :deactivate
+        #     end
+        #   end
+        #
+        #   # good
+        #   resources :products, only: [:show] do
+        #     resources :activations, only: %i[create destroy]
+        #   end
+        class NoCustomActions < Base
+          MSG = 'Custom `%<context>s` action `%<verb>s %<name>s`. Model it as a RESTful ' \
+                'sub-resource (e.g. `resources :activations, only: [:create]`) instead. ' \
+                'Disable with a reason if a custom action is genuinely unavoidable.'.freeze
+
+          RESTRICT_ON_SEND = %i[get post patch put delete match].freeze
+
+          MEMBER_OR_COLLECTION = %i[member collection].freeze
+          RESOURCEFUL = %i[resources resource].freeze
+          # Wrappers that add conditions but do not change whether the verb is a
+          # resource action — walk through them to find the real context.
+          TRANSPARENT_WRAPPERS = %i[constraints defaults].freeze
+
+          def on_send(node)
+            context = routing_context(node)
+            return unless context
+
+            add_offense(
+              node.loc.selector,
+              message: format(MSG, context: context, verb: node.method_name, name: action_name(node))
+            )
+          end
+
+          private
+
+          # The routing context that makes this verb a custom resource action,
+          # or nil if it is a stand-alone route. Shapes that count:
+          #   - inside a `member` / `collection` block (at any depth)
+          #   - the inline `on: :member` / `on: :collection` / `on: :new` option
+          #   - a bare verb whose nearest non-transparent enclosing block is
+          #     `resources` / `resource` (a collection route) or `concern`
+          # `constraints` / `defaults` wrappers are transparent (walked through);
+          # a `namespace` / `scope` block turns the verb into a stand-alone route
+          # and stops the search.
+          def routing_context(node)
+            inline = inline_on_context(node)
+            return inline if inline
+
+            sends = enclosing_routing_sends(node)
+
+            # `member` / `collection` mark a custom action at any nesting depth.
+            explicit = sends.find { |s| MEMBER_OR_COLLECTION.include?(s.method_name) }
+            return explicit.method_name.to_s if explicit
+
+            # Otherwise the nearest block that isn't a transparent wrapper decides.
+            decider = sends.find { |s| !TRANSPARENT_WRAPPERS.include?(s.method_name) }
+            return unless decider
+
+            return 'collection' if RESOURCEFUL.include?(decider.method_name)
+
+            'concern' if decider.method_name == :concern
+          end
+
+          # The block call-sends enclosing this node, innermost first, limited to
+          # DSL blocks with no explicit receiver. Covers `do...end`, `{}`, and
+          # numbered (`_1`) / `it` block forms.
+          def enclosing_routing_sends(node)
+            node.each_ancestor(:block, :numblock, :itblock).filter_map do |b|
+              send = b.children.first
+              send if send.send_type? && send.receiver.nil?
+            end
+          end
+
+          # The value of an inline `on:` option (`:member` / `:collection` /
+          # `:new`) as a string, or nil when absent. `on:` is only ever used to
+          # attach a custom action to a resource.
+          def inline_on_context(node)
+            options = node.arguments.find(&:hash_type?)
+            return unless options
+
+            pair = options.pairs.find { |p| p.key.sym_type? && p.key.value == :on }
+            return unless pair
+
+            pair.value.sym_type? ? pair.value.value.to_s : 'member'
+          end
+
+          # Display name for the action: the leading symbol/string argument
+          # (`:activate`, `'weeks/:start_date'`), or `?` when it can't be read.
+          def action_name(node)
+            arg = node.first_argument
+            return '?' unless arg
+
+            case arg.type
+            when :sym then ":#{arg.value}"
+            when :str then "'#{arg.value}'"
+            else '?'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+require 'active_support/inflector'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module Route
+        # Use a plural name for `resources` and a singular name for `resource`.
+        #
+        # ## Rationale
+        # Follow Rails' standard REST conventions. A plural `resources` maps to a
+        # collection (`/products`), so its name should be plural; a singular
+        # `resource` maps to a single implicit-id resource (`/profile`), so its
+        # name should be singular. Mismatched number reads against every Rails
+        # convention and produces awkward path/helper names.
+        #
+        #   ❌ resources :product   # => /product
+        #   ❌ resource  :sessions  # singular resource, plural name
+        #
+        #   ✔️ resources :products  # => /products
+        #   ✔️ resource  :session   # => /session
+        #
+        # The check uses ActiveSupport's inflector, so irregular and uncountable
+        # nouns are handled (`resources :people`, `resources :fish` are fine).
+        #
+        # ## Exception
+        # A project with custom inflections (`config/initializers/inflections.rb`)
+        # the bundled inflector doesn't know about may be misjudged. Disable the
+        # cop on that line with a reason.
+        #
+        # @example
+        #   # bad
+        #   resources :product
+        #   resource :sessions
+        #
+        #   # good
+        #   resources :products
+        #   resource :session
+        class ResourceNameNumber < Base
+          MSG = '`%<method>s` should name a %<number>s resource — use `:%<expected>s`.'.freeze
+
+          RESTRICT_ON_SEND = %i[resources resource].freeze
+
+          def on_send(node)
+            node.arguments.each do |arg|
+              name = name_of(arg)
+              next unless name
+
+              expected = expected_name(node.method_name, name)
+              next if expected == name
+
+              add_offense(
+                arg,
+                message: format(MSG, method: node.method_name, number: number_word(node.method_name), expected: expected)
+              )
+            end
+          end
+
+          private
+
+          # The resource name as a string, for symbol or string arguments only
+          # (skips the options hash, blocks, etc.).
+          def name_of(arg)
+            arg.value.to_s if arg.sym_type? || arg.str_type?
+          end
+
+          def expected_name(method, name)
+            method == :resources ? ActiveSupport::Inflector.pluralize(name) : ActiveSupport::Inflector.singularize(name)
+          end
+
+          def number_word(method)
+            method == :resources ? 'plural' : 'singular'
+          end
+        end
+      end
+    end
+  end
+end

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