rubocop-dev_doc 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 726cbfc87e097508ea26f7cb598c61e4f743e9979d688b340f277836899a0913
-  data.tar.gz: 221eb62a0484ac2695d0ae1c06f340192e6741118676f2b30cbd14296f3b6e8f
+  metadata.gz: f669dc6f7e91c7e3aaac4e42e680df95fc24acbf6b467e7831387866cc2dc0d4
+  data.tar.gz: 41f06d6d2b20efd95b60389aae5f6803d206ad8f844d8de9daf04d87369ebf8f
 SHA512:
-  metadata.gz: 3ea55c9934463e771ad0f465b691268d743f0598e07a758b84d8ca66b2a54af4ce290f137f64161232aab20f32ca274b762c49b66089a3ded781826be5c0d249
-  data.tar.gz: edc9a58999125d644baa1db29d9bf89a5de47f72c864ee717460053c2f5e0104670bdbbb56f4744ca7f2c44ab085d18d75a4a68b77f01952a35e82ab759af0d7
+  metadata.gz: 7cdef60287b7ef58701aab3c5e025416b2033d93c3a09d06b6addc3636daaf169010584df484ec6377caa192d74d901ee52a0abf56473490c3f4e289cf6895ba
+  data.tar.gz: 84a55b7ffaf35e17e8ee436c7f696c176659c30394fa7ed6a50a7bc46fa64ecbb2b5728a5df6547d457ba0006154e9279409b7fc2f6075f4937d0a0406a37ee6

data/config/default.yml

@@ -96,7 +96,11 @@ DevDoc/Migration/BooleanColumnNotNull:
 #     Enabled: false
 # Use AllowedMethods for skips that are by-design in your project (touch,
 # counter caches) instead of per-site disables.
-DevDoc/Migration/AvoidBypassingValidation:
+# Renamed from DevDoc/Migration/AvoidBypassingValidation in 0.9.0 — the cop was
+# never migration-specific (deliberately global, no Include); the old department
+# name misled readers into thinking app code was unguarded. Old name raises a
+# rename error via config/obsoletion.yml.
+DevDoc/Rails/AvoidBypassingValidation:
   Description: "Avoid methods that bypass validations and callbacks (`update_column`, `update_all`, `insert_all`, `touch`, etc.). Superset of Rails/SkipsModelValidations — disable that cop when enabling this one."
   Enabled: false
   AllowedMethods: []
@@ -177,9 +181,16 @@ DevDoc/Rails/EnumColumnNotNull:
   Include:
     - "app/models/**/*.rb"
 
+# Receiver detection is inclusion-based (precision-first): the cop only fires
+# when the chain visibly proves a relation (where/joins/includes/order/... or
+# a scope listed in AdditionalRelationMethods). Opaque receivers and bare
+# association reads are NOT flagged — the prior exclusion-based design
+# dogfooded at 21 offenses / 0 true positives on a mature codebase. Recover
+# recall on hot association/scope names via AdditionalRelationMethods.
 DevDoc/Rails/NoBlockPredicateOnRelation:
   Description: "Avoid block-form `count`/`reject`/`select`/`find`/`any?` on AR relations; push the predicate into SQL with `.where(...)` or a scope."
   Enabled: true
+  AdditionalRelationMethods: []
   AdditionalNonRelationMethods: []
   Exclude:
     - "spec/**/*"
@@ -504,14 +515,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 +563,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
@@ -602,8 +663,14 @@ DevDoc/View/PreferPropOverName:
   # sibling label:/placeholder: for manual removal.
   Enabled: false
   SafeAutoCorrect: false
+  # fields_creditCard and fields_dynamicGroup are structurally non-model:
+  # credit-card fields capture transient credentials that must never bind to
+  # a persisted model, and dynamic-group names are array-param structural keys
+  # with no label/placeholder to derive.
   ExemptFieldMethods:
     - fields_hidden
+    - fields_creditCard
+    - fields_dynamicGroup
   Include:
     - "app/views/**/*.jbuilder"
     - "app/views/**/*.rb"

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/{migration → rails}/avoid_bypassing_validation.rb

@@ -1,7 +1,7 @@
 module RuboCop
   module Cop
     module DevDoc
-      module Migration
+      module Rails
         # Avoid methods that bypass validations and callbacks.
         #
         # ## Rationale

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

@@ -59,7 +59,7 @@ module RuboCop
         # For **single records**, use `Model.increment_counter(:col, id)`
         # or `Model.update_counters(id, col: 1)` — both generate
         # parameterized SQL and surface typos in the column name. Neither
