rubocop-dev_doc 0.17.0 → 0.18.0

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

@@ -7,8 +7,28 @@ module RuboCop
         # ## Rationale
         # Avoid bypassing validation unless absolutely necessary. Methods like
         # `update_column`, `update_all`, `insert_all`, `upsert_all`, `delete_all`,
-        # and `save(validate: false)` skip validations and callbacks, which hides
-        # data integrity issues rather than surfacing them.
+        # and the `validate: false` option on `save`/`save!`/`create`/`create!`
+        # skip validations and callbacks, which hides data integrity issues
+        # rather than surfacing them. A validation refusal is INFORMATION: the
+        # record telling you its data is wrong — the response is to fix the
+        # data (backfill from what the ledger already knows), never to silence
+        # the gate (a real app, 2026-09-13: a `save!(validate: false)`
+        # membership write silenced the bank-account guard on legacy records;
+        # the cure was backfilling four purchases from their own transactions).
+        #
+        # ## Why bypasses are treated as hostile
+        # The guards that matter most are the ones the call site cannot see:
+        # same-account references, direction/state alignment, finalize gates.
+        # A bypassing write does not fail those guards — it never consults
+        # them, so their failure ships silently into the data (real case:
+        # a real app's `move_to`, 2026-09-12, relocated purchase items
+        # across accounts while their category references stayed behind —
+        # invisible to the suite, caught only by a manual audit).
+        #
+        # That is why the sanctioned disable protocol asks for more than a
+        # reason: name the COLUMNS being written and why record-by-record
+        # (`find_each` + `save!`) is not viable — a reviewer must be able to
+        # check the blast radius, not just the intent.
         #
         # Even in migrations, check the code to see if there is any blatant
         # reason why existing records may be invalid. If there is, fix those
@@ -16,8 +36,9 @@ module RuboCop
         #
         # ## Relationship with Rails/SkipsModelValidations
         # This cop is a strict SUPERSET of the stock `Rails/SkipsModelValidations`
-        # (it covers every method that cop flags, plus `delete_all` and
-        # `save(validate: false)`), with per-method actionable messages instead
+        # (it covers every method that cop flags, plus `delete_all` and the
+        # `validate: false` option on save/save!/create/create!), with
+        # per-method actionable messages instead
         # of a generic one. Consumer projects should enable THIS cop and disable
         # `Rails/SkipsModelValidations` — running both forces every disable
         # comment to name two cops for the same offense. Methods that skip
@@ -44,6 +65,9 @@ module RuboCop
         #   # bad
         #   user.save(validate: false)
         #
+        #   # bad — the bang adds raise-on-failure, NOT validations
+        #   user.save!(validate: false)
+        #
         #   # bad
         #   User.insert_all(rows)
         #
@@ -53,22 +77,31 @@ module RuboCop
         #     faq.save!
         #   end
         class AvoidBypassingValidation < Base
