rubocop-dev_doc 0.16.0 → 0.18.0

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

@@ -0,0 +1,162 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag block-form `find`/`detect` on an ActiveRecord association
+        # declared in the same file, and demand the fork: refactor to
+        # `find_by`, or keep the in-memory view and justify it with a
+        # disable-reason.
+        #
+        # ## Rationale
+        # `Relation#find` with a block returns straight into
+        # `Enumerable#find` over the association's loaded target —
+        # persisted rows PLUS records built in memory and not yet saved.
+        # `find_by` is `where(...).take`: a SQL query that has never seen
+        # those records — and on an unsaved owner the association's DB
+        # scope is empty outright, so `find_by` returns nil while the
+        # loaded target holds the caller's submitted selection (`build`,
+        # nested attributes, a `*_ids=` assignment on a new record). A
+        # validator refactored to `find_by` stops seeing what was
+        # submitted, and the very check it exists to make silently
+        # passes. (On a persisted owner a `*_ids=` assignment writes the
+        # join rows immediately, inside a transaction, so both spellings
+        # agree there; the block form's edge is the unsaved population.)
+        # Code whose in-memory semantics are load-bearing but unexplained
+        # is one well-meaning `find_by` refactor away from a bug its suite
+        # does not pin, so the cop's job is to force that explanation to
+        # exist.
+        #
+        # ## Exception — the justified in-memory search
+        # Where the in-memory view is required (validators over unsaved
+        # records, nested-attribute flows), keep the block form and
+        # disable this cop inline, with the reason stated at the disable:
+        # why the loaded target — not the database — is the correct thing
+        # to search here. The disable-with-reason is the sanctioned exit
+        # (the same doctrine as the sibling doctrine cops); no magic
+        # comment keyword is recognized, because a keyword can be typed
+        # without the understanding.
+        #
+        # ## Relationship with DevDoc/Rails/NoBlockPredicateOnRelation
+        # That cop fires on PROVEN relation chains (`.where(...)`,
+        # scopes) and deliberately exempts bare association reads — its
+        # dogfooding history names "validators that must see unsaved
+        # in-memory records" as the exempted population. This cop is the
+        # complement: bare association reads proven by a same-file
+        # `has_many` / `has_and_belongs_to_many` declaration,
+        # `find`/`detect` only, about correctness justification rather
+        # than SQL push-down. The two never fire on the same node.
+        #
+        # NOTE: non-offenses, by design: an `lvar` shadowing the
+        # association's name (`tags = load_tags; tags.find { }` with a
+        # `has_many :tags` in the file); a same-file `def` receiver (a
+        # scope-shaped method is not a declaration); a `.where`-chained
+        # receiver (NoBlockPredicateOnRelation's territory);
+        # `has_one`/`belongs_to` names (singular associations do not
+        # enumerate); chained receivers such as
+        # `association.reload.find { }`; receivers on other objects
+        # (`other.posts.find { }`); and receivers in files that do not
+        # declare the association — a controller's
+        # `@post.comments.find { }` is a stated blind spot, since the
+        # declaring class is invisible outside its file. Safe-navigation
+        # receivers (`association&.find { }`) fire: same in-memory
+        # semantics. `&:sym` block-passes and numbered-block spellings
+        # fire like block literals; other block-passes
+        # (`&->(tag) { ... }`, `&method(:tag)`) are not detected — the
+        # same documented hole NoBlockPredicateOnRelation carries.
+        #
+        # @example
+        #   # bad (declaration and search in one file)
+        #   class Post < ApplicationRecord
+        #     has_many :comments
+        #
+        #     def foreign_comment?
+        #       comments.find { |comment| comment.post_id != id }
+        #     end
+        #   end
+        #
+        #   # good — the database side
+        #   comments.find_by(post_id: id)
+        #
+        #   # good — the justified in-memory side
+        #   # The post is unsaved, so the submitted comments exist only in
+        #   # the loaded target; find_by on an unsaved owner's association
+        #   # is empty and would let a foreign comment through.
+        #   # rubocop:disable DevDoc/Style/InMemoryAssociationFind
+        #   comments.find { |comment| comment.post_id != id }
+        #   # rubocop:enable DevDoc/Style/InMemoryAssociationFind
+        class InMemoryAssociationFind < Base
+          MSG = 'Block-form `%<method>s` on association `%<association>s` searches the loaded ' \
+                'association, including unsaved in-memory children. Use `find_by` unless that ' \
+                'in-memory view is required; if it is, keep the block form and disable this ' \
+                'cop with that reason.'.freeze
+
+          RESTRICT_ON_SEND = %i[find detect].freeze
+
+          # A bare association read: `comments` or `self.comments`.
+          # Anything else — an lvar, an ivar, a constant, another object's
+          # call, a chained call — captures nothing and the send is left
+          # alone. The safe-navigation spelling reaches here through
+          # `on_csend`: `comments&.find` dispatches on_csend with a plain
+          # `(send nil? :comments)` receiver.
+          def_node_matcher :bare_receiver_name, <<~PATTERN
+            {(send nil? $_) (send (self) $_)}
+          PATTERN
+
+          # The name a `has_many` / `has_and_belongs_to_many` macro declares;
+          # the trailing `...` carries the scope lambda and options hash.
+          def_node_matcher :declared_association_name, <<~PATTERN
+            (send nil? {:has_many :has_and_belongs_to_many} $({sym str} _) ...)
+          PATTERN
+
+          def on_new_investigation
+            super
+            @association_names = nil
+          end
+
+          def on_send(node)
+            return unless node.block_literal? || symbol_block_pass?(node)
+            return if node.receiver.nil?
+
+            name = bare_receiver_name(unwrap_begin(node.receiver))
+            return unless name
+            return unless association_names.include?(name)
+
+            add_offense(node, message: format(MSG, method: node.method_name, association: name))
+          end
+
+          alias on_csend on_send
+
+          private
+
+          # A paren group's value is its LAST child (`(a; b).find { }`
+          # searches `b`), so unwrap to that before matching — same
+          # doctrine as NoBlockPredicateOnRelation.
+          def unwrap_begin(node)
+            node = node.children.last while node&.begin_type?
+            node
+          end
+
+          # `find(&:sym)` searches the loaded target exactly like the literal
+          # block form — one character shorter, so it must not be a dodge.
+          def symbol_block_pass?(node)
+            last = node.last_argument
+            last&.block_pass_type? && last.children.first&.sym_type?
+          end
+
+          # Every collection association name declared in this file, wherever
+          # the macro sits — class body, `included do` block in a concern.
+          def association_names
+            @association_names ||= Set.new.tap do |names|
+              next unless processed_source.ast
+
+              processed_source.ast.each_node(:send) do |node|
+                name = declared_association_name(node)
+                names << name.value.to_sym if name
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,269 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag a block-form `rescue` whose body swallows the failure without
+        # a trace: no re-raise, no reporting call, no stated justification.
+        #
+        # ## Rationale
+        # A rescue that neither re-raises nor reports makes production
+        # failures invisible. The code keeps running on a fallback as if
+        # nothing happened, nothing reaches the logs or the error monitor,
+        # and the first observable symptom is wrong behavior or wrong data —
+        # usually far from the cause, which makes the swallow self-concealing:
+        # the very breakage that should have been seen is the one thing no
+        # one can see. The shape ships easily because it starts as "this must
+        # never break the page": a display helper degrading on a malformed
+        # file, an optional integration returning a fallback. Degrading is
+        # fine; degrading UNRECORDED is not — the report is one line beside
+        # the fallback.
+        #
+        # The broad spellings are the aggravating case: a bare `rescue` or
+        # `rescue StandardError` catches programming errors (NoMethodError,
+        # TypeError) together with the expected environmental failure, so a
+        # bug in the very code being protected is silenced too. A narrow,
+        # named exception class shrinks that blast radius but still owes the
+        # same three exits.
+        #
+        # ## What an offense means
+        # An offense does NOT assert the swallow is a defect. The cop cannot
+        # see whether a deliberate degradation is correct for the call site —
+        # it asserts the swallow is UNDOCUMENTED. A rescue that degrades on
+        # purpose is a violation until the reason is stated in the marker
+        # comment; the marker is the intended resolution for deliberate
+        # ones, not a workaround. On adoption, expect a one-time
+        # justification sweep over existing rescues — writing each reason
+        # honestly IS the audit.
+        #
+        # ## Remedy
+        # The blessed shape is report-then-degrade — one reporting line,
+        # then the fallback:
+        #
+        #   ❌ the failure vanishes
+        #   def verified_suffix
+        #     stamp = read_stamp
+        #     "verified #{stamp.fetch('checked_at')}"
+        #   rescue StandardError
+        #     nil
+        #   end
+        #
+        #   ✔️ report, then degrade — the page still renders, the failure
+        #   still lands where someone will read it
+        #   def verified_suffix
+        #     stamp = read_stamp
+        #     "verified #{stamp.fetch('checked_at')}"
+        #   rescue StandardError => e
+        #     logger.error("stamp unreadable, suffix suppressed: #{e.class} #{e.message}")
+        #     nil
+        #   end
+        #
+        #   ✔️ re-raise (after any partial handling) — the caller decides
+        #
+        #   ✔️ deliberate degradation, reason stated for review
+        #   def verified_suffix
+        #     stamp = read_stamp
+        #     "verified #{stamp.fetch('checked_at')}"
+        #   rescue StandardError
+        #     # silent-rescue: cosmetic suffix only; the stamp file is
+        #     # machine-regenerated and a stale suffix must not break the page.
+        #     nil
+        #   end
+        #
+        # ## Returning the failure as data counts as surfacing it
+        # A body whose return VALUE carries the bound exception — an error
+        # payload (`Result.new(status: 502, body: { error: e.class.to_s })`),
+        # a rendered 4xx (`render json: { error: e.message }, status:
+        # :bad_request`), an error column persisted for a status page — is
+        # not silent: the failure leaves the method with the caller, who
+        # decides what to do with it, exactly as with a re-raise. The cop
+        # reads this structurally: the body's final expression (or any
+        # explicit `return`) references the bound exception variable.
+        # Blind spots of that reading, for reviewers: the reference counts
+        # even on a branch the run did not take, and a generic payload
+        # built WITHOUT the exception ("failed") still flags.
+        #
+        # ## Relationship with `Lint/SuppressedException` (stock)
+        # This cop is a strict superset at the stock cop's default settings
+        # (`AllowComments: true`, `AllowNil: true`): everything it flags —
+        # the empty, uncommented rescue — this cop flags too, and it also
+        # catches the `nil`, literal and silent-action bodies those settings
+        # allow, requiring a named marker phrase instead of any comment.
+        # Disable `Lint/SuppressedException` when enabling this one to avoid
+        # double-flagging the empty-body corner.
+        #
+        # Modifier rescues (`value rescue fallback`) are deliberately out of
+        # scope: the modifier form has no room to report, so every instance
+        # is categorically silent, and `Style/RescueModifier` already flags
+        # all of them on form alone. Keep that cop enabled; this one adds
+        # nothing there.
+        #
+        # ## Configuration
+        # `JustificationMarker` (default: `silent-rescue:`) — the phrase the
+        # adjacent comment must contain: on the `rescue` line itself
+        # (trailing), in the contiguous comment block ending on the line
+        # directly above the `rescue` keyword, or in the body's leading
+        # comment block directly below it (measured adopters put the reason
+        # there; unlike the auth marker cops both sides of the `rescue`
+        # keyword are accepted — the marker still has to name the phrase
+        # deliberately, whichever placement reads best).
+        #
+        # `ReportingMethods` (default: `log`, `warn`, `error`, `errors`,
+        # `exception`, `fatal`, `critical`, `notify`, `notice`, `report`,
+        # `capture`, `track`, `instrument`, `monitor`, `alert`,
+        # `breadcrumb`, `handle`) — matched as whole name TOKENS, not
+        # substrings: a method counts when, after stripping a trailing
+        # `?`/`!`/`=`, any of its `_`-separated segments equals one of these
+        # words. Receiver-agnostic, so any logger or error-monitor API
+        # counts (`logger.error(e)`, `Sentry.capture_exception(e)`,
+        # `NewRelic::Agent.notice_error(e)`), a delegating handler whose
+        # name says what it does counts (`handle_api_error(e)`), and a body
+        # surfacing the failure through the record counts
+        # (`record.errors.add(:base, ...)` — the user sees it). A name that
+        # merely CONTAINS a verb does not: `login_path`, `tracking_number`,
+        # `warning?` are not reporting. Add your project's in-house
+        # reporting verbs here.
+        #
+        # NOTE: The walk judges the body syntactically: any matching call
+        # anywhere in the body counts as reporting, even one an if-condition
+        # hides, and a failure merely stashed (`@last_error = e`) does not.
+        # Reviewers judge whether what gets reported is the right failure.
+        # Retry-only bodies (`rescue; retry; end`) are flagged — an
+        # unreported retry loop is the classic forever-silent failure. An
+        # empty-bodied clause's below-rescue marker also sits directly above
+        # the NEXT clause's `rescue`, so one marker justifies both — a single
+        # statement covering adjacent clauses, accepted as intended. Only
+        # `app/` and `lib/` are inspected.
+        #
+        # @example
+        #   # bad — fallback, no trace
+        #   begin
+        #     sync_prices
+        #   rescue StandardError
+        #     []
+        #   end
+        #
+        #   # good — report, then degrade
+        #   begin
+        #     sync_prices
+        #   rescue StandardError => e
+        #     logger.error("price sync failed: #{e.message}")
+        #     []
+        #   end
+        #
+        #   # good — deliberate, stated
+        #   begin
+        #     sync_prices
+        #   rescue StandardError
+        #     # silent-rescue: prices refresh hourly; a failed refresh keeps
+        #     # the list from the last successful run.
+        #     []
+        #   end
+        class NoSilentRescue < Base
+          include Auth::AdjacentJustification
+          include RescueNode
+
+          MSG = 'This rescue swallows the failure without a trace — report it (a logger/error-monitor ' \
+                'call), re-raise it, or state the reason in a "%<marker>s" comment next to the rescue.'.freeze
+
+          DEFAULT_REPORTING_METHODS = %w[
+            log warn error errors exception fatal critical notify notice report capture track
+            instrument monitor alert breadcrumb handle
+          ].freeze
+
+          PROPAGATING_METHODS = %i[raise fail throw].freeze
+
+          def on_resbody(node)
+            return if rescue_modifier?(node)
+            return if reports_or_propagates?(node.body)
+            return if surfaces_failure?(node)
+            return if adjacent_justification?(node) || leading_body_marker?(node)
+
+            add_offense(node.loc.keyword, message: format(MSG, marker: justification_marker))
+          end
+
+          private
+
+          # Any reporting or propagating call in the body — including the
+          # body itself when it is that call — makes the rescue audible.
+          # An empty body reports nothing by construction.
+          def reports_or_propagates?(body)
+            return false if body.nil?
+
+            body.each_node(:send, :csend).any? { |call| reporting_call?(call) }
+          end
+
+          # The marker also counts in the body's own leading comment block —
+          # the contiguous comment-only lines directly below the `rescue`
+          # keyword, where adopters naturally state the reason. A comment
+          # after the first body statement is not adjacent to the rescue.
+          def leading_body_marker?(node)
+            marker = normalized_marker
+            comments_by_line = processed_source.comments.group_by { |comment| comment.location.line }
+            line = node.loc.keyword.line + 1
+            while (line_comments = comments_by_line[line]) && comment_only_line?(line)
+              return true if contains_marker?(line_comments, marker)
+
+              line += 1
+            end
+
+            false
+          end
+
+          # The String-downcasing the shared concern applies on its own
+          # path; a Regexp marker passes through for `contains_marker?`.
+          def normalized_marker
+            marker = justification_marker
+            marker.is_a?(String) ? marker.downcase : marker
+          end
+
+          # A body whose return value carries the bound exception hands the
+          # failure to the caller as data (error payload, rendered 4xx,
+          # persisted error column) — surfaced, not swallowed.
+          def surfaces_failure?(node)
+            exception_variable = node.exception_variable
+            return false unless exception_variable
+
+            body = node.body
+            return false if body.nil?
+
+            name = exception_variable.name
+            references_exception?(final_expression(body), name) ||
+              body.each_descendant(:return).any? do |returned|
+                references_exception?(returned.children.first, name)
+              end
+          end
+
+          def final_expression(body)
+            body.begin_type? ? body.children.last : body
+          end
+
+          def references_exception?(node, name)
+            return false unless node
+
+            node.each_node(:lvar).any? { |lvar| lvar.children.first == name }
+          end
+
+          # Token match, not substring: `login_path` must not read as
+          # reporting. `warning?`/`save!`/`level=` lose their suffix before
+          # splitting.
+          def reporting_call?(call)
+            name = call.method_name
+            return true if PROPAGATING_METHODS.include?(name)
+
+            tokens = name.to_s.sub(/[?!=]\z/, '').split('_')
+            reporting_methods.any? { |verb| tokens.include?(verb) }
+          end
+
+          def reporting_methods
+            @reporting_methods ||=
+              Array(cop_config.fetch('ReportingMethods', DEFAULT_REPORTING_METHODS))
+          end
+
+          def justification_marker
+            cop_config.fetch('JustificationMarker', 'silent-rescue:')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,193 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag a hand-rolled allow-list lookup — a `find`/`detect` block that
+        # compares each entry of a fixed list (bare or `.to_s`'d) against a
+        # request param — where the boundary helper already owns the decision.
+        #
+        # ## Rationale
+        # `glib_allowlist_symbol_param(value, ALLOWED, default:)` exists so the
+        # missing/junk/blank-value decision lives in one reviewed place. The
+        # hand-rolled `LIST.find { |entry| entry.to_s == params[:x].to_s }`
+        # re-derives the helper's internals at the call site: the
+        # degrade-to-default policy, the nil/blank fallthrough and the
+        # string-space (symbol-DoS-safe) comparison all get re-implemented by
+        # hand, and the next reader cannot tell an intentional degrade from an
+        # oversight. A real instance of exactly this shape slipped through
+        # review carrying a paragraph of commentary explaining what the
+        # helper's name already encodes.
+        #
+        # ## Relationship with the boundary cop pair
+        # Third of the trio over the same boundary doctrine.
+        # `DevDoc/Style/StringSymbolComparison` polices comparing without
+        # converting (always-false `==` against a symbol literal);
+        # `DevDoc/Style/AvoidSymbolizingBoundaryInput` polices converting
+        # without validating (`.to_sym` on params). This cop polices the third
+        # shape: validating by hand instead of through the shared helper. All
+        # three share the same sanctioned exit.
+        #
+        # ## Exception — the swap is a behavior change on mutating requests
+        # On GET/HEAD the helper degrades unrecognised values to `default`,
+        # exactly like the hand-roll. On a mutating request it raises
+        # `UnrecognizedValue` on a present-but-unrecognised value — the
+        # intended doctrine for values the UI wrote (a mismatch means a
+        # forgotten allow-list entry or a broken client and must surface).
+        # Where a silent degrade is deliberate — an endpoint anyone can
+        # POST to, where junk values are expected traffic — pass the
+        # helper's `raise_on_unrecognized: false` (glib-web 7.0.2+):
+        # unrecognised values then degrade to `default` on every method,
+        # matching the hand-roll's degrade-vs-raise behavior. (The return
+        # type follows the remedy's own rule either way: the helper always
+        # symbolizes the matched entry, including entries from string
+        # lists.)
+        #
+        # ## Sources detected
+        # - `params[…]`, `params.dig(…)`, `params.fetch(…)`, `params.require(…)`
+        # - `request.headers[…]`
+        #
+        # `ENV[…]` is deliberately excluded, as in
+        # `DevDoc/Style/AvoidSymbolizingBoundaryInput`: operator-controlled,
+        # not attacker-reachable, and boot-time config code has no controller
+        # helper to call.
+        #
+        # NOTE: only the direct `find`/`detect` block form is detected, and
+        # only over a developer-controlled list: the body must be a single
+        # `==` comparison (parentheses around it are fine; multi-statement
+        # bodies, modifier-`if`/`rescue` bodies and `!=` are not), and the
+        # iterated collection must not itself be boundary-sourced —
+        # `params[:ids].find { … }` is a lookup inside client data, not an
+        # allow-list, and the helper's `.to_sym` must never run over client
+        # entries. A `Hash#find` over pairs (`PRESETS.find { |key, _config| … }`)
+        # fires too; its remedy passes `.keys` and returns the key, not the
+        # `[key, value]` pair. Membership predicates over the same comparison
+        # (`any?`, `include?`), the numbered-block and `it` spellings (`_1`,
+        # Ruby 3.4's `it`), a param already flowed into a local or helper
+        # (`report_params[:x]`), a `params.permit(…)[]` read (not a detected
+        # source, as in the sibling cops), and a laundered list receiver
+        # (`params[:ids].map(&:to_i).find { … }`) are beyond static reach —
+        # review catches those.
+        #
+        # @example
+        #   # bad
+        #   preset = PRESETS.keys.find { |key| key.to_s == params[:preset].to_s }
+        #   mode = MODES.find { |mode| params[:mode].to_s == mode.to_s }
+        #   status = STATUSES.detect { |status| status == params[:status] }
+        #
+        #   # good
+        #   preset = glib_allowlist_symbol_param(params[:preset], PRESETS.keys, default: DEFAULT_PRESET)
+        #   mode = glib_allowlist_symbol_param(params[:mode], MODES, default: :active)
+        #   status = glib_allowlist_symbol_param(params[:status], STATUSES, default: :draft)
+        class PreferAllowlistSymbolParam < Base
+          MSG = 'Hand-rolled allow-list lookup against `%<source>s`; use ' \
+                '`glib_allowlist_symbol_param(value, ALLOWED, default:)` instead.'.freeze
+
+          # String-preserving transforms that may sit between the boundary
+          # read and the comparison — same laundering-hop doctrine as
+          # AvoidSymbolizingBoundaryInput.
+          TRANSFORM_HOPS = %i[presence to_s strip downcase upcase squish].freeze
+
+          def_node_matcher :params_access?, <<~PATTERN
+            (send (send nil? :params) {:[] :dig :fetch :require} ...)
+          PATTERN
+
+          def_node_matcher :request_headers_access?, <<~PATTERN
+            (send (send _ :headers) :[] _)
+          PATTERN
+
+          def on_block(node)
+            return unless %i[find detect].include?(node.send_node.method_name)
+            # A boundary-sourced list is a lookup inside client data, not an
+            # allow-list (see NOTE): the helper's `.to_sym` must never run
+            # over client-controlled entries.
+            return if boundary_source_in(node.send_node.receiver)
+
+            source = boundary_lookup(node)
+            return unless source
+
+            add_offense(node, message: format(MSG, source: source.source))
+          end
+
+          private
+
+          # The boundary access in the block's `==` comparison, whichever side
+          # holds it; nil when the body is not a single comparison or neither
+          # side reads the boundary.
+          def boundary_lookup(block)
+            comparison = block_comparison(block.body)
+            return unless comparison
+
+            names = block_arg_names(block)
+            lookup_source(comparison.receiver, comparison.first_argument, names) ||
+              lookup_source(comparison.first_argument, comparison.receiver, names)
+          end
+
+          # The block's `==` comparison, or nil for any other body shape.
+          # Parentheses mint a single-child `begin` around the comparison;
+          # those are unwrapped so `(entry.to_s == params[:x].to_s)` still
+          # matches, while multi-statement bodies keep their multi-child
+          # begin and fall out here.
+          def block_comparison(body)
+            body = body.children.first while single_child_begin?(body)
+            body if body&.send_type? && body.method?(:==)
+          end
+
+          def single_child_begin?(node)
+            node&.begin_type? && node.children.one?
+          end
+
+          # The compared block arguments (`|key|`); destructured arguments
+          # have no single name and contribute none.
+          def block_arg_names(block)
+            block.arguments.filter_map { |arg| arg.name if arg.arg_type? }
+          end
+
+          # The boundary access behind `other_operand`, when the OTHER side is
+          # the allow-list entry. Returns nil otherwise.
+          def lookup_source(entry_operand, other_operand, names)
+            return unless entry_operand?(entry_operand, names)
+
+            boundary_source_in(other_operand)
+          end
+
+          # The allow-list entry side: a bare block argument (`|status|`) or
+          # its string form (`|key| key.to_s`, `key&.to_s`). Anything richer —
+          # an attribute of the iterated record (`u.email`) or another method
+          # call on it — is a lookup-by-value, not an allow-list, and is left
+          # alone.
+          def entry_operand?(operand, names)
+            return true if operand.lvar_type? && names.include?(operand.name)
+
+            to_s_on_entry?(operand) && names.include?(operand.receiver.name)
+          end
+
+          # The entry's own `.to_s` — the helper's own comparison shape,
+          # whatever the list holds.
+          def to_s_on_entry?(operand)
+            (operand.send_type? || operand.csend_type?) && operand.method?(:to_s) &&
+              operand.receiver&.lvar_type?
+          end
+
+          # The boundary source at the bottom of the receiver chain, walking
+          # through laundering transforms (mirrors
+          # AvoidSymbolizingBoundaryInput#boundary_source_in). Returns nil for
+          # anything else (locals, ivars, helper-method results) so those
+          # don't false-positive.
+          def boundary_source_in(node)
+            while node
+              return node if boundary_source?(node)
+              return nil unless node.send_type? || node.csend_type?
+              return nil unless TRANSFORM_HOPS.include?(node.method_name)
+
+              node = node.receiver
+            end
+          end
+
+          def boundary_source?(node)
+            params_access?(node) || request_headers_access?(node)
+          end
+        end
+      end
+    end
+  end
+end