rubocop-dev_doc 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d3924b0184e741e19b3f29854b6f472a9bd54667ddfef1e59ccc1aa000e5073
-  data.tar.gz: d59338919f825edec8ed8bbc717d26f19782fbc88411d90e1a8e0c110d07235d
+  metadata.gz: d919e99af15a6422fabc24cd8cd5697d45777275150060f5df47fd20be56f386
+  data.tar.gz: 4998be254bdb93920dfa694ab035a588bb5b44f768fa9f1867814c7e88feed19
 SHA512:
-  metadata.gz: 606dad217da6a65ddc8eb66040f2f8747be5fed37aa27764f2ae74a2fa2266158e848d780b2ee10a7d690f20832b0c36b3a5b3b16d766c433c99088226b78c8e
-  data.tar.gz: 49cac436e0dfef59326c94b89187c5d6001578972d0faa76f2fca683cfd93b9dc1e5866093351884a49e0ad58cb0f6f768a4711275f57e6bf85d24efc913137f
+  metadata.gz: 13dcfa0d80c10d12254a6fba6ddcbc05ec075650184739ff705ced68fc59a0743bdef285e8f990fb44bd027cc84c97db392b5fee3ba54e4b48ededd0d2c8711f
+  data.tar.gz: b8bf463155762956e6c2ed5619554f2a84a70765c9619a94fb06d3190f056d29c8230bbff1f11e4ccca8560cab3765106f9f1b4f7abe9da68a9760e1e7f236bc

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."
@@ -463,14 +504,42 @@ DevDoc/Test/RequireGlibIntegrationBase:
   RequiredBase: Glib::IntegrationTest
   LegacyBases:
     - ActionDispatch::IntegrationTest
+  # jobs/mailers/channels are included too: only LegacyBases are flagged, so the
+  # side-effect tier (Glib::NonHttpIntegrationTest) and unit bases there are
+  # untouched — this closes the seam where a raw ActionDispatch::IntegrationTest
+  # in test/jobs/ would sidestep both the glib plumbing and every base rule.
   Include:
     - "test/controllers/**/*_test.rb"
     - "test/integration/**/*_test.rb"
+    - "test/jobs/**/*_test.rb"
+    - "test/mailers/**/*_test.rb"
+    - "test/channels/**/*_test.rb"
+
+# Previews render on every GET in development — persistence inside one mutates
+# the dev DB as a side effect of viewing an email. Also guards the preview
+# harness as a relocation target: mailer-body variants staged for snapshots
+# must set state in memory, not write it.
+DevDoc/Test/NoPersistenceInMailerPreviews:
+  Description: "Mailer previews must not persist records — previews render on GET; assign in memory, the mailer receives objects via .with(...)."
+  Enabled: true
+  AllowedMethods: []
+  Include:
+    - "test/mailers/previews/**/*.rb"
+    - "spec/mailers/previews/**/*.rb"
+    - "lib/mailer_previews/**/*.rb"
 
 DevDoc/Test/RequireUnitTestJustification:
   Description: "Every test file must live in a recognized directory; unit-test directories additionally require a justification header (marker phrase: 'deliberate exception')."
   Enabled: true
   MarkerPhrase: "deliberate exception"
+  # WiringPhrase: justified non-HTTP tests must also carry a line (matched
+  # case-insensitively, before the first class/module) accounting for the HTTP
+  # wiring their subject participates in — name the request test that covers
+  # that path, or state why no runtime HTTP path exists (naming the entry
+  # point). Writing it forces the relocating author to notice when a
+  # controller param / policy branch / rendered error is about to lose its
+  # only request-level coverage. Set to "" to disable (not recommended).
+  WiringPhrase: "wiring:"
   # Total classification — Include deliberately covers ALL test files so a test
   # can't dodge enforcement by being placed in an invented directory. Note
   # AvoidUnitTest's base-class heuristic is evadable when a project's universal
@@ -483,15 +552,37 @@ DevDoc/Test/RequireUnitTestJustification:
   #     offense — a unit test parked in an exempt directory would dodge both the
   #     header rule and the runtime lint (which only reaches integration-base
   #     descendants).