+          # The core clause shared by the message family: WHY a bypass is
+          # hostile, not just what it skips. A bypass does not fail the
+          # model's integrity guards — it never consults them.
+          GUARD_CLAUSE = 'it bypasses validations AND callbacks, so every model-level integrity guard ' \
+                         'is silently inoperative for this write'.freeze
+          PROTOCOL = 'sanctioned bypasses: disable naming the COLUMNS written and why ' \
+                     'record-by-record is not viable (see cop doc)'.freeze
+
           MESSAGES = {
-            update_column: 'Avoid `update_column`; it bypasses validations. Use `save!` instead.',
-            update_columns: 'Avoid `update_columns`; it bypasses validations. Use `save!` instead.',
-            update_attribute: 'Avoid `update_attribute`; it bypasses validations (the singular is not ' \
+            update_column: "Avoid `update_column`; #{GUARD_CLAUSE}. Use `update!` instead.",
+            update_columns: "Avoid `update_columns`; #{GUARD_CLAUSE}. Use `update!` instead.",
+            update_attribute: "Avoid `update_attribute`; #{GUARD_CLAUSE} (the singular is not " \
                               'a validating `update`). Use `update!` instead.',
-            update_all: 'Avoid `update_all`; it bypasses validations. Use `save!` in a loop instead.',
-            insert: 'Avoid `insert`; it bypasses validations. Use `create!` instead, ' \
-                    'or `# rubocop:disable` with a reason if a raw insert is intentional.',
+            update_all: "Avoid `update_all`; #{GUARD_CLAUSE} for every matched row. " \
+                        'Use `save!` in a loop instead.',
+            insert: "Avoid `insert`; #{GUARD_CLAUSE}. Use `create!` instead, " \
+                    "or #{PROTOCOL} if a raw insert is intentional.",
             insert!: 'Avoid `insert!`; it bypasses validations (the bang is about duplicate keys, ' \
                      'not validity). Use `create!` instead.',
-            insert_all: 'Avoid `insert_all`; it bypasses validations. Use `create!` in a loop, ' \
-                        'or `# rubocop:disable` with a reason if bulk-insert is intentional.',
-            upsert: 'Avoid `upsert`; it bypasses validations. Use `create!`/`update!` instead, ' \
-                    'or `# rubocop:disable` with a reason if a raw upsert is intentional.',
-            upsert_all: 'Avoid `upsert_all`; it bypasses validations. Use `create!`/`update!` in a loop, ' \
-                        'or `# rubocop:disable` with a reason if bulk-upsert is intentional.',
+            insert_all: "Avoid `insert_all`; #{GUARD_CLAUSE} for every row. Use `create!` in a loop, " \
+                        "or #{PROTOCOL} if bulk-insert is intentional.",
+            upsert: "Avoid `upsert`; #{GUARD_CLAUSE}. Use `create!`/`update!` instead, " \
+                    "or #{PROTOCOL} if a raw upsert is intentional.",
+            upsert_all: "Avoid `upsert_all`; #{GUARD_CLAUSE} for every row. Use `create!`/`update!` in a loop, " \
+                        "or #{PROTOCOL} if bulk-upsert is intentional.",
             toggle!: 'Avoid `toggle!`; it saves without validations. Use `toggle(...).save!` instead.',
             increment!: 'Avoid `increment!`; it writes without validations. Use `increment(...).save!` instead.',
             decrement!: 'Avoid `decrement!`; it writes without validations. Use `decrement(...).save!` instead.',
@@ -85,18 +118,28 @@ module RuboCop
                    '(`updated_at` updates automatically), or `AllowedMethods` if bare timestamp bumps are ' \
                    'accepted in this project.',
             touch_all: 'Avoid `touch_all`; it issues a bulk UPDATE that bypasses validations and callbacks. ' \
-                       'Iterate with `save!`, or `# rubocop:disable` with a reason if a bulk timestamp bump ' \
-                       'is intentional.',
+                       "Iterate with `save!`, or #{PROTOCOL} if a bulk timestamp bump is intentional.",
             insert_all!: 'Avoid `insert_all!`; it bypasses validations (the bang is about duplicate keys, ' \
                          'not validity). Use `create!` in a loop, or `# rubocop:disable` with a reason if ' \
                          'bulk-insert is intentional.',
             delete_all: 'Avoid `delete_all`; it bypasses callbacks. Use `destroy_all` to run callbacks, ' \
-                        'or `# rubocop:disable` with a reason if bulk-delete is intentional.'
+                        "or #{PROTOCOL} if bulk-delete is intentional."
           }.freeze
 
-          SAVE_MSG = 'Avoid `save(validate: false)`; it bypasses validations. Use `save!` instead.'.freeze
+          SAVE_MSG = 'Avoid `%<selector>s(validate: false)`; validations are the only thing it skips — if a ' \
+                     'guard refuses this save, that refusal is information: the record is telling you its ' \
+                     'data is wrong. Fix the data (backfill), not the gate.'.freeze
+
+          # save! matters as much as save: a bang only adds raise-on-failure,
+          # it does NOT restore validations — `save!(validate: false)` is the
+          # exact shape that slipped past this cop's pre-2026-09-13 `:save`-
+          # only RESTRICT_ON_SEND (a real app, purchase 29: a membership
+          # write silenced the bank-account guard on legacy data, and the
+          # suite + lint both waved it through). create/create! accept the
+          # same option with the same effect.
+          VALIDATION_GATE_METHODS = %i[save save! create create!].freeze
 
