rubocop-dev_doc 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d3924b0184e741e19b3f29854b6f472a9bd54667ddfef1e59ccc1aa000e5073
-  data.tar.gz: d59338919f825edec8ed8bbc717d26f19782fbc88411d90e1a8e0c110d07235d
+  metadata.gz: 726cbfc87e097508ea26f7cb598c61e4f743e9979d688b340f277836899a0913
+  data.tar.gz: 221eb62a0484ac2695d0ae1c06f340192e6741118676f2b30cbd14296f3b6e8f
 SHA512:
-  metadata.gz: 606dad217da6a65ddc8eb66040f2f8747be5fed37aa27764f2ae74a2fa2266158e848d780b2ee10a7d690f20832b0c36b3a5b3b16d766c433c99088226b78c8e
-  data.tar.gz: 49cac436e0dfef59326c94b89187c5d6001578972d0faa76f2fca683cfd93b9dc1e5866093351884a49e0ad58cb0f6f768a4711275f57e6bf85d24efc913137f
+  metadata.gz: 3ea55c9934463e771ad0f465b691268d743f0598e07a758b84d8ca66b2a54af4ce290f137f64161232aab20f32ca274b762c49b66089a3ded781826be5c0d249
+  data.tar.gz: edc9a58999125d644baa1db29d9bf89a5de47f72c864ee717460053c2f5e0104670bdbbb56f4744ca7f2c44ab085d18d75a4a68b77f01952a35e82ab759af0d7

data/config/default.yml

@@ -195,8 +195,8 @@ DevDoc/Style/NoUnscopedMethodDefinitions:
   # included by default.
   SafeDSLReceivers: []
 
-DevDoc/Style/AvoidSend:
-  Description: "Avoid `send`/`public_send` with an explicit receiver; prefer direct calls or safer alternatives."
+DevDoc/Style/AvoidInsecureSend:
+  Description: "Avoid insecure dynamic `send`/`public_send` — `send` is always flagged; `public_send` requires a prefix or trusted source (validator/mailer)."
   Enabled: true
 
 DevDoc/Style/PreferPublicSend:
@@ -388,9 +388,22 @@ Rails/StrongParametersExpect:
 # Narrower replacement for Rails/StrongParametersExpect — flags only the
 # hash-form rewrite (`params.require(:foo).permit(...)` → `params.expect(foo: [...])`).
 # Does not flag scalar `params[:foo]` in any context.
+#
+# SafeAutoCorrect is false because `expect` is NOT drop-in for require+permit
+# (verified against a production suite; see the cop docs for full detail):
+# 1. `expect` raises ParameterMissing (400) when the key is present but every
+#    value filters out — permit returned an empty slice and callers often rely
+#    on that ("slice-style" param methods probed on every request).
+# 2. `expect` uses explicit_arrays: collection-valued nested attributes
+#    (numeric-keyed fields_for hashes) need the double-array `[[...]]`
+#    declaration; the flat `[...]` this autocorrect emits SILENTLY filters
+#    collections to empty. Audit every *_attributes key after correcting:
+#    has_many nests need `[[...]]`, has_one nests stay flat.
+# Run with `-A` only alongside a test suite that exercises the forms.
 DevDoc/Rails/StrongParametersExpect:
   Description: "Use `params.expect(foo: [...])` instead of `params.require(:foo).permit(...)`."
   Enabled: true
+  SafeAutoCorrect: false
   Include:
     - "app/controllers/**/*.rb"
 
@@ -412,10 +425,32 @@ Rails/SaveBang:
   Exclude:
     - "app/controllers/**/*"
 
+# Superseded by DevDoc/Style/CaseElseDecision below: same detection, but the
+# offense message carries the raise/report/fall-through decision framework
+# instead of upstream's "Missing else statement" (which teaches the wrong
+# reflex — add an else, any else). Running both double-flags every offense.
 Style/MissingElse:
-  Enabled: true
+  Enabled: false
   EnforcedStyle: case
 