-        # is flagged by `DevDoc/Migration/AvoidBypassingValidation` (they
+        # is flagged by `DevDoc/Rails/AvoidBypassingValidation` (they
         # are the Rails-blessed atomic-counter primitives).
         #
         # For **bulk counter updates**, the only clean option is
@@ -67,7 +67,7 @@ module RuboCop
         # queries, slow on large tables, but free of the
         # validation-bypass smell. If the N-query cost is genuinely
         # unacceptable, `update_all("col = col + 1")` requires disabling
-        # BOTH this cop AND `DevDoc/Migration/AvoidBypassingValidation`
+        # BOTH this cop AND `DevDoc/Rails/AvoidBypassingValidation`
         # with reasons — the friction is the audit trail (locking
         # implications, idempotency on re-runs, and the like are worth
         # a second look).
@@ -95,7 +95,7 @@ module RuboCop
         # migration failing because a model changed.
         #
         # The correct backfill pattern goes through the model with
-        # `save!` — `DevDoc/Migration/AvoidBypassingValidation`
+        # `save!` — `DevDoc/Rails/AvoidBypassingValidation`
         # enforces this, and `best_practices/backend/en/02_migration.md`
         # shows the shape:
         #

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

@@ -28,11 +28,31 @@ module RuboCop
         # attributes, non-trivial Ruby logic). For those, add a
         # `# rubocop:disable` with a brief reason.
         #
+        # ## Receiver detection is precision-first (inclusion, not exclusion)
+        # The cop only fires when the receiver chain PROVES it is a relation:
+        # it must contain a relation-returning method (`where`, `joins`,
+        # `includes`, `order`, `limit`, ... — see RELATION_RETURNING_METHODS)
+        # or a project-declared scope from `AdditionalRelationMethods`.
+        # Opaque receivers (locals, ivars, method params, bare association
+        # reads like `user.posts`) are NOT flagged.
+        #
+        # This is a deliberate trade. The earlier exclusion-based design
+        # ("flag anything that isn't provably a non-relation") was dogfooded
+        # against a mature codebase and scored 21 offenses with ZERO true
+        # positives — params arrays, gem data, AST enumerators, and validators
+        # that must see unsaved in-memory records. A cop that is all noise
+        # teaches people to write disables, which is worse than the missed
+        # recall: a bare `user.posts.any? { }` slipping through is a perf
+        # nit; twenty reflex disables are a culture problem. Projects can
+        # recover recall selectively by listing their hot association/scope
+        # names in `AdditionalRelationMethods`.
+        #
         # ## Excluded receivers
-        # To keep false positives low, the cop skips receivers that clearly
-        # aren't AR relations: array literals (`[...]`), hash literals
-        # (`{...}`), screaming-case constants (e.g. `PRICING_PLANS`), and
-        # send-chains ending in a method known to return a non-Relation:
+        # Even within a proven relation chain, the cop skips receivers whose
+        # FINAL call is known to return a non-Relation (the collection is
+        # already materialised, so SQL push-down is no longer possible), plus
+        # obvious non-relations: array literals (`[...]`), hash literals
+        # (`{...}`), and screaming-case constants (e.g. `PRICING_PLANS`):
         # * Array-returning — `pluck`, `to_a`, `map`, `flatten`, `compact`,
         #   `uniq`, `sort`, `sort_by`, `reduce`, `inject`, `each_with_object`,
         #   `zip`, `take`, `drop`, `group_by`, `partition`, `tally`,
@@ -63,24 +83,20 @@ module RuboCop
         #   proves the element is a String.
         #
         # ## Configuration
-        # `AdditionalNonRelationMethods` (default `[]`): per-project list of
-        # method names that return non-Relation collections. Useful when a
-        # codebase has its own helper methods returning plain Arrays / Hashes
-        # (e.g. a presenter factory) — adding them here lets the cop skip
-        # send-chains ending in those methods. Example:
+        # `AdditionalRelationMethods` (default `[]`): per-project list of
+        # association/scope names the cop should treat as relation-returning.
+        # This is how a project recovers recall on its hot paths without
+        # re-opening the false-positive door. Example:
         #
         #   DevDoc/Rails/NoBlockPredicateOnRelation:
-        #     AdditionalNonRelationMethods:
-        #       - all_items
-        #       - for_account
-        #       - gst_registration_ranges
-        #
-        # NOTE: The cop cannot determine whether a local variable, instance
-        # variable, or method parameter is an AR relation or a plain
-        # collection. When the receiver is in fact a plain Array/Hash, add
-        # `# rubocop:disable DevDoc/Rails/NoBlockPredicateOnRelation` with a
-        # brief reason — the friction is intentional and ensures the choice
-        # is reviewed.
+        #     AdditionalRelationMethods:
+        #       - accessible_organization_documents
+        #       - active_subscriptions
+        #
+        # `AdditionalNonRelationMethods` (default `[]`): per-project list of
+        # method names that return non-Relation collections (e.g. a presenter
+        # factory) — a chain ENDING in one of these is skipped even when an
+        # earlier link is a relation method.
         #
         # @example
         #   # bad