-          RESTRICT_ON_SEND = (MESSAGES.keys + %i[save]).freeze
+          RESTRICT_ON_SEND = (MESSAGES.keys + VALIDATION_GATE_METHODS).freeze
 
           # insert/insert!/upsert are AR *class-level* APIs (User.insert(...)),
           # while `insert` on a non-const receiver is everyday Array#insert —
@@ -111,10 +154,8 @@ module RuboCop
           def on_send(node)
             return if allowed_methods.include?(node.method_name.to_s)
 
-            if node.method?(:save)
-              return unless save_with_validate_false?(node)
-
-              add_offense(node.loc.selector, message: SAVE_MSG)
+            if VALIDATION_GATE_METHODS.include?(node.method_name)
+              validation_gate_offense(node)
             else
               return unless receiver_shape_matches?(node)
 
@@ -124,6 +165,17 @@ module RuboCop
 
           private
 
+          # save/save!/create/create!: only offensive WITH the skip option —
+          # the plain forms are the validating writes this cop pushes toward.
+          def validation_gate_offense(node)
+            return unless skips_validation_option?(node)
+
+            add_offense(
+              node.loc.selector,
+              message: format(SAVE_MSG, selector: node.method_name)
+            )
+          end
+
           def receiver_shape_matches?(node)
             const_receiver = node.receiver&.const_type?
             return const_receiver if CONST_RECEIVER_ONLY.include?(node.method_name)
@@ -139,7 +191,10 @@ module RuboCop
             cop_config.fetch('AllowedMethods', []).map(&:to_s)
           end
 
-          def save_with_validate_false?(node)
+          # Only a literal `validate: false` option is detected; a dynamic
+          # value (`validate: skip`) escapes this cop — deliberate trade to
+          # avoid false positives on non-AR objects.
+          def skips_validation_option?(node)
             node.arguments.any? do |arg|
               next unless arg.hash_type?
 

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

