rubocop-dev_doc 0.7.0 → 0.9.0

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

@@ -104,7 +104,9 @@ module RuboCop
           MSG = '`%<method>s` with a block loads every row into Ruby. ' \
                 'Push the predicate into SQL with `.where(...)` or a model scope.'.freeze
 
-          RESTRICT_ON_SEND = %i[count reject select find any?].freeze
+          # filter/detect are the Ruby aliases of select/find — leaving them
+          # out would make the alias a zero-cost dodge.
+          RESTRICT_ON_SEND = %i[count reject select filter find detect any?].freeze
 
           # Methods whose return value is known to be a non-Relation collection
           # (Array, Hash, or Enumerator). When a `.select`/`.reject`/etc. with a
@@ -129,7 +131,7 @@ module RuboCop
           ].freeze
 
           def on_send(node)
-            return unless node.block_literal?
+            return unless node.block_literal? || symbol_block_pass?(node)
             return if node.receiver.nil?
             return if excluded_receiver?(node.receiver)
             return if excluded_block?(node)
@@ -139,6 +141,13 @@ module RuboCop
 
           private
 
+          # `reject(&:archived?)` loads every row exactly like the literal
+          # block form — one character shorter, so it must not be a dodge.
+          def symbol_block_pass?(node)
+            last = node.last_argument
+            last&.block_pass_type? && last.children.first&.sym_type?
+          end
+
           def excluded_receiver?(receiver)
             return true if receiver.array_type? || receiver.hash_type?
             return true if receiver.const_type? && screaming_case_const?(receiver)

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

@@ -55,7 +55,10 @@ module RuboCop
         class NoDeliverLaterInTransaction < Base
           MSG = '`%<method>s` inside a `transaction` block may use stale data. Move it outside the transaction.'.freeze
 
-          CORE_METHODS = %i[deliver_later perform_later].freeze
+          # Also the bang form, the bulk API, and the enqueue primitive that
+          # perform_later wraps — each is an equally easy spelling of the same
+          # premature enqueue.
+          CORE_METHODS = %i[deliver_later deliver_later! perform_later perform_all_later enqueue].freeze
 
           def on_send(node)
             return unless inside_transaction?(node)
@@ -74,9 +77,11 @@ module RuboCop
             cop_config.fetch('KnownAsyncWrappers', [])
           end
 
+          # with_lock opens a transaction too (lock! inside a transaction
+          # block), so an enqueue inside it has the identical hazard.
           def inside_transaction?(node)
             node.each_ancestor(:block).any? do |ancestor|
-              ancestor.method_name == :transaction
+              %i[transaction with_lock].include?(ancestor.method_name)
             end
           end
         end

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

@@ -47,12 +47,16 @@ module RuboCop
         #     OrderJob.perform_later(self)
         #   end
         class NoPerformLaterInModel < Base
-          MSG = 'Avoid `perform_later` in model files. Call it from the controller, ' \
-                'or use an explicit method name to signal the side effect.'.freeze
-          RESTRICT_ON_SEND = %i[perform_later].freeze
+          MSG = 'Avoid `%<method>s` in model files — it enqueues an ActiveJob (mailer deliveries ' \
+                'included), with the same transaction/stale-data hazard as `perform_later`. Call it ' \
+                'from the controller, or use an explicit method name to signal the side effect.'.freeze
+          # deliver_later is ActiveJob under the hood (MailDeliveryJob) and
+          # enqueue is the primitive perform_later wraps — omitting either
+          # would leave an everyday spelling of the same async enqueue.
+          RESTRICT_ON_SEND = %i[perform_later perform_all_later deliver_later deliver_later! enqueue].freeze
 
           def on_send(node)
-            add_offense(node.loc.selector)
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
           end
         end
       end

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

@@ -38,6 +38,31 @@ module RuboCop
         # Scalar `params[:foo]` in any context — leave that to per-project
         # decision or the upstream cop.
         #