-  #   - UnitTestDirectories: allowed only with the justification header.
+  #   - UnitTestDirectories: allowed only with the justification header
+  #     (marker phrase + wiring line).
+  #   - NonHttpDirectories: the only homes for NonHttpBaseClasses — the
+  #     side-effect tier (full stack, fixtures, deliveries, but no HTTP verbs)
+  #     for jobs/mailers whose contract is a side effect, not a response.
+  #     Elsewhere that base is an evasion vector (in test/controllers/ it would
+  #     dodge the runtime HTTP lint exactly like a unit base) and is flagged.
+  #     Glib::IntegrationTest remains legal in these directories: job tests
+  #     legitimately mix HTTP assertions with side-effect assertions. A class
+  #     on the non-HTTP base, however, carries the same justification-header
+  #     contract as a unit directory — it consciously opted out of HTTP, so it
+  #     must say why and account for the wiring.
   #   - Anything else (including test/ root): flagged as unrecognized — adding a
   #     new test home is a reviewed config change, not an implicit act.
+  # RequireUnitBase: allowlist semantics in unit-test directories — a *Test
+  # class must subclass a UnitBaseClasses member; plain ActiveSupport::TestCase
+  # is rejected as an unexamined default (the confession base is structural,
+  # not optional). Set false to revert to blocklist-only (integration bases).
+  RequireUnitBase: true
   UnitBaseClasses:
     - Glib::LastResortUnitTest
+  NonHttpBaseClasses:
+    - Glib::NonHttpIntegrationTest
   UnitTestDirectories:
     - models
     - services
     - helpers
+  NonHttpDirectories:
+    - jobs
+    - mailers
+    - channels
   ExemptDirectories:
     - controllers
     - integration

data/lib/dev_doc/test/lints/http_driven_controller_tests.rb

@@ -22,20 +22,38 @@ module DevDoc
       # request" is checked per test, not per file. A unit test cannot pass it
       # by renaming, relocating within the file, or subclassing anything.
       #
-      # There is deliberately NO opt-out flag: a test that never issues a
-      # request does not belong under `test/controllers/`. Move it to the
-      # matching directory (`test/models/`, `test/jobs/`, ...) with the
-      # justification header your project's conventions require
-      # (see DevDoc/Test/RequireUnitTestJustification).
+      # There is deliberately NO opt-out flag, and the escape route is
+      # deliberately ordered: CONVERT first, relocate only as a last resort.
+      # The observed failure mode when this lint fires is relocation-verbatim —
+      # the test moves to a unit/side-effect directory unchanged, and the HTTP
+      # wiring its subject participates in (a controller param handed to a
+      # mailer, a policy branch, a rendered error) silently loses its only
+      # prospective coverage. That is why the destination header must carry a
+      # "Wiring:" line (enforced by DevDoc/Test/RequireUnitTestJustification):
+      # writing it forces the mover to go look for the request test that still
+      # covers the wiring — and to notice when there isn't one. Relocated tests
+      # must also re-base off the integration class (e.g. onto
+      # Glib::LastResortUnitTest or Glib::NonHttpIntegrationTest); the
+      # destination dirs forbid integration bases, so a test moved unchanged
+      # keeps tripping that cop.
       module HttpDrivenControllerTests
         CONTROLLER_TEST_PATH = %r{(\A|/)test/controllers/}
 
         MESSAGE = <<~MSG.freeze
           %<location>s lives under test/controllers/ but never issued an HTTP request —
-          it is a unit test in controller-test clothing. Convert it to drive the app
-          through a request (the bugs live in the wiring), or move it to the directory
-          matching what it exercises (test/models/, test/jobs/, ...) with a documented
-          justification header.
+          it is a unit test in controller-test clothing. CONVERT it first: drive the
+          same behavior through a request (the bugs live in the wiring), assuming a
+          request test IS possible and looking harder — that conclusion is almost
+          always premature (see DevDoc/Test/AvoidUnitTest for the patterns). Only if
+          conversion is genuinely impossible, RELOCATE it to the directory matching
+          what it exercises (test/models/, test/jobs/, ...) on a non-integration base
+          (e.g. Glib::LastResortUnitTest / Glib::NonHttpIntegrationTest) — never
+          verbatim: the destination header must justify the exception AND carry a
+          "Wiring:" line naming the request test that still covers the HTTP path this
+          test's subject participates in (or stating why no HTTP path exists), both
+          enforced by DevDoc/Test/RequireUnitTestJustification. Relocating assertions
+          into the mailer-preview harness only pins the mailer itself — a request test
+          must still prove the controller feeds it (params -> Mailer.with(...)).
         MSG
 
         def before_setup

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
@@ -51,7 +51,7 @@ module RuboCop
         # `send(:foo)` (no explicit receiver) calls a method on `self` and is
         # commonly used inside a class to dispatch to its own private methods.
         # Rewriting to `public_send` would either change semantics (the