@@ -0,0 +1,177 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Controllers must not write errors onto a model (`record.errors.add`);
+        # the validity rule belongs to the model (or the form-object PORO that
+        # owns the operation's validations), whose failures the save renders
+        # through the standard model-errors channel for every caller.
+        #
+        # ## Rationale
+        # A controller-side `errors.add` is one half of a validation that
+        # lives in the wrong layer, and both halves fail the same way:
+        #
+        # - **Hand-written validations drift from the model's.** The purest
+        #   form is `record.errors.add(:title, :blank) if title.blank?` —
+        #   symbol-for-symbol what `validates :title, presence: true`
+        #   produces. The model-side rule protects every caller and every
+        #   write path; the controller-side copy guards exactly one POST, so a
+        #   later action (or a background writer) silently skips it — the
+        #   "validation asymmetry" failure: create validates, update doesn't.
+        # - **Tests follow validators.** A model validation gets exercised by
+        #   every save and gets its unhappy-path test; a controller guard
+        #   exists only where someone thought to test that one branch, so
+        #   blank-input crashes surface as 4xx/500s from users instead.
+        # - **State preconditions on an operation** ("only published articles
+        #   can be archived") are domain knowledge too. The model pattern is a
+        #   default-off flag accessor (`importing`, `archiving`) that gates a
+        #   validation to the flow that must obey it — the same shape as a
+        #   `moving` flag guarding a move operation.
+        #
+        #   ❌ Hand-written presence validation
+        #   def create
+        #     return @article.errors.add(:title, :blank) if title.blank?
+        #     @article.publish!
+        #   end
+        #
+        #   ❌ Operation precondition the controller enforces alone
+        #   unless @article.published?
+        #     @article.errors.add(:base, 'Only published articles can be archived')
+        #     return
+        #   end
+        #
+        #   ✔️ The model owns the rule; the controller assigns and calls
+        #   @article.category_id = params.dig(:article, :category_id)
+        #   @article.publish!
+        #
+        # ## Delivery is not validation (auto-exemptions)
+        # Not every `errors.add` in a controller is a misplaced rule. When the
+        # check already lives in the right layer — a model method, a policy, a
+        # service — the controller line is only DELIVERING that outcome into
+        # the model-errors channel the responder renders. Moving such a line
+        # into a validation would couple the model to a policy or smuggle an
+        # acting user into it. The cop reads the guard of the branch
+        # containing the `errors.add` (nearest enclosing `if`/`unless`,
+        # including modifier form) and auto-exempts the three observed
+        # delivery shapes:
+        #
+        # - **rescue** — the branch catches an exception (`rescue
+        #   ImportService::AlreadyImportedError`); the decision was the
+        #   raiser's.
+        # - **policy guard** — the condition consults `policy(...)`: an
+        #   authorization decision whose home is the policy layer.
+        # - **verification bang** — the condition invokes a `!`-suffixed
+        #   method (`validate_and_consume_otp!`, `send_verification_email!`):
+        #   the check lives inside that method; this branch renders its
+        #   return value.
+        #
+        # These exemptions were calibrated by triaging every hit of the raw
+        # signal (any `errors.add` in a controller) across two consuming
+        # codebases: with them, every remaining hit was a misplaced rule or a
+        # judgment call worth a reviewer's eye.
+        #
+        # ## Exception
+        # A check that LOOKS like validation but is genuinely neither a model
+        # rule nor a delivered outcome (e.g. an attempt-verification method
+        # spelled with `?` instead of `!`) — disable inline, naming where the
+        # check lives:
+        #
+        #   # rubocop:disable DevDoc/Rails/NoErrorsAddInController
+        #   # -- outcome of User#verify_code? (attempt verification, not record validity)
+        #
+        # ## Relationship with DevDoc/Rails/NoCollectionIdsWriterInController
+        # Same placement family (the model owns the write AND its guards),
+        # complementary signals: that cop catches association writers that
+        # bypass validations silently; this cop catches validity rules
+        # hand-copied into the controller where the model never sees them.
+        #
+        # NOTE: Blindness, for reviewers: a `?`-suffixed verification method
+        # in the guard is NOT exempted (over-flag on purpose — prefer a false
+        # positive to a false negative; silence with the disable above); a
+        # data rule hidden inside a policy-referencing guard IS wrongly
+        # exempted; `errors[:key] = value` and `send(:add, ...)` spellings are
+        # not detected; and a branch guarded by `case/when` gets no guard
+        # analysis (flagged — justify or restructure).
+        #
+        # @example
+        #   # bad — hand-written presence validation
+        #   return @article.errors.add(:title, :blank) if title.blank?
+        #
+        #   # bad — import-row rules belong on a form-object PORO
+        #   return @member.errors.add(:base, 'Each entry needs an email') if email.blank?
+        #
+        #   # good (auto-exempt) — delivering a policy decision
+        #   if policy(@chat).initiation_blocked_for_admin?
+        #     @chat.errors.add(:base, 'Admins cannot initiate this chat')
+        #   end
+        #
+        #   # good (auto-exempt) — delivering a verification outcome
+        #   if @user.validate_and_consume_otp!(params[:otp_attempt])
+        #     @user.enable_two_factor
+        #   else
+        #     @user.errors.add(:base, 'Invalid OTP code')
+        #   end
+        class NoErrorsAddInController < Base
+          MSG = 'Errors written onto the model from the controller — the rule belongs in a model ' \
+                'validation (or form-object PORO) whose failures the save renders for every caller. ' \
+                'If this line only delivers an outcome from elsewhere, disable with a comment naming ' \
+                'where the check lives.'.freeze
+
+          RESTRICT_ON_SEND = %i[add].freeze
+
+          # A `!`-method in a guard is the verify idiom (returns success or
+          # failure without raising). `!` itself (`:not`) must not match.
+          BANG_METHOD = /\w!\z/
+
+          def on_send(node)
+            return unless errors_receiver?(node.receiver)
+            return if delivering_outcome?(node)
+
+            add_offense(node.loc.selector)
+          end
+          # Safe navigation (`record&.errors&.add(...)`) parses as csend
+          # nodes, which on_send does not receive — alias it so `&.` is
+          # caught too.
+          alias on_csend on_send
+
+          private
+
+          # `record.errors.add(...)` on any receiver shape (ivar, local,
+          # chain); the `errors` read itself may be safe-navigated, so csend
+          # receivers count.
+          def errors_receiver?(receiver)
+            %i[send csend].include?(receiver&.type) && receiver.method_name == :errors
+          end
+
+          # The three observed delivery shapes (see the docstring): the check
+          # lives elsewhere and this line renders its outcome.
+          def delivering_outcome?(node)
+            node.each_ancestor(:resbody).any? || guarded_by_external_check?(node)
+          end
+
+          def guarded_by_external_check?(node)
+            if_node = node.each_ancestor(:if).first
+            return false unless if_node
+
+            condition = if_node.condition
+            references_policy?(condition) || invokes_bang_method?(condition)
+          end
+
+          def references_policy?(condition)
+            send_nodes(condition).any? { |send_node| send_node.method_name == :policy }
+          end
+
+          def invokes_bang_method?(condition)
+            send_nodes(condition).any? do |send_node|
+              BANG_METHOD.match?(send_node.method_name.to_s)
+            end
+          end
+
+          def send_nodes(root)
+            [root, *root.each_descendant(:send)].select(&:send_type?)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,236 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # A record finder in a controller must not be fed by a form-submitted
+        # attribute (`params[:form][:attribute]`, `params.dig(:form, :attribute)`,
+        # `params.require(:form)[:attribute]`): assign the id to the model and
+        # let its validations decide.
+        #
+        # ## Rationale
+        # A route param (`params[:id]`, `params[:post_id]`) is resource
+        # identity from the URL — a missing record means a bad URL, and the
+        # finder's `RecordNotFound` → 404 is the correct response. A
+        # form-submitted attribute is a different kind of input entirely: an
+        # unpicked select is the FIRST state a user can reach, so "blank" is an
+        # expected form state, not a bad URL. Feeding it to `find` converts
+        # "the user hasn't chosen yet" into a 404 — which JSON-UI frontends
+        # render as a generic error ("Not accessible") for every 4xx — and
+        # `find_by` trades the crash for a nil-guard + hand-written
+        # `errors.add` in the controller, which is validation living outside
+        # the model (see the controller best-practice doc: let model
+        # validations handle business rules through the normal save flow).
+        #
+        # The deeper failure mode: the lookup exists because the flow passes
+        # the resolved record as a method argument instead of assigning the
+        # foreign key to the model — and an argument cannot be validated. Under
+        # assignment, there is no line of code where a blank pick can become a
+        # 4xx: blank → nil → presence validation; foreign id → same-account
+        # validation; both render through the standard model-errors channel.
+        #
+        # Measured on the raw signal (finders whose arguments reference nested
+        # params) across two consuming codebases: every hit triaged as either
+        # this violation or a deliberate lookup carried below.
+        #
+        #   ❌ Blank pick raises RecordNotFound — a 404 for an expected form state
+        #   def create
+        #     category = current_user.categories.find(params[:article][:category_id])
+        #     @article.publish_to!(category)
+        #   end
+        #
+        #   ✔️ The controller assigns; the model validates; the responder renders
+        #   def create
+        #     @article.category_id = params.dig(:article, :category_id)
+        #     @article.publish!
+        #   end
+        #
+        # ## Exception
+        # A lookup where nil is a VALID outcome (resolve-or-create flows: no
+        # session yet → create one) is deliberate — silence it with a
+        # `%<marker>s` comment on the flagged line or the contiguous block
+        # directly above, stating why the resolution must not become an
+        # assignment + validation.
+        #
+        # ## Relationship with DevDoc/Auth/UnscopedFindJustification
+        # Different rules on adjacent shapes: that cop flags a bare CONSTANT
+        # receiver resolving a client-controlled id with no scoping (an auth
+        # reach question); this cop flags any receiver fed by a NESTED form
+        # param (a placement question). A constant-receiver form-param find
+        # can rightly trip both.
+        #
+        # NOTE: The nesting walk counts consecutive accessor hops
+        # (`[]`/`dig`/`fetch`/`require`/`expect`) above `params`. An id
+        # copied into a local first IS detected — a read of a local/instance
+        # variable whose every same-method assignment sources a nested form
+        # param (`attribute_id = params[:form][:attribute_id]`;
+        # `Model.find(attribute_id)`); op-assignments (`||=`, `&&=`, `+=`,
+        # including one sourced from a form param) count as NOT sourced, so
+        # any op-assignment of the name silences the analysis. Still not
+        # detected, for reviewers: a laundering hop BETWEEN accessors
+        # (`params[:form].presence&.dig(:attribute_id)`), a local reassigned
+        # from a safe source anywhere in the method (the cop stays silent
+        # rather than guess which assignment the finder sees), an ivar
+        # assigned in a different method (e.g. a `before_action`), and
+        # multiple-assignment spellings (`a, b = params[:form][:x], y`).
+        #
+        # @example
+        #   # bad — form-submitted attribute resolved by a finder
+        #   category = current_user.categories.find(params[:article][:category_id])
+        #   session = Chat.find_by(id: params.dig(:chat_message, :session_id))
+        #
+        #   # bad — the laundering spelling, same offense one line earlier
+        #   category_id = params.dig(:article, :category_id)
+        #   category = current_user.categories.find(category_id)
+        #
+        #   # good — route params stay finder-fed; a bad URL SHOULD 404
+        #   @article = current_user.articles.find(params[:article_id])
+        #   @comment = @article.comments.find_by(id: params[:comment_id])
+        #
+        #   # good — assignment + model validation
+        #   @article.category_id = params.dig(:article, :category_id)
+        #   @article.save
+        #
+        #   # good — deliberate resolve-or-create lookup, reason stated
+        #   # form-lookup: absent session is valid — nil means create a new one
+        #   session = Chat.find_by(id: params[:chat_message][:session_id]) || Chat.create!
+        class NoFormParamLookupInController < Base
+          include Auth::AdjacentJustification
+
+          MSG = '`%<method>s` resolves a form-submitted attribute (`params[form][attribute]`) — ' \
+                'a blank or unknown pick becomes RecordNotFound, a 404 for an expected form state, ' \
+                'and the validity check migrates into the controller. Assign the id to the model ' \
+                'and validate it there; for a deliberate lookup state why in a "%<marker>s" comment.'.freeze
+
+          # One hop above `params` may itself be nested when it names several
+          # keys: `params.dig(:form, :attribute)` is top-level spelling with
+          # nested reach. `fetch` is excluded from this rule — its second
+          # argument is a default value, not a nested key.
+          MULTI_KEY_ACCESSORS = %i[dig].freeze
+          # Chained accessors counted as hops above a bare `params`; two or
+          # more hops means the value lives under a form hash, not at the
+          # route-param top level.
+          ACCESSOR_HOPS = %i([] dig fetch require expect).freeze
+          # Variable reads/assignments tracked by the laundering analysis.
+          VARIABLE_READS = %i[lvar ivar].freeze
+          VARIABLE_ASSIGNMENTS = %i[lvasgn ivasgn].freeze
+
+          # FinderMethods is configuration-driven, so the name filter lives in
+          # on_send rather than RESTRICT_ON_SEND.
+          def on_send(node)
+            return unless finder_methods.include?(node.method_name)
+            return unless node.arguments.any? { |argument| references_form_param?(argument) }
+            return if adjacent_justification?(node)
+
+            add_offense(node.loc.selector, message: offense_message(node))
+          end
+          alias on_csend on_send
+
+          private
+
+          def offense_message(node)
+            format(MSG, method: node.method_name, marker: justification_marker)
+          end
+
+          def references_form_param?(search_root)
+            references_nested_form_param?(search_root) || laundered_form_param?(search_root)
+          end
+
+          def references_nested_form_param?(search_root)
+            search_root.each_descendant(:send) do |descendant|
+              return true if bare_params?(descendant) && nested_access?(descendant)
+            end
+            false
+          end
+
+          # The laundering spelling: the id is copied into a local/instance
+          # variable on one line and the finder is fed the variable on the
+          # next (`attribute_id = params[:form][:attribute_id]` …
+          # `Model.find(attribute_id)`). A read counts only when EVERY
+          # assignment to that name in the same method sources a nested form
+          # param — one safe reassignment anywhere makes the final value
+          # unknowable without order analysis, so the cop stays silent
+          # (under-flagging by design).
+          def laundered_form_param?(search_root)
+            method_scope = search_root.each_ancestor(:def, :defs).first
+            return false if method_scope.nil?
+
+            assignments = method_scope.each_descendant(*VARIABLE_ASSIGNMENTS).to_a
+            variable_reads(search_root).any? do |read|
+              assigned_only_from_form_params?(read.children.first, assignments)
+            end
+          end
+
+          # True when the name is assigned at least once in the method and
+          # every one of its assignments sources a nested form param. An
+          # op-assignment (`x ||= y`, `x += n`) parses as an op-asgn node
+          # wrapping a VALUELESS lvasgn/ivasgn — `children.last` is the name
+          # Symbol, not a value — and counts as NOT sourced: its rhs is a
+          # reassignment from somewhere else, which per the contract above
+          # silences the analysis (and a form-param-sourced `||=` is that
+          # same blindness, not a crash).
+          def assigned_only_from_form_params?(name, assignments)
+            name_assignments = assignments.select { |assignment| assignment.children.first == name }
+            name_assignments.any? && name_assignments.all? { |assignment| form_param_sourced?(assignment) }
+          end
+
+          def form_param_sourced?(assignment)
+            rhs = assignment.children.last
+            rhs.is_a?(RuboCop::AST::Node) && references_nested_form_param?(rhs)
+          end
+
+          def variable_reads(search_root)
+            [search_root, *search_root.each_descendant(*VARIABLE_READS)]
+          end
+
+          def bare_params?(node)
+            node.method_name == :params && node.receiver.nil?
+          end
+
+          # True when the value is reached through a form hash: two or more
+          # chained accessor hops (`params[:form][:attribute]`,
+          # `params.require(:form)[:attribute]`), or a single `dig` naming
+          # several keys.
+          def nested_access?(params_node)
+            first_hop = params_node.parent
+            return false unless accessor_call?(first_hop)
+
+            return true if multi_key_dig?(first_hop)
+
+            accessor_hops(first_hop) >= 2
+          end
+
+          def accessor_call?(node)
+            node&.send_type? && ACCESSOR_HOPS.include?(node.method_name)
+          end
+
+          # `dig` is the one accessor whose extra ARGUMENTS nest: a single
+          # `params.dig(:form, :attribute)` hop reaches as deep as
+          # `params[:form][:attribute]`.
+          def multi_key_dig?(node)
+            node.method_name == :dig && node.arguments.count >= 2
+          end
+
+          # Chained accessor calls above the given one, stopping at the first
+          # non-accessor parent.
+          def accessor_hops(node)
+            hops = 1
+            current = node.parent
+            while accessor_call?(current)
+              hops += 1
+              current = current.parent
+            end
+            hops
+          end
+
+          def finder_methods
+            @finder_methods ||= Array(cop_config.fetch('FinderMethods', %w[find find_by find_by!])).map(&:to_sym)
+          end
+
+          def justification_marker
+            cop_config.fetch('JustificationMarker', 'form-lookup:')
+          end
+        end
+      end
+    end
+  end
+end