rubocop-dev_doc 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 726cbfc87e097508ea26f7cb598c61e4f743e9979d688b340f277836899a0913
-  data.tar.gz: 221eb62a0484ac2695d0ae1c06f340192e6741118676f2b30cbd14296f3b6e8f
+  metadata.gz: d919e99af15a6422fabc24cd8cd5697d45777275150060f5df47fd20be56f386
+  data.tar.gz: 4998be254bdb93920dfa694ab035a588bb5b44f768fa9f1867814c7e88feed19
 SHA512:
-  metadata.gz: 3ea55c9934463e771ad0f465b691268d743f0598e07a758b84d8ca66b2a54af4ce290f137f64161232aab20f32ca274b762c49b66089a3ded781826be5c0d249
-  data.tar.gz: edc9a58999125d644baa1db29d9bf89a5de47f72c864ee717460053c2f5e0104670bdbbb56f4744ca7f2c44ab085d18d75a4a68b77f01952a35e82ab759af0d7
+  metadata.gz: 13dcfa0d80c10d12254a6fba6ddcbc05ec075650184739ff705ced68fc59a0743bdef285e8f990fb44bd027cc84c97db392b5fee3ba54e4b48ededd0d2c8711f
+  data.tar.gz: b8bf463155762956e6c2ed5619554f2a84a70765c9619a94fb06d3190f056d29c8230bbff1f11e4ccca8560cab3765106f9f1b4f7abe9da68a9760e1e7f236bc

data/config/default.yml

@@ -504,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
@@ -524,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/style/prefer_public_send.rb

@@ -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.9.0".freeze
+    VERSION = "0.10.0".freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - dev-doc contributors
@@ -132,7 +132,6 @@ files:
 - 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
@@ -146,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