-        # method must become public) or fail. Same exemption as `AvoidSend`.
+        # method must become public) or fail.
         #
         # @example
         #   # bad — prefer public_send

data/lib/rubocop/cop/dev_doc/test/justification_header.rb

@@ -0,0 +1,80 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # The justification-header contract shared by test-placement cops: a
+        # justified non-HTTP test must open with leading comments (before the
+        # first class/module) that contain the marker phrase (why a controller
+        # test can't cover this) AND a wiring line (which request test still
+        # covers the HTTP path its subject participates in — or why no runtime
+        # HTTP path exists). Host cops must provide `offense_range` and
+        # `cop_config`.
+        module JustificationHeader
+          MSG_JUSTIFY = 'Unit-test file without a justification header. Controller tests catch the ' \
+                        'wiring bugs unit tests miss, so first assume a controller test IS possible ' \
+                        'and look harder — that conclusion is almost always premature (see ' \
+                        'DevDoc/Test/AvoidUnitTest for patterns that reach "unit-only" behaviour ' \
+                        'end-to-end). If genuinely impossible, explain why in the leading comments, ' \
+                        'including the marker phrase "%<phrase>s".'.freeze
+
+          MSG_JUSTIFY_WIRING = ' The header must also carry a "%<wiring>s" line naming the request ' \
+                               'test that still covers the HTTP wiring this test bypasses (or why ' \
+                               'no runtime HTTP path exists).'.freeze
+
+          MSG_WIRING = 'Justification header lacks a "%<phrase>s" line. Every justified non-HTTP ' \
+                       'test must account for the HTTP wiring its subject participates in: name the ' \
+                       'request test that covers that path end-to-end, or state why no runtime HTTP ' \
+                       'path exists (naming the actual entry point — job, sync service, rake task). ' \
+                       'Writing this line is what catches a relocation that would silently strand a ' \
+                       'controller param, policy branch, or rendered error with no request-level ' \
+                       'coverage.'.freeze
+
+          private
+
+          # One offense at a time (same range — RuboCop dedupes): a missing
+          # header gets MSG_JUSTIFY (which names the full contract, wiring line
+          # included); MSG_WIRING fires only when the marker is present but the
+          # wiring line is not — the signature of a relocation that never asked
+          # what request-level coverage remains.
+          def check_justification
+            unless leading_comments_contain?(marker_phrase)
+              add_offense(offense_range, message: justify_message)
+              return
+            end
+            return if wiring_phrase.empty? || leading_comments_contain?(wiring_phrase)
+
+            add_offense(offense_range, message: format(MSG_WIRING, phrase: wiring_phrase))
+          end
+
+          def justify_message
+            message = format(MSG_JUSTIFY, phrase: marker_phrase)
+            return message if wiring_phrase.empty?
+
+            message + format(MSG_JUSTIFY_WIRING, wiring: wiring_phrase)
+          end
+
+          def leading_comments_contain?(phrase)
+            processed_source.comments.any? do |comment|
+              comment.location.line < first_definition_line &&
+                comment.text.downcase.include?(phrase.downcase)
+            end
+          end
+
+          # Header comments legitimately sit between the `require`s and the test
+          # class, so "leading" means before the first class/module definition.
+          def first_definition_line
+            root = processed_source.ast
+            return Float::INFINITY unless root
+
+            definition = root.each_node(:class, :module).first
+            (definition || root).first_line
+          end
+
+          def marker_phrase = cop_config.fetch('MarkerPhrase', 'deliberate exception')
+
+          def wiring_phrase = cop_config.fetch('WiringPhrase', 'wiring:').to_s
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/test/no_persistence_in_mailer_previews.rb