+        # ## Autocorrect is UNSAFE (SafeAutoCorrect: false)
+        # `expect` is not a drop-in for require+permit; both deltas below were
+        # verified against a production suite (81 test failures before manual
+        # fix-ups):
+        #
+        # 1. **Empty-slice 400**: `expect` raises ParameterMissing when the key
+        #    is present but every value filters out — `permit` returned an
+        #    empty slice and proceeded. Bites "slice-style" param methods that
+        #    probe for whichever keys arrived (e.g. a publishing_params called
+        #    unconditionally in update). Keep those tolerant with
+        #    `params.fetch(:key, {}).permit(...)` + an inline reason.
+        # 2. **Silent collection loss**: `expect` filters with explicit_arrays,
+        #    so collection-valued nested attributes (numeric-keyed fields_for /
+        #    dynamic-group hashes, `{"0"=>{...}}`) require the double-array
+        #    `[[...]]` declaration. The flat `[...]` this autocorrect emits
+        #    SILENTLY filters such collections to empty — no error, no data.
+        #    After correcting, audit every *_attributes key: has_many nests
+        #    need `[[...]]`, has_one nests stay flat.
+        #
+        # The corrector also deliberately skips permit calls whose arguments
+        # are computed (e.g. `permit([...static...] + extra)`): copying the
+        # expression into `expect(key: [<expr>])` would produce a one-element
+        # outer array — which IS expect's array-of-hashes syntax, silently
+        # changing semantics. Those sites are flagged without a correction.
+        #
         # @example
         #   # bad
         #   params.require(:user).permit(:name, :email)
@@ -57,9 +82,9 @@ module RuboCop
           extend AutoCorrector
 
           MSG_REQUIRE_PERMIT = 'Use `params.expect(%<key>s: [...])` instead of ' \
-                               '`params.require(:%<key>s).permit(...)`.'
+                               '`params.require(:%<key>s).permit(...)`.'.freeze
           MSG_PERMIT_REQUIRE = 'Use `params.expect(%<key>s: ...)` instead of ' \
-                               '`params.permit(%<key>s: ...).require(:%<key>s)`.'
+                               '`params.permit(%<key>s: ...).require(:%<key>s)`.'.freeze
 
           RESTRICT_ON_SEND = %i[permit require].freeze
 
@@ -73,25 +98,33 @@ module RuboCop
           # 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?
+            return unless chained_call?(require_node, :require) && params_receiver?(require_node.receiver)
+            return unless single_sym_arg?(require_node)
 
             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)
+              autocorrect_require_permit(corrector, permit_node, require_node, key)
             end
           end
 
+          # Computed args (`permit([...] + extra)`, `permit(some_method)`) must
+          # not be source-copied into the expect array: a single computed-array
+          # element becomes `expect(key: [expr])` — expect's array-of-hashes
+          # syntax — silently changing semantics. Flag without correcting.
+          def autocorrect_require_permit(corrector, permit_node, require_node, key)
+            return unless literal_permit_args?(permit_node)
+
+            corrector.replace(
+              permit_node,
+              build_require_permit_replacement(require_node.receiver, key, permit_node.arguments)
+            )
+          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?
+            return unless chained_call?(permit_node, :permit) && params_receiver?(permit_node.receiver)
+            return unless single_sym_arg?(require_node)
 
             key = require_node.first_argument.value
             pair = permit_hash_pair_for_key(permit_node, key)
@@ -103,6 +136,23 @@ module RuboCop
             end
           end
 
+          def chained_call?(node, method_name)
+            node&.send_type? && node.method_name == method_name
+          end
+
+          def single_sym_arg?(node)
+            node.arguments.one? && node.first_argument.sym_type?
+          end
+
+          # Source-copying is only safe for literal permit arguments; any
+          # computed expression (method call, `+`, splat, const) changes
+          # meaning inside `expect`'s array literal.
+          def literal_permit_args?(permit_node)
+            permit_node.arguments.all? do |arg|
+              arg.sym_type? || arg.str_type? || arg.hash_type? || arg.array_type?
+            end
+          end
+
           def params_receiver?(node)
             node&.send_type? && node.method_name == :params && node.receiver.nil?
           end

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

@@ -60,7 +60,9 @@ module RuboCop
           ].freeze
 
           def on_send(node)
-            return unless node.receiver.nil?
+            # `self.head(...)` is the same controller call — a bare receiver
+            # check would make explicit-self a one-token dodge.
+            return unless node.receiver.nil? || node.receiver.self_type?
 
             status_node = node.arguments.first
             return unless status_node

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