@@ -108,31 +124,38 @@ module RuboCop
           # out would make the alias a zero-cost dodge.
           RESTRICT_ON_SEND = %i[count reject select filter find detect any?].freeze
 
+          # Methods returning an ActiveRecord::Relation — a chain containing one
+          # of these PROVES the receiver is a relation (inclusion-based
+          # detection; see the docstring). `merge`, `all` and `from` are
+          # deliberately absent: Hash#merge is everyday Ruby, `.all` is also
+          # the API of non-AR clients (e.g. Stripe list endpoints), and
+          # ActiveSupport adds Array#from.
+          RELATION_RETURNING_METHODS = %i[
+            where rewhere not joins left_joins left_outer_joins includes
+            preload eager_load references order reorder group having limit
+            offset distinct unscope unscoped lock readonly or
+          ].freeze
+
           # Methods whose return value is known to be a non-Relation collection
           # (Array, Hash, or Enumerator). When a `.select`/`.reject`/etc. with a
           # block is chained onto a call to one of these, the block runs over
           # the materialised collection — pushing into SQL isn't possible.
           NON_RELATION_RETURNING_METHODS = %i[
-            pluck pluck_to_hash
-            to_a to_ary
-            values keys
-            map flat_map collect collect_concat filter_map
-            flatten compact uniq sort sort_by reverse
-            reduce inject each_with_object
-            split lines chars bytes
-            zip take drop drop_while take_while
-            group_by partition tally tally_by chunk_while slice_when
-
-            slice except merge transform_values transform_keys to_h
-            compact_blank with_indifferent_access index_by index_with
-
-            each_with_index each_slice each_cons each_entry each_key each_value each_pair
-            chunk slice_before slice_after lazy with_index with_object
+            pluck pluck_to_hash to_a to_ary values keys map flat_map collect
+            collect_concat filter_map flatten compact uniq sort sort_by reverse
+            reduce inject each_with_object split lines chars bytes zip take
+            drop drop_while take_while group_by partition tally tally_by
+            chunk_while slice_when slice except merge transform_values
+            transform_keys to_h compact_blank with_indifferent_access index_by
+            index_with each_with_index each_slice each_cons each_entry each_key
+            each_value each_pair chunk slice_before slice_after lazy with_index
+            with_object
           ].freeze
 
           def on_send(node)
             return unless node.block_literal? || symbol_block_pass?(node)
             return if node.receiver.nil?
+            return unless relation_chain?(node.receiver)
             return if excluded_receiver?(node.receiver)
             return if excluded_block?(node)
 
@@ -148,55 +171,83 @@ module RuboCop
             last&.block_pass_type? && last.children.first&.sym_type?
           end
 
-          def excluded_receiver?(receiver)
-            return true if receiver.array_type? || receiver.hash_type?
-            return true if receiver.const_type? && screaming_case_const?(receiver)
-            return excluded_receiver?(receiver.children.first) if receiver.begin_type?
-            return true if receiver.send_type? && non_relation_method?(receiver.method_name)
+          # Inclusion gate: walk down the receiver chain looking for a link
+          # that PROVES this is a relation. Opaque receivers (lvars, ivars,
+          # bare association reads) never pass — that's the precision-first
+          # doctrine documented above.
+          def relation_chain?(node)
+            current = node
+            while current
+              current = unwrap_begin(current)
+              break unless current&.send_type?
+              return true if relation_method?(current.method_name)
 
+              current = current.receiver
+            end
             false
           end
 
-          # Merge built-in known-safe methods with project-specific ones from
-          # `AdditionalNonRelationMethods` in .rubocop.yml. The config knob
-          # lets each project opt-in their own domain methods (e.g. a
-          # `CashBookEntry.for_account` that returns an Array of plain Ruby
-          # presenters) without modifying this cop.
-          def non_relation_method?(method_name)
-            return true if NON_RELATION_RETURNING_METHODS.include?(method_name)
+          # A paren group's value is its LAST child (`(a; b).select { }` runs
+          # the block on `b`), so unwrap to that — `children.first` would judge
+          # the discarded statement.
+          def unwrap_begin(node)
+            node = node.children.last while node&.begin_type?
+            node
+          end
+
+          def relation_method?(method_name)
+            RELATION_RETURNING_METHODS.include?(method_name) ||
+              configured_methods('AdditionalRelationMethods').include?(method_name)
+          end
+
+          # Even inside a proven relation chain, skip when the FINAL call
+          # materialises the collection (`where(...).pluck(:id)`,
+          # `where(...).to_a`, ...): the block then runs over an in-memory
+          # collection and SQL push-down is no longer possible.
+          def excluded_receiver?(receiver)
+            receiver = unwrap_begin(receiver)
+            receiver&.send_type? && non_relation_method?(receiver.method_name)
+          end
 