@@ -0,0 +1,78 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # Mailer previews must not persist records. A preview renders on every
+        # GET in development, so a `save!`/`update!`/`create!` inside one
+        # mutates the development database as a side effect of merely VIEWING
+        # an email — and re-renders keep re-writing it.
+        #
+        # ## Rationale
+        # Previews are also a relocation target: when the HTTP-driven lint
+        # pushes mailer-body assertions into preview variants (snapshot-tested
+        # via generate_preview_tests), the temptation is to persist the state
+        # the variant needs. Don't — the mailer receives its objects in memory
+        # via `.with(...)`, so in-memory assignment (`record.attr = value`)
+        # renders identically with no side effect. For sample data, use
+        # fixtures/seeded rows or unsaved `new`/`build` records.
+        #
+        # This was a real defect: a preview called
+        # `checklist.update!(note_for_assignee: ...)` to stage a note variant,
+        # silently rewriting the first published checklist's note in the dev DB
+        # on every preview view. In-memory assignment renders the same body.
+        #
+        # `AllowedMethods` exists for projects whose preview data setup
+        # genuinely must write (e.g. a sandboxed preview database) — prefer
+        # leaving it empty.
+        #
+        # @example
+        #   # bad — viewing the preview rewrites the record
+        #   def reminder_with_note
+        #     checklist.update!(note_for_assignee: 'Standing note')
+        #     ChecklistMailer.with(checklist: checklist).reminder
+        #   end
+        #
+        #   # good — same rendered body, no side effect
+        #   def reminder_with_note
+        #     checklist.note_for_assignee = 'Standing note'
+        #     ChecklistMailer.with(checklist: checklist).reminder
+        #   end
+        class NoPersistenceInMailerPreviews < Base
+          MSG = '`%<method>s` persists from a mailer preview — previews render on every GET in ' \
+                'development, so viewing the email mutates the dev DB. Assign in memory instead ' \
+                '(`record.attr = value`): the mailer receives the object via `.with(...)`, so the ' \
+                'rendered body is identical. For sample data, use fixtures/seeded rows or unsaved ' \
+                '`new`/`build` records.'.freeze
+
+          # `delete` and `insert` are deliberately absent: Hash#delete /
+          # Array#insert are everyday preview code and would false-positive;
+          # record-level intent is still covered by destroy/delete_all/insert_all.
+          PERSISTENCE_METHODS = %i[
+            save save! create create! update update! update_column update_columns
+            update_all update_attribute delete_all destroy destroy! destroy_all
+            insert! insert_all insert_all! upsert upsert_all
+            increment! decrement! toggle! touch touch_all
+            find_or_create_by find_or_create_by! create_or_find_by create_or_find_by!
+            first_or_create first_or_create!
+          ].freeze
+
+          def on_send(node)
+            method = node.method_name
+            return unless PERSISTENCE_METHODS.include?(method)
+            return if allowed_methods.include?(method.to_s)
+
+            add_offense(node.loc.selector, message: format(MSG, method: method))
+          end
+          # Safe navigation (`record&.update_column`) arrives as csend, which
+          # on_send does NOT receive — without this alias it slips through
+          # (found by red-teaming: `first&.update_column` in a real preview).
+          alias on_csend on_send
+
+          private
+
+          def allowed_methods = cop_config.fetch('AllowedMethods', [])
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/test/require_unit_test_justification.rb

@@ -1,3 +1,6 @@
+require_relative 'justification_header'
+require_relative 'test_file_placement'
+
 module RuboCop
   module Cop
     module DevDoc
@@ -15,12 +18,37 @@ module RuboCop
         #    in an exempt directory means a unit test is parked where the
         #    justification-header rule (and, for test/controllers/, the runtime
         #    HTTP lint — which only reaches integration-base descendants) cannot