@@ -0,0 +1,159 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Avoid insecure dynamic `send` and `public_send` with an explicit receiver.
+        #
+        # ## Rationale
+        # `send()` can call *any* method, including destructive ones like
+        # `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.
+        #
+        # `public_send` respects method visibility, but still allows calling
+        # any public method. When the method name is dynamic, a prefix restricts
+        # the callable surface to methods sharing that prefix.
+        #
+        # ## Rules
+        #
+        # **`send()` with a dynamic argument is always flagged.** There is no
+        # safe use case for dynamic `send` — use `public_send` instead, and
+        # disable with a justification when bypassing visibility is intentional.
+        #
+        # **`public_send()` with a dynamic argument is allowed when:**
+        # - The argument is a **literal symbol or string** (method name is fixed at code-write time).
+        # - The call uses a **prefix pattern** (`"prefix_#{method_name}"`) that restricts callable methods.
+        # - The call is in a **validator** file (`app/validators/`) — method names come from model DSL, not user input.
+        # - The call is a **mailer dispatch** — method names are trusted internal symbols.
+        #
+        # **`public_send()` with a dynamic argument is flagged when:**
+        # - The argument is an unrestricted variable or interpolation with no static prefix.
+        #
+        # ## Safer alternatives
+        #
+        # **a) For model attributes — use bracket notation instead.**
+        # `@model[column_name]` only accesses database columns, so it cannot
+        # accidentally invoke methods like `destroy`.
+        #
+        #   ❌ Dangerous — method_name could be :destroy or any other method
+        #   @user.send(method_name)
+        #
+        #   ✔️ Safe — only accesses database columns
+        #   @user[method_name]
+        #
+        # **b) For non-model objects — use a prefix to restrict callable methods.**
+        # By interpolating the dynamic part into a fixed prefix, only methods
+        # with that prefix (e.g. `export_csv`, `export_pdf`) can be invoked,
+        # preventing accidental calls to unintended methods.
+        #
+        #   ❌ Unrestricted — any method can be called
+        #   obj.public_send(method_name)
+        #
+        #   ✔️ Restricted — only methods with the prefix can be called
+        #   obj.public_send("export_#{method_name}")
+        #
+        # NOTE: A prefix narrows the callable surface but does not eliminate it —
+        # an attacker-controlled suffix can still reach any method sharing the
+        # prefix (e.g. `"export_#{x}"` could hit `export_and_destroy`). Use the
+        # narrowest prefix that fits, and prefer an explicit whitelist when the
+        # set of targets is small.
+        #
+        # @example
+        #   # bad — dynamic method name from a variable
+        #   @user.send(method_name)
+        #   obj.public_send(action)
+        #
+        #   # bad — interpolation with no static prefix restricts nothing
+        #   obj.send("#{x}")
+        #   obj.send("#{x}_run")
+        #
+        #   # good — literal symbol: method name is statically visible
+        #   instance.public_send(:email)
+        #
+        #   # good — bracket notation for model attributes
+        #   @user[attribute_name]
+        #
+        #   # good — static prefix restricts the callable methods
+        #   obj.public_send("export_#{method_name}")
+        #
+        #   # good — validator pattern (trusted source)
+        #   record.public_send(attribute)
+        #
+        #   # good — mailer dispatch (trusted source)
+        #   mailer.public_send(action)
+        class AvoidInsecureSend < Base
+          MSG_SEND = "Avoid dynamic `send` — use `public_send` instead, or " \
+                     "bracket notation for model attributes. Disable with a " \
+                     "justification when bypassing visibility is intentional.".freeze
+
+          MSG_PUBLIC_SEND = "Avoid unrestricted dynamic `public_send` — use a " \
+                            "prefix (`obj.public_send(\"export_\#{x}\")`) to " \
+                            "restrict callable methods, or bracket notation for " \
+                            "model attributes.".freeze
+
+          # `__send__` is the canonical alias — omitting it would leave a
+          # zero-cost dodge for the exact dynamic dispatch this cop restricts.
+          RESTRICT_ON_SEND = %i[send public_send __send__].freeze
+
+          def on_send(node)
+            return if node.receiver.nil?
+            return if literal_argument?(node)
+            return if prefixed_dynamic_method?(node)
+
+            check_send(node)
+          end
+
+          private
+
+          def literal_argument?(node)
+            node.first_argument&.sym_type?
+          end
+
+          def prefixed_dynamic_method?(node)
+            arg = node.first_argument
+            return false unless arg&.type?(:dstr, :dsym)
+
+            first = arg.children.first
+            first&.str_type? && !first.value.empty?
+          end
+
+          def check_send(node)
+            if node.method?(:send) || node.method?(:__send__)
+              add_offense(node.loc.selector, message: MSG_SEND)
+            else
+              check_public_send(node)
+            end
+          end
+
+          def check_public_send(node)
+            return if validator_file?
+            return if mailer_dispatch?(node)
+
+            add_offense(node.loc.selector, message: MSG_PUBLIC_SEND)
+          end
+
+          # Validator files are exempt — method names come from model DSL
+          # (developer-controlled), not user input.
+          def validator_file?
+            processed_source.file_path.to_s.include?('app/validators/')
+          end
+
+          # Mailer dispatch is exempt — method names are trusted internal symbols
+          # (constructor args, method params), not user input.
+          #
+          # Heuristic: the receiver is a mailer class or a parameterized mailer,
+          # and the method is a mailer action (not a private helper).
+          def mailer_dispatch?(node)
+            receiver = node.receiver
+            return false unless receiver
+
+            receiver_source = receiver.source
+            receiver_source.match?(/Mailer\b/) ||
+              receiver_source.match?(/\.with\(/) ||
+              receiver_source.match?(/parameterized_mailer/)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -62,7 +62,9 @@ module RuboCop
         class AvoidSend < Base
           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
+          # `__send__` is the canonical alias — omitting it would leave a
+          # zero-cost dodge for the exact dynamic dispatch this cop restricts.
+          RESTRICT_ON_SEND = %i[send public_send __send__].freeze
 
           def on_send(node)
             return if node.receiver.nil?

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

@@ -0,0 +1,87 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Every `case` must carry an `else` that DECIDES what a non-matching
+        # value means — this cop supersedes `Style/MissingElse`
+        # (EnforcedStyle: case), whose "Missing `else` statement" message
+        # teaches the wrong reflex: add an else, any else.
+        #
+        # ## Rationale
+        # A `case` without `else` makes "exhaustive dispatch" and "deliberate
+        # partial match" indistinguishable — an unanticipated value silently
+        # evaluates to nil. The fix is not a bare `else`; it is a decision.
+        # Three legitimate outcomes:
+        #
+        # 1. **Fall-through genuinely happens in normal operation** — add
+        #    `else` with a comment stating WHY it is correct (requires
+        #    `Style/EmptyElse` to be disabled).
+        # 2. **A non-match is a bug and continuing is unsafe** — `else raise`
+        #    (fail fast; unexpected enum/mode values must not proceed).
+        # 3. **A non-match is a bug but users can safely continue** — report
+        #    to the error tracker, then degrade gracefully (return the neutral
+        #    value). Prefer this over raising in user-facing render paths.
+        #
+        # Never pick 1 by reflex: if you cannot write down why the else
+        # legitimately happens, it belongs in bucket 2 or 3. Also weigh WHERE
+        # the case runs: raising on user-supplied input that executes before
+        # authorization turns garbage requests into 500s, and error-tracker
+        # reports on pre-auth, scanner-reachable paths are noise, not signal.
+        #
+        # ## Interaction with Style/MissingElse
+        # Same detection surface (case statements and `case/in` pattern
+        # matches; `if` is exempt) — running both double-flags every offense.
+        # Disable `Style/MissingElse` when enabling this cop:
+        #
+        #   Style/MissingElse:
+        #     Enabled: false
+        #
+        # @example
+        #   # bad — a value nobody anticipated silently becomes nil
+        #   case status
+        #   when :active then process
+        #   when :archived then skip
+        #   end
+        #
+        #   # good — closed set: fail fast
+        #   case status
+        #   when :active then process
+        #   when :archived then skip
+        #   else
+        #     raise "Unexpected status: #{status}"
+        #   end
+        #
+        #   # good — bug, but users can continue: report and degrade
+        #   case status
+        #   when :active then process
+        #   when :archived then skip
+        #   else
+        #     ErrorTracker.error("Unexpected status: #{status}")
+        #     nil
+        #   end
+        #
+        #   # good — legitimate fall-through, reason stated
+        #   case action_name.to_sym
+        #   when :new, :create then load_import
+        #   else
+        #     # No resource setup needed for the remaining actions.
+        #   end
+        class CaseElseDecision < Base
+          MSG = '`case` has no `else` — decide what a non-match means: ' \
+                '`raise` if continuing is unsafe (closed set); report to the ' \
+                'error tracker and degrade gracefully if users can continue; ' \
+                'or `else` + a comment stating why fall-through is ' \
+                'legitimate. Never add a bare `else` by reflex.'.freeze
+
+          def on_case(node)
+            add_offense(node.loc.keyword) unless node.else?
+          end
+
+          def on_case_match(node)
+            add_offense(node.loc.keyword) unless node.else?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag `||` between literals in a boolean condition (`if`, `unless`,
+        # `while`, `until`, and ternary). The operator folds to one operand
+        # immediately (`:a || :b` is just `:a`), so the condition is constant —
+        # the branch (or loop body) always runs the same way, and the other
+        # literal is dead.
+        #
+        # ## Rationale
+        # `if :billing || :payments` reads like "either is truthy" but compiles
+        # to `if :billing` — always truthy. The author almost certainly meant a
+        # real comparison (`==`) or a variable, not two literal alternatives.
+        # Unlike `DevDoc/Style/LiteralOrInWhenClause`, a condition has no
+        # comma-form alternative, so the right fix depends on intent and is NOT
+        # autocorrected — the cop only flags.
+        #
+        # Scoped to `||` only: core `Lint/LiteralAsCondition` already catches
+        # literal `&&` chains and single literals, but misses `||` chains and
+        # ternaries — this cop fills exactly that gap with no overlap.
+        #
+        #   ❌ always truthy — :payments is dead
+        #   if :billing || :payments
+        #     charge
+        #   end
+        #
+        #   ✔️ a real comparison
+        #   if status == :billing || status == :payments
+        #     charge
+        #   end
+        #
+        # @example
+        #   # bad
+        #   x = (:a || :b) ? one : two
+        #
+        #   # good
+        #   x = (val == :a || val == :b) ? one : two
+        class LiteralOperatorInCondition < Base
+          MSG = '`%<source>s` always evaluates to `%<result>s`, so this condition is constant.'.freeze
+
+          LITERAL_TYPES = %i[sym str int float true false nil].freeze
+          FALSY_TYPES = %i[false nil].freeze
+
+          # `unless` desugars to `if` and the ternary `? :` is an `if` node, so a
+          # single on_if covers both (plus modifier forms). `until` mirrors
+          # `while` — both expose `condition`.
+          def on_if(node)
+            check(node.condition)
+          end
+
+          def on_while(node)
+            check(node.condition)
+          end
+
+          alias on_until on_while
+
+          private
+
+          def check(condition)
+            inner = unwrap_begin(condition)
+            return unless inner.or_type?
+
+            leaves = flatten_chain(inner)
+            return unless leaves.all? { |leaf| LITERAL_TYPES.include?(leaf.type) }
+
+            add_offense(
+              inner,
+              message: format(MSG, source: inner.source, result: fold(leaves).source)
+            )
+          end
+
+          # The helpers below parallel DevDoc/Style/LiteralOrInWhenClause
+          # (`||`-only here). Lift them into a shared module if a third consumer
+          # appears; duplicated for now to keep that cop untouched.
+
+          # Parentheses wrap a condition in a `begin` node; unwrap it.
+          def unwrap_begin(node)
+            node = node.children.first while node.begin_type?
+            node
+          end
+
+          # Flatten a homogeneous `||` chain into its operand nodes. An operand
+          # wrapped in parentheses arrives as a `begin` node (`(:a || :b) || :c`),
+          # so unwrap before recursing; otherwise the inner chain reads as a
+          # single non-literal leaf and slips past the all-literal check.
+          def flatten_chain(node)
+            node = unwrap_begin(node)
+            return [node] unless node.or_type?
+
+            flatten_chain(node.lhs) + flatten_chain(node.rhs)
+          end
+
+          # The first truthy literal the `||` chain folds to (or its last
+          # operand when the whole chain is nil/false).
+          def fold(leaves)
+            leaves.find { |leaf| !FALSY_TYPES.include?(leaf.type) } || leaves.last
+          end
+        end
+      end
+    end
+  end
+end