-            additional = cop_config['AdditionalNonRelationMethods'] || []
-            additional.map(&:to_sym).include?(method_name)
+          # Built-in known-safe methods plus project-specific ones from
+          # `AdditionalNonRelationMethods` (e.g. a `CashBookEntry.for_account`
+          # returning an Array of plain Ruby presenters).
+          def non_relation_method?(method_name)
+            NON_RELATION_RETURNING_METHODS.include?(method_name) ||
+              configured_methods('AdditionalNonRelationMethods').include?(method_name)
           end
 
-          def screaming_case_const?(const_node)
-            const_node.short_name.to_s.match?(/\A[A-Z][A-Z0-9_]*\z/)
+          def configured_methods(key)
+            (cop_config[key] || []).map(&:to_sym)
           end
 
           # Look at the block parameters and body for evidence that the
-          # iterated element can't be an ActiveRecord record.
+          # iterated element can't be an ActiveRecord record. 2+ arg
+          # destructuring means the iterator yields a pair/tuple (Hash#each,
+          # zip, etc.) — AR relations only yield single records; for a
+          # single-arg block, inspect how the arg is used inside the body.
           def excluded_block?(send_node)
             block_node = send_node.block_node
-            return false unless block_node
-
-            args = block_node.arguments
-            return false unless args
+            return false unless block_node.respond_to?(:arguments)
+            return true if pair_destructuring_block?(block_node)
 
-            # 2+ arg destructuring means the iterator yields a pair/tuple
-            # (Hash#each, zip, etc.). AR relations only yield single records.
-            return true if args.children.length >= 2
+            # `to_a` normalises across node kinds: a block's ArgsNode yields its
+            # children; a numblock's `arguments` is already a plain (empty) Array.
+            args = block_node.arguments.to_a
+            arg_name = args.length == 1 ? block_arg_name(args.first) : nil
+            return false unless arg_name && block_node.body
 
-            # Single-arg block: inspect how the arg is used inside the body.
-            return false unless args.children.length == 1
-
-            arg_node = args.children.first
-            arg_name = block_arg_name(arg_node)
-            return false unless arg_name
+            block_arg_indicates_non_record?(block_node.body, arg_name)
+          end
 
-            body = block_node.body
-            return false unless body
+          # 2+ block params — literal `|k, v|` or numbered (`_2` yields arity 2
+          # as an Integer child, there is no ArgsNode) — mean the iterator
+          # yields a pair/tuple (Hash#each, zip, ...); AR relations yield
+          # single records.
+          def pair_destructuring_block?(block_node)
+            return block_node.children[1] >= 2 if block_node.numblock_type?
 
-            block_arg_indicates_non_record?(body, arg_name)
+            block_node.arguments.to_a.length >= 2
           end
 
           # Extract the simple name of a block argument, regardless of whether
@@ -214,18 +265,22 @@ module RuboCop
           #   * Single-character string-literal indexing — `arg[0] == '+'` —
           #     implies String
           def block_arg_indicates_non_record?(body, arg_name)
-            body.each_descendant(:send) do |send|
-              next unless send.method_name == :[]
-              next unless send.receiver&.lvar_type?
-              next unless send.receiver.children.first == arg_name
-              next unless send.arguments.length == 1
-
-              key = send.first_argument
-              return true if key.sym_type?
-              return true if key.int_type? && compared_to_single_char_string?(send)
+            body.each_descendant(:send).any? do |send|
+              indexes_block_arg?(send, arg_name) && non_record_key?(send)
             end
+          end
 
-            false
+          # `arg[...]` with exactly one index argument, on the named block arg.
+          def indexes_block_arg?(send, arg_name)
+            send.method_name == :[] &&
+              send.receiver&.lvar_type? &&
+              send.receiver.children.first == arg_name &&
+              send.arguments.length == 1
+          end
+
+          def non_record_key?(send)
+            key = send.first_argument
+            key.sym_type? || (key.int_type? && compared_to_single_char_string?(send))
           end
 
           # `arg[0] == '+'` — the [] send is one side of a `==` or `!=`

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