-        #    see it.
+        #    see it. The non-HTTP side-effect base (`NonHttpBaseClasses`, default
+        #    `Glib::NonHttpIntegrationTest`) is confined the same way to its own
+        #    directories (`NonHttpDirectories`, default: jobs, mailers,
+        #    channels): full-stack tests whose contract is a side effect (a job's
+        #    record mutations, a mailer's body) rather than an HTTP response.
+        #    Outside those directories it is an evasion vector — in
+        #    test/controllers/ it would dodge the runtime HTTP lint exactly like
+        #    a unit base, and in a unit directory it would launder a unit test
+        #    past the truthful-declaration rule. Inside them, a class on the
+        #    non-HTTP base carries the same justification-header contract as a
+        #    unit directory (it consciously opted out of HTTP), while classes on
+        #    the integration base stay header-free — job tests legitimately mix
+        #    HTTP assertions with side-effect assertions.
         # 2. **Unit-test directories** (`UnitTestDirectories`, default: models,
         #    services, helpers) — allowed only with a justification header: the
         #    leading comments (before the first class/module) must contain the
         #    marker phrase (default "deliberate exception") explaining why a
-        #    controller test can't cover this.
+        #    controller test can't cover this, AND a wiring line (`WiringPhrase`,
+        #    default "wiring:") naming the request test that still covers the
+        #    HTTP path this test's subject participates in — or why no runtime
+        #    HTTP path exists, naming the actual entry point. The justification
+        #    must state the concrete mechanism (who calls save!, where the data
+        #    comes from); stock phrases ("the controller merely surfaces the
+        #    model's errors") do not count, and a header that misstates the
+        #    mechanism is worse than none — verify the claim by tracing the
+        #    write path before writing it. Base classes are allowlisted here
+        #    (`RequireUnitBase`, default true): a *Test class must subclass a
+        #    `UnitBaseClasses` member — plain ActiveSupport::TestCase is
+        #    rejected as an unexamined default, so the confession base is
+        #    structural, not optional. Inline helpers/doubles (non-*Test names)
+        #    are not policed.
         # 3. **Anything else** — flagged as an unrecognized test directory.
         #    Adding a new test home is a reviewed decision made in this cop's
         #    config, not something a generated test can do implicitly.
@@ -53,6 +81,8 @@ module RuboCop
         #   # Per best practice, we focus on controller tests. This model test
         #   # is a deliberate exception: the safely_* guards raise on ANY direct
         #   # call, so by design no controller path can reach them.
+        #   # Wiring: none — the guards are dead-man switches with no runtime
+        #   # caller; member_soft_deletion_test covers the soft-delete flow.
         #   class MemberTest < Glib::LastResortUnitTest
         #
         # @example
@@ -63,14 +93,11 @@ module RuboCop
         #   # bad — test/controllers/member_test.rb inheriting Glib::LastResortUnitTest
         #
         #   # good — test/models/member_test.rb whose leading comments contain
-        #   # "deliberate exception" and explain why no controller path exists
+        #   # "deliberate exception" and a "Wiring:" line, and explain why no
+        #   # controller path exists
         class RequireUnitTestJustification < Base
-          MSG_JUSTIFY = 'Unit-test file without a justification header. Controller tests catch the ' \
-                        'wiring bugs unit tests miss, so first assume a controller test IS possible ' \
-                        'and look harder — that conclusion is almost always premature (see ' \
-                        'DevDoc/Test/AvoidUnitTest for patterns that reach "unit-only" behaviour ' \
-                        'end-to-end). If genuinely impossible, explain why in the leading comments, ' \
-                        'including the marker phrase "%<phrase>s".'.freeze
+          include JustificationHeader
+          include TestFilePlacement
 
           MSG_UNRECOGNIZED = 'Test file in unrecognized directory `test/%<dir>s/`. Unit tests hide in ' \
                              'uncategorized directories: move this file to a recognized home ' \
@@ -87,8 +114,23 @@ module RuboCop
                           'hiding from that enforcement — move it there and justify it, or write a ' \
                           'real %<dir>s test.'.freeze
 
+          MSG_UNIT_BASE_REQUIRED = '`%<base>s` is not a sanctioned unit-test base. A justified unit ' \
+                                   'test must subclass one of: %<unit_bases>s — the name is the ' \
+                                   'policy (a conscious last resort) and base-class-keyed tooling ' \
+                                   'relies on it; plain ActiveSupport::TestCase reads as an ' \
+                                   'unexamined default. Extend UnitBaseClasses in this cop\'s ' \
+                                   'config if your project has another sanctioned unit base.'.freeze
+
+          MSG_NON_HTTP_BASE = '`%<base>s` is the non-HTTP side-effect base — it belongs only in ' \
+                              '%<non_http_dirs>s. In `test/%<dir>s/` it evades that directory\'s ' \
+                              'enforcement (the runtime HTTP lint reaches only integration-base ' \
+                              'descendants; unit directories require a unit base under a ' \
+                              'justification header) — move the test, or subclass the base this ' \
+                              'directory is enforced through.'.freeze
+
           FORBIDDEN_BASES = %w[ActionDispatch::IntegrationTest Glib::IntegrationTest].freeze
           EXEMPT_DIRS = %w[controllers integration jobs mailers channels system linters tasks].freeze