+# The point is NOT to add a silent `else` — it is to force a decision about
+# what no-branch-matching MEANS at each case. Three legitimate outcomes:
+# 1. The else genuinely happens in normal operation -> `else` + a comment
+#    stating why fall-through is correct (requires Style/EmptyElse off).
+# 2. The else indicates a bug and continuing is unsafe -> `else raise`
+#    (fail fast; unexpected enum/mode values must not proceed silently).
+# 3. The else indicates a bug but users can safely continue -> report to the
+#    error tracker and degrade gracefully (e.g. log an error, then 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 — a
+# raise on user-supplied input that executes before authorization turns
+# garbage requests into 500s, and error-tracker reports on pre-auth,
+# scanner-reachable paths become noise rather than signal.
+DevDoc/Style/CaseElseDecision:
+  Description: "Every `case` needs an `else` that decides what a non-match means: raise (unsafe to continue), report + degrade (bug but tolerable), or a comment justifying fall-through. Supersedes Style/MissingElse."
+  Enabled: true
+
 # Core default is `Max: 2`, which permits `a&.b&.c`. Tightened to `Max: 1`:
 # in `a&.b&.c`, the second `&.` is ambiguous — the reader can't tell whether
 # it's there because `b.c` can genuinely be nil on its own, or merely because
@@ -436,6 +471,12 @@ DevDoc/Test/AvoidGlibTravelFreeze:
   Include:
     - "test/**/*.rb"
     - "spec/**/*.rb"
+  # Mailer previews aren't tests: freeze_time there exists to render stable
+  # dev-tool output, glib's test helpers aren't available in preview classes,
+  # and the "frozen time masks timing bugs" rationale doesn't apply.
+  Exclude:
+    - "test/mailers/previews/**/*"
+    - "spec/mailers/previews/**/*"
 
 DevDoc/Test/RequireGlibTravelBlock:
   Description: "`glib_travel` must be called with a block — the bare anchor form leaks frozen time past the test. A bare duration argument (`glib_travel(61.seconds)`) that advances the clock is the accepted non-block form."

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_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/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/prefer_public_send.rb

@@ -21,16 +21,16 @@ module RuboCop
         #   meant a public-API call. `send` leaves it ambiguous whether
         #   private access was wanted.
         #
-        # ## Relationship to AvoidSend
-        # `DevDoc/Style/AvoidSend` flags *dynamic* dispatch (both `send` and
+        # ## Relationship to AvoidInsecureSend
+        # `DevDoc/Style/AvoidInsecureSend` flags *dynamic* dispatch (both `send` and
         # `public_send`) as risky. This cop is orthogonal: it flags `send`
-        # specifically, including the cases AvoidSend exempts (literal-symbol
+        # specifically, including the cases AvoidInsecureSend exempts (literal-symbol
         # args, prefix-string args). The friction asymmetry is intentional —
         # `send` is the deeper exception, so it costs an extra disable:
         #
-        #   obj.public_send(method_name)        # AvoidSend: 1 disable
+        #   obj.public_send(method_name)        # AvoidInsecureSend: 1 disable
         #   obj.public_send(:foo)               # clean
-        #   obj.send(method_name)               # AvoidSend + this cop: 2 disables
+        #   obj.send(method_name)               # AvoidInsecureSend + this cop: 2 disables
         #   obj.send(:foo)                      # this cop only: 1 disable
         #
         # ## When `send` IS the right choice

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.8.0".freeze
+    VERSION = "0.9.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-04 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -130,8 +130,10 @@ files:
 - lib/rubocop/cop/dev_doc/route/resource_name_number.rb
 - lib/rubocop/cop/dev_doc/route/resources_require_only.rb
 - lib/rubocop/cop/dev_doc/style/avoid_head_response.rb
+- lib/rubocop/cop/dev_doc/style/avoid_insecure_send.rb
 - lib/rubocop/cop/dev_doc/style/avoid_options_hash.rb
 - lib/rubocop/cop/dev_doc/style/avoid_send.rb
+- lib/rubocop/cop/dev_doc/style/case_else_decision.rb
 - lib/rubocop/cop/dev_doc/style/literal_operator_in_condition.rb
 - lib/rubocop/cop/dev_doc/style/literal_or_in_when_clause.rb
 - lib/rubocop/cop/dev_doc/style/minimize_variable_scope.rb