+          NON_HTTP_DIRS = %w[jobs mailers channels].freeze
 
           def on_new_investigation
             return if processed_source.blank?
@@ -103,109 +145,93 @@ module RuboCop
 
           def enforce_directory_rules(dir)
             if exempt_directories.include?(dir)
-              check_unit_bases(dir)
+              check_confined_bases(dir)
+              check_justification if non_http_base_in_non_http_dir?(dir)
             elsif unit_test_directories.include?(dir)
               check_justification
               check_base_classes
+              check_confined_bases(dir)
             else
               add_offense(offense_range, message: format(MSG_UNRECOGNIZED, dir: dir, known: known_directories))
             end
           end
 
-          def check_justification
-            return if leading_comments_contain_phrase?
-
-            add_offense(offense_range, message: format(MSG_JUSTIFY, phrase: marker_phrase))
+          # Landing on the non-HTTP side-effect base is a conscious exception
+          # too (the class opted out of HTTP inside an integration-shaped
+          # home), so it carries the same header contract as a unit directory.
+          def non_http_base_in_non_http_dir?(dir)
+            non_http_directories.include?(dir) && class_with_base?(non_http_base_classes)
           end
 
-          # A justified unit test must also DECLARE itself truthfully: inheriting
-          # an integration base class hides the test type from readers and from
-          # base-class-keyed tooling (the observed AvoidUnitTest evasion).
+          # A justified unit test must also DECLARE itself truthfully. Two
+          # tiers: integration bases get the tailored lie-about-type message;
+          # any other base outside UnitBaseClasses (e.g. plain
+          # ActiveSupport::TestCase) is rejected as an unexamined default —
+          # allowlist semantics, so the confession base is structural, not
+          # optional (disable via RequireUnitBase: false). Non-HTTP bases are
+          # skipped here so check_confined_bases' specific message fires.
           def check_base_classes
-            each_class_with_base(forbidden_base_classes) do |superclass, base|
-              add_offense(superclass, message: format(MSG_BASE, base: base))
-            end
-          end
-
-          # The inverse rule for exempt directories: a unit base there means a
-          # unit test parked where neither the header rule nor the runtime HTTP
-          # lint (which only reaches integration-base descendants) can see it.
-          def check_unit_bases(dir)
-            each_class_with_base(unit_base_classes) do |superclass, base|
-              add_offense(superclass,
-                          message: format(MSG_UNIT_BASE, base: base, dir: dir, unit_dirs: unit_directories_list))
-            end
-          end
+            each_test_class do |class_node, base|
+              next if base.nil? || unit_base_classes.include?(base) || non_http_base_classes.include?(base)
 
-          def each_class_with_base(bases)
-            root = processed_source.ast
-            return unless root
-
-            root.each_node(:class) do |class_node|
-              base = class_node.parent_class&.const_name
-              yield(class_node.parent_class, base) if base && bases.include?(base)
+              message = base_offense_message(base)
+              add_offense(class_node.parent_class, message: message) if message
             end
           end
 
-          # First path segment after the (last) `test/` component; nil when the
-          # file is not under one, '.' for files directly in test/. Only
-          # `*_test.rb` files count — anything else (helpers, shared scenarios,
-          # previews) is never loaded by the test runner, so there is nothing to
-          # enforce. In-cop guard on purpose: the config Include says the same,
-          # but the cop must stay correct even when run with a forced config.
-          def test_subdirectory
-            path = processed_source.file_path.to_s
-            return nil unless File.basename(path).end_with?('_test.rb')
-
-            rest = path_after_test_root(path)
-            return nil unless rest
-
-            segments = rest.split('/')
-            segments.length == 1 ? '.' : segments.first
-          end
-
-          # Everything after the LAST `test/` root component (handles nesting
-          # like test/services/ai/x_test.rb and repos checked out under a
-          # directory that itself contains `test/`).
-          def path_after_test_root(path)
-            if (index = path.rindex('/test/'))
-              path[(index + '/test/'.length)..]
-            elsif path.start_with?('test/')
-              path.delete_prefix('test/')
+          def base_offense_message(base)
+            if forbidden_base_classes.include?(base)
+              format(MSG_BASE, base: base)
+            elsif require_unit_base?
+              format(MSG_UNIT_BASE_REQUIRED, base: base, unit_bases: unit_base_classes.join(', '))
             end
           end
 
-          def leading_comments_contain_phrase?
-            processed_source.comments.any? do |comment|
-              comment.location.line < first_definition_line &&
-                comment.text.downcase.include?(marker_phrase.downcase)
+          # Bases confined to a directory set — the unit base to unit-test
+          # directories, the non-HTTP side-effect base to NonHttpDirectories.
+          # Anywhere else, the base parks a test where the enforcement that
+          # directory relies on (header rule, runtime HTTP lint — which only
+          # reaches integration-base descendants) cannot see it.
+          def check_confined_bases(dir)
+            base_confinements.each do |bases, allowed_dirs, message|
+              next if allowed_dirs.include?(dir)
+
+              each_class_with_base(bases) do |superclass, base|
+                add_offense(superclass,
+                            message: format(message, base: base, dir: dir,
+                                                     unit_dirs: unit_directories_list,
+                                                     non_http_dirs: non_http_directories_list))
+              end
             end
           end
 
-          # Header comments legitimately sit between the `require`s and the test
-          # class, so "leading" means before the first class/module definition.
-          def first_definition_line
-            root = processed_source.ast
-            return Float::INFINITY unless root
-
-            definition = root.each_node(:class, :module).first
-            (definition || root).first_line
+          def base_confinements
+            [
+              [unit_base_classes, unit_test_directories, MSG_UNIT_BASE],
+              [non_http_base_classes, non_http_directories, MSG_NON_HTTP_BASE]
+            ]
           end
 
-          def marker_phrase = cop_config.fetch('MarkerPhrase', 'deliberate exception')
-
           def forbidden_base_classes = cop_config.fetch('ForbiddenBaseClasses', FORBIDDEN_BASES)
 
           def unit_base_classes = cop_config.fetch('UnitBaseClasses', %w[Glib::LastResortUnitTest])
 
+          def non_http_base_classes = cop_config.fetch('NonHttpBaseClasses', %w[Glib::NonHttpIntegrationTest])
+
+          def require_unit_base? = cop_config.fetch('RequireUnitBase', true)
+
           def unit_test_directories = cop_config.fetch('UnitTestDirectories', %w[models services helpers])
 
+          def non_http_directories = cop_config.fetch('NonHttpDirectories', NON_HTTP_DIRS)
+
           def exempt_directories = cop_config.fetch('ExemptDirectories', EXEMPT_DIRS)
 
           def known_directories = (exempt_directories + unit_test_directories).map { |d| "test/#{d}/" }.join(', ')
 
           def unit_directories_list = unit_test_directories.map { |d| "test/#{d}/" }.join(', ')
 
+          def non_http_directories_list = non_http_directories.map { |d| "test/#{d}/" }.join(', ')
+
           def offense_range
             range = processed_source.ast&.source_range || processed_source.comments.first&.source_range
             range.with(end_pos: range.begin_pos + [range.source_line.length, 1].max)

data/lib/rubocop/cop/dev_doc/test/test_file_placement.rb

@@ -0,0 +1,74 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # Helpers shared by test-placement cops: classifying which test/
+        # subdirectory a file belongs to, and scanning its classes for base
+        # classes that placement rules key on.
+        module TestFilePlacement
+          private
+
+          # First path segment after the (last) `test/` component; nil when the
+          # file is not under one, '.' for files directly in test/. Only
+          # `*_test.rb` files count — anything else (helpers, shared scenarios,
+          # previews) is never loaded by the test runner, so there is nothing to
+          # enforce. In-module guard on purpose: the config Include says the same,
+          # but the cop must stay correct even when run with a forced config.
+          def test_subdirectory
+            path = processed_source.file_path.to_s
+            return nil unless File.basename(path).end_with?('_test.rb')
+
+            rest = path_after_test_root(path)
+            return nil unless rest
+
+            segments = rest.split('/')
+            segments.length == 1 ? '.' : segments.first
+          end
+
+          # Everything after the LAST `test/` root component (handles nesting
+          # like test/services/ai/x_test.rb and repos checked out under a
+          # directory that itself contains `test/`).
+          def path_after_test_root(path)
+            if (index = path.rindex('/test/'))
+              path[(index + '/test/'.length)..]
+            elsif path.start_with?('test/')
+              path.delete_prefix('test/')
+            end
+          end
+
+          def each_class_with_base(bases)
+            root = processed_source.ast
+            return unless root
+
+            root.each_node(:class) do |class_node|
+              base = class_node.parent_class&.const_name
+              yield(class_node.parent_class, base) if base && bases.include?(base)
+            end
+          end
+
+          # Yields each class node whose NAME marks it as a test class
+          # (`...Test`), with its superclass const name (nil when none). Scoping
+          # to *Test names keeps inline helpers/doubles (`class FakeGateway <
+          # BaseGateway`) out of base-class enforcement.
+          def each_test_class
+            root = processed_source.ast
+            return unless root
+
+            root.each_node(:class) do |class_node|
+              name = class_node.identifier.const_name
+              next unless name&.end_with?('Test')
+
+              yield(class_node, class_node.parent_class&.const_name)
+            end
+          end
+
+          def class_with_base?(bases)
+            found = false
+            each_class_with_base(bases) { |_superclass, _base| found = true }
+            found
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.8.0".freeze
+    VERSION = "0.10.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.10.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,9 @@ 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
@@ -144,11 +145,14 @@ files:
 - lib/rubocop/cop/dev_doc/style/tap_block_ignores_value.rb
 - lib/rubocop/cop/dev_doc/test/avoid_glib_travel_freeze.rb
 - lib/rubocop/cop/dev_doc/test/avoid_unit_test.rb
+- lib/rubocop/cop/dev_doc/test/justification_header.rb
+- lib/rubocop/cop/dev_doc/test/no_persistence_in_mailer_previews.rb
 - lib/rubocop/cop/dev_doc/test/require_glib_integration_base.rb
 - lib/rubocop/cop/dev_doc/test/require_glib_travel.rb
 - lib/rubocop/cop/dev_doc/test/require_glib_travel_block.rb
 - lib/rubocop/cop/dev_doc/test/require_unit_test_justification.rb
 - lib/rubocop/cop/dev_doc/test/response_assert_equal.rb
+- lib/rubocop/cop/dev_doc/test/test_file_placement.rb
 - lib/rubocop/cop/dev_doc/view/prefer_prop_over_name.rb
 - lib/rubocop/dev_doc.rb
 - lib/rubocop/dev_doc/plugin.rb

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

@@ -1,95 +0,0 @@
-module RuboCop
-  module Cop
-    module DevDoc
-      module Style
-        # Avoid 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.
-        #
-        # **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
-        #
-        # **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.send(method_name)
-        #
-        #   ✔️ Restricted — only methods with the prefix can be called
-        #   obj.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.send(:private_helper, arg)
-        #
-        #   # good — bracket notation for model attributes
-        #   @user[attribute_name]
-        #
-        #   # good — static prefix restricts the callable methods
-        #   obj.send("export_#{method_name}")
-        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
-          # `__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?
-
-            arg = node.first_argument
-            return if arg&.sym_type?
-            return if prefixed_dynamic_method?(arg)
-
-            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
-          end
-
-          private
-
-          # A dynamic string/symbol that begins with a static prefix (e.g.
-          # `"export_#{x}"`) restricts the callable surface to methods sharing
-          # that prefix, so it is exempt. Pure interpolation (`"#{x}"`) or a
-          # trailing prefix (`"#{x}_run"`) restricts nothing and is still flagged.
-          def prefixed_dynamic_method?(arg)
-            return false unless arg&.type?(:dstr, :dsym)
-
-            first = arg.children.first
-            first&.str_type? && !first.value.empty?
-          end
-        end
-      end
-    end
-  end
-end