rubocop-dev_doc 0.5.0.beta1 → 0.5.0

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

@@ -0,0 +1,227 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Avoid raw SQL in query methods and `connection.execute`.
+        #
+        # ## Rationale
+        # Raw SQL bypasses Rails' adapter abstraction, hides typos in
+        # column and table names (a misspelled column silently returns
+        # nothing instead of raising `NameError`), is non-reversible in
+        # migrations, and ships no audit trail for why raw SQL was chosen
+        # over the Rails idiom. Every raw-SQL site should be a deliberate,
+        # reviewable choice — not a default.
+        #
+        # Prefer, in order:
+        #
+        # - The hash/array form: `where(status: "active")`,
+        #   `where(status: ["active", "pending"])`.
+        # - Parameterized fragments: `where("col = ?", val)`,
+        #   `where("col = :sym", sym: val)`. The `?` / `:name` placeholder
+        #   binds the value safely and the column name is the only
+        #   user-controlled surface.
+        # - Arel nodes for database-specific constructs that the hash
+        #   form can't express.
+        #
+        #   ❌ Raw SQL — typo in `statu` returns nothing, silently
+        #   User.where("statu = 'active'")
+        #
+        #   ✔️ Hash form — typo raises `ArgumentError` at the query layer
+        #   User.where(status: "active")
+        #
+        #   ✔️ Parameterized fragment — value bound, column name spelled
+        #   User.where("status = ?", status)
+        #
+        # ## Scope
+        # The cop covers any string argument to:
+        #
+        # - **Execution methods** — `execute`, `exec_query`, `exec_update`,
+        #   `exec_delete`, `exec_insert`, `find_by_sql`, `select_rows`,
+        #   `select_values`, `select_one`, `select_all`, `update_sql`,
+        #   `insert_sql`, `delete_sql`, `update_all`, `delete_all`.
+        # - **Query fragment methods** — `where`, `having`, `order`,
+        #   `reorder`, `joins`, `select`, `group`, `from`, `lock`, `pluck`.
+        # - **`Arel.sql`** — the explicit opt-in to raw SQL (see below).
+        #
+        # Applies everywhere — application code AND migrations. A
+        # migration's `execute "UPDATE ..."` is the same smell as an
+        # app code `where("...")`; both bypass the adapter and offer no
+        # audit trail.
+        #
+        # ## `Arel.sql`
+        # Always flagged. `Arel.sql` exists specifically to bypass Rails'
+        # raw-SQL protection — reaching for it should require
+        # justification, not be a reflex. If a fragment is genuinely
+        # needed, disable inline with a reason; otherwise express it as
+        # an Arel AST node or a parameterized query.
+        #
+        # ## Counter updates (`update_all("col = col + 1")`)
+        # 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
+        # are the Rails-blessed atomic-counter primitives).
+        #
+        # For **bulk counter updates**, the only clean option is
+        # `find_each { |m| Model.increment_counter(:col, m.id) }` — N
+        # 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`
+        # with reasons — the friction is the audit trail (locking
+        # implications, idempotency on re-runs, and the like are worth
+        # a second look).
+        #
+        #   ❌ Single-record counter update via raw SQL
+        #   User.where(id: id).update_all("login_count = login_count + 1")
+        #
+        #   ✔️ Parameterized — generates safe SQL
+        #   User.increment_counter(:login_count, id)
+        #
+        # ## Exception
+        # Genuine raw-SQL needs — database-specific DDL
+        # (`CREATE INDEX CONCURRENTLY`, `ALTER TYPE ... ADD VALUE`),
+        # complex joins that don't fit Arel, analytic queries with CTEs
+        # — go through an inline disable comment with a brief reason.
+        # The friction is the feature: every raw-SQL site ends up in
+        # code review with an articulated justification.
+        #
+        # ## Migration backfills are NOT an exception
+        # A common AI-agent reflex is to justify
+        # `execute "UPDATE users SET role = 0 ..."` with "models can
+        # drift, so raw SQL is safer." That justification is rejected
+        # here. The data-integrity cost of bypassing validations and
+        # callbacks outweighs the (rare, usually catchable) risk of a
+        # migration failing because a model changed.
+        #
+        # The correct backfill pattern goes through the model with
+        # `save!` — `DevDoc/Migration/AvoidBypassingValidation`
+        # enforces this, and `best_practices/backend/en/02_migration.md`
+        # shows the shape:
+        #
+        #   ✔️ Model through the migration — validations run, callbacks fire
+        #   User.where(role: nil).find_each do |user|
+        #     user.role = 0
+        #     user.save!
+        #   end
+        #
+        # If existing rows would fail validation, fix the data first
+        # rather than bypassing validation — that's the signal, not an
+        # obstacle.
+        #
+        # NOTE: Parameterized fragments are detected by the presence of
+        # a `?` or `:name` placeholder plus at least one additional
+        # argument. A `?` appearing in literal SQL that isn't a
+        # placeholder (`where("name LIKE '%?%'")`) is a residual false
+        # negative; inline-disable if it surfaces.
+        #
+        # NOTE: Interpolated strings (`where("col = '#{val}'")`) are
+        # ALWAYS flagged — they cannot be parameterized by construction
+        # and are a SQL-injection risk. Use the `?` placeholder form.
+        #
+        # NOTE: Method calls returning strings (`where(some_helper)`)
+        # are not flagged — the cop only inspects literal strings.
+        # Helper methods that wrap raw SQL should themselves carry the
+        # disable.
+        #
+        # @example
+        #   # bad — raw SQL
+        #   execute "UPDATE users SET role = 0 WHERE role IS NULL"
+        #   User.where("status = 'active'")
+        #   User.where("status = '#{status}'")
+        #   User.order("created_at")
+        #   User.joins("INNER JOIN items ON items.user_id = users.id")
+        #   User.update_all("login_count = login_count + 1")
+        #   User.select("DISTINCT status")
+        #   Arel.sql("NULLS LAST")
+        #
+        #   # good — hash / array / symbol form
+        #   User.where(status: "active")
+        #   User.where(status: ["active", "pending"])
+        #   User.order(:created_at)
+        #   User.joins(:items)
+        #   User.update_all(status: "active")
+        #   User.select(:status)
+        #
+        #   # good — parameterized fragment
+        #   User.where("status = ?", status)
+        #   User.where("status = :sym", sym: status)
+        #   User.find_by_sql("SELECT * FROM users WHERE id = ?", id)
+        #
+        #   # good — counter update on a single record
+        #   User.increment_counter(:login_count, id)
+        class AvoidRawSql < Base
+          MSG = 'Avoid raw SQL — prefer the hash/array form, a ' \
+                'parameterized fragment, or an Arel node. Disable with ' \
+                'a reason when raw SQL is genuinely required.'.freeze
+
+          EXECUTION_METHODS = %i[
+            execute exec_query exec_update exec_delete exec_insert
+            find_by_sql select_rows select_values select_one select_all
+            update_sql insert_sql delete_sql update_all delete_all
+          ].freeze
+
+          FRAGMENT_METHODS = %i[
+            where having order reorder joins select group from lock pluck
+          ].freeze
+
+          SQL_METHODS = (EXECUTION_METHODS + FRAGMENT_METHODS).freeze
+
+          RESTRICT_ON_SEND = (SQL_METHODS + [:sql]).freeze
+
+          def on_send(node)
+            if arel_sql?(node)
+              check_arel_sql(node)
+            elsif SQL_METHODS.include?(node.method_name)
+              check_sql_method(node)
+            end
+          end
+
+          private
+
+          # `Arel.sql("...")` — the explicit opt-in to raw SQL. The
+          # receiver must be the `Arel` constant so unrelated
+          # `obj.sql(...)` calls don't false-positive.
+          def arel_sql?(node)
+            node.method_name == :sql &&
+              node.receiver&.const_type? &&
+              node.receiver.const_name == 'Arel'
+          end
+
+          # Arel.sql is always flagged (no parameterized exemption) —
+          # reaching for it is itself the smell being audited.
+          def check_arel_sql(node)
+            arg = node.first_argument
+            return unless arg && string?(arg)
+
+            add_offense(arg)
+          end
+
+          def check_sql_method(node)
+            arg = node.first_argument
+            return unless arg && string?(arg)
+            return if parameterized?(node, arg)
+
+            add_offense(arg)
+          end
+
+          def string?(arg)
+            arg.str_type? || arg.dstr_type?
+          end
+
+          # A literal string (`str`) is parameterized when it contains a
+          # `?` or `:name` placeholder AND there's at least one more
+          # argument to bind. An interpolated string (`dstr`) is NEVER
+          # parameterized — the value is concatenated in, not bound.
+          def parameterized?(send_node, string_arg)
+            return false if string_arg.dstr_type?
+            return false unless send_node.arguments.count > 1
+
+            value = string_arg.value
+            value.include?('?') || value.match?(/:[a-z_][a-z0-9_]*/i)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Prefer `public_send` over `send` when dispatching dynamically.
+        #
+        # ## Rationale
+        # `public_send` respects Ruby's method visibility. When the dispatched
+        # name should resolve to a public API method (the common case for
+        # generic validators, form helpers, attribute readers, etc.), using
+        # `public_send`:
+        #
+        # - **Surfaces typos / misconfig immediately.** A name that drifts to
+        #   a private internal raises `NoMethodError` instead of silently
+        #   invoking it.
+        # - **Future-proofs the call site.** If the target method later moves
+        #   to private (refactor, contract narrowing), `public_send` raises
+        #   on the next run; `send` keeps silently working — potentially
+        #   masking a real bug.
+        # - **Documents intent.** A reader of `public_send` knows the author
+        #   meant a public-API call. `send` leaves it ambiguous whether
+        #   private access was wanted.
+        #
+        # ## Relationship to AvoidSend
+        # `DevDoc/Style/AvoidSend` flags *dynamic* dispatch (both `send` and
+        # `public_send`) as risky. This cop is orthogonal: it flags `send`
+        # specifically, including the cases AvoidSend exempts (literal-symbol
+        # args, prefix-string args). The friction asymmetry is intentional —
+        # `send` is the deeper exception, so it costs an extra disable:
+        #
+        #   obj.public_send(method_name)        # AvoidSend: 1 disable
+        #   obj.public_send(:foo)               # clean
+        #   obj.send(method_name)               # AvoidSend + this cop: 2 disables
+        #   obj.send(:foo)                      # this cop only: 1 disable
+        #
+        # ## When `send` IS the right choice
+        # Reach for `send` only when you have an articulable reason to bypass
+        # visibility — and leave a comment so the next reader knows it's
+        # deliberate:
+        #
+        # - **Tests** calling a private helper:
+        #
+        #     # rubocop:disable DevDoc/Style/PreferPublicSend -- unit-testing private method
+        #     assert_equal 5, calculator.send(:internal_carry)
+        #     # rubocop:enable DevDoc/Style/PreferPublicSend
+        #
+        # - **Framework / introspection** code that intentionally calls
+        #   private callbacks (e.g. `record.send(:_run_save_callbacks)`).
+        #
+        # ## Receiver-less `send` is exempt
+        # `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`.
+        #
+        # @example
+        #   # bad — prefer public_send
+        #   record.send(attribute)
+        #   instance.send(:public_method)
+        #   obj.send("export_#{x}")
+        #
+        #   # good — visibility-respecting dispatch
+        #   record.public_send(attribute)
+        #   instance.public_send(:public_method)
+        #   obj.public_send("export_#{x}")
+        #
+        #   # good — receiver-less send (calling self's own method)
+        #   send(:internal_helper)
+        class PreferPublicSend < Base
+          MSG = 'Prefer `public_send` over `send` — it respects method ' \
+                'visibility, surfacing typos/misconfig that would otherwise ' \
+                'silently invoke a private method. Disable with a reason ' \
+                'when bypassing visibility is intentional.'.freeze
+
+          RESTRICT_ON_SEND = %i[send].freeze
+
+          def on_send(node)
+            return if node.receiver.nil?
+
+            add_offense(node.loc.selector)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag `Object#tap` whose block ignores the yielded value.
+        #
+        # ## Rationale
+        # `tap` exists to **operate on the yielded receiver and return it** —
+        # `obj.tap { |x| configure(x) }`. The yielded value is the whole
+        # point of the method.
+        #
+        # When the block **ignores** the yielded value, `tap` is no longer
+        # doing that job. It's being used purely as a temp-variable-elision
+        # trick for "run a side effect, then return the receiver":
+        #
+        #   ❌ Block never references the yielded value — `tap` is eliding a temp var
+        #   read_value.tap { do_side_effect }
+        #
+        # This costs readability for no benefit:
+        #
+        # - **It hides the return value in the receiver position.** `tap`'s
+        #   "returns self" behaviour is its *less obvious* property. A reader
+        #   has to stop and recall that the expression returns the receiver,
+        #   not the block's value. The explicit form puts the return value on
+        #   its own line where "what does this return" is literal.
+        # - **Footgun magnet.** Return-value semantics here are subtle — it's
+        #   easy to nearby-edit the block into something whose value you think
+        #   matters, or to confuse it with the broken `expr; side_effect`
+        #   sequence (which returns the side effect's value, not `expr`'s).
+        #   Code whose contract is "return this value" reads and edits more
+        #   safely when the return is explicit.
+        # - **Equal stakes → prefer the duller form.** Both forms are correct
+        #   and neither is faster. With no functional difference, the more
+        #   obvious one wins in a shared codebase.
+        #
+        #   ✔️ Explicit intent, return value on its own line
+        #   result = read_value
+        #   do_side_effect
+        #   result
+        #
+        # ## When `tap` IS the right choice
+        # Reserve `tap` for its canonical use — when the block references the
+        # yielded value:
+        #
+        #   ✔️ Block uses the yielded value — this is what `tap` is for
+        #   Model.new.tap { |m| m.role = :admin; m.save }
+        #   record.tap { |r| logger.debug(r.to_sql) }
+        #
+        # ## Exception
+        # Genuine intentional uses (e.g. a logging side effect that reads
+        # clearer in tap position) go through an inline `# rubocop:disable`
+        # with a reason. The friction is the feature — it forces the choice
+        # to be articulated and reviewed.
+        #
+        # NOTE: Numbered-param (`_1`) and implicit-`it` (Ruby 3.4+) forms are
+        # not flagged — by construction, those forms reference the yielded
+        # value, which is the canonical use of `tap`. Block-pass (`&:sym`) is
+        # likewise not flagged; it isn't a block node.
+        #
+        # NOTE: If a nested block *shadows* the outer arg name
+        # (`tap { |v| items.each { |v| v.foo } }`), the inner reference is
+        # treated as covering the outer — a rare residual false negative.
+        # Inline-disable if it ever matters.
+        #
+        # @example
+        #   # bad — block ignores the yielded value
+        #   read_value.tap { do_side_effect }
+        #   record.tap { |r| log_event }
+        #   value.tap { }
+        #
+        #   # good — block references the yielded value
+        #   Model.new.tap { |m| m.role = :admin; m.save }
+        #   record.tap { |r| logger.debug(r.to_sql) }
+        #
+        #   # good — a reference inside a nested block still counts
+        #   items.tap { |i| [1, 2].each { i << _1 } }
+        #
+        #   # good — preferred explicit form when the value is unused
+        #   result = read_value
+        #   do_side_effect
+        #   result
+        class TapBlockIgnoresValue < Base
+          MSG = '`tap` is for operating on the yielded value — when the ' \
+                'block ignores it, prefer an explicit assign-and-return. ' \
+                'Disable with a reason when the side effect reads clearer ' \
+                'in `tap` position.'.freeze
+
+          def on_block(node)
+            return unless node.send_node.method?(:tap)
+            return if block_uses_yielded_value?(node)
+
+            add_offense(node.send_node.loc.selector)
+          end
+
+          private
+
+          def block_uses_yielded_value?(node)
+            args = node.arguments
+            return false unless args
+            return false if args.children.empty? # no param declared → value ignored
+
+            # `tap` yields one value; multi-arg / destructuring is unusual.
+            # Be conservative — don't flag what we can't confidently call
+            # "ignoring the value".
+            return true if args.children.length >= 2
+
+            arg = args.children.first
+            return true unless arg.respond_to?(:name)
+
+            return false unless node.body # empty body with declared arg → flag
+
+            # Walk from the block node (not `body`): `each_descendant`
+            # excludes the receiver, so a body that *is* an lvar
+            # (`tap { |v| v }`) would be missed otherwise. Nested blocks
+            # are walked too, so a reference inside one counts as "used".
+            # The shadowing edge case is documented above as a NOTE.
+            node.each_descendant(:lvar).any? { |n| n.children.first == arg.name }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -13,6 +13,18 @@ module RuboCop
         # controller test (very rare) — e.g. a search-ranking detail the
         # controller never exposes.
         #
+        # The danger a unit test hides: it can stay green while the feature is
+        # broken in production. It proves a method works in isolation — NOT that
+        # the real request path calls that method, in the right order, inside the
+        # transaction it needs. A model method can be flawless in a unit test
+        # while the controller calls the wrong method, skips it, or runs it
+        # outside its transaction; the unit test stays green and the feature is
+        # broken. Controller tests fail when the *wiring* is wrong — which is
+        # where regressions actually live. So a passing unit test is not evidence
+        # the feature works; it is false confidence about production. Reach for
+        # one only when you are sure a controller test genuinely cannot reach the
+        # path, not because it is quicker to write.
+        #
         # This cop flags only the literal `< ActiveSupport::TestCase`
         # superclass. The blessed blackbox bases —
         # `ActionDispatch::IntegrationTest`, `Glib::IntegrationTest`,
@@ -20,6 +32,18 @@ module RuboCop
         # though they inherit from `ActiveSupport::TestCase` transitively.
         #
         # ## Escape hatch
+        # Before reaching for a unit test, assume a controller test IS possible
+        # and look harder — that conclusion is almost always premature. Behaviour
+        # that feels inherently unit-level is usually reachable end-to-end:
+        #   - Transaction rollback / "a failure mid-request": inject the failure
+        #     at a class-method chokepoint the gem/service calls (stub it to
+        #     raise), drive the real request, and assert the observable rollback
+        #     (e.g. `assert_no_difference` on the record count). Even atomicity,
+        #     which feels inherently unit-level, is reachable this way.
+        #   - "The controller wraps it in a transaction so I can't isolate the
+        #     model's own": you usually don't need to — assert the *observable*
+        #     guarantee through the real path; that is what matters in production.
+        #
         # When a unit test is genuinely necessary, suppress with a reason that
         # explains why a controller test can't cover the path. That reason IS the
         # required justification — keep it specific and reviewable:

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.5.0.beta1".freeze
+    VERSION = "0.5.0".freeze
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.5.0.beta1
+  version: 0.5.0
 platform: ruby
 authors:
 - dev-doc contributors
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -79,6 +80,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+description:
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -91,10 +94,6 @@ files:
 - lib/rubocop-dev_doc.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching.rb
 - lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb
-- lib/rubocop/cop/dev_doc/i18n/report_text.rb
-- lib/rubocop/cop/dev_doc/i18n/require_translation.rb
-- lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb
-- lib/rubocop/cop/dev_doc/i18n/unverified_translation.rb
 - lib/rubocop/cop/dev_doc/migration/amount_column_in_cents.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_bypassing_validation.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb
@@ -109,7 +108,9 @@ files:
 - lib/rubocop/cop/dev_doc/migration/require_timestamps.rb
 - lib/rubocop/cop/dev_doc/rails/application_record_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb
+- lib/rubocop/cop/dev_doc/rails/avoid_ordering_by_id.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_rails_callbacks.rb
+- lib/rubocop/cop/dev_doc/rails/avoid_raw_sql.rb
 - lib/rubocop/cop/dev_doc/rails/bang_save_in_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/enum_column_not_null.rb
 - lib/rubocop/cop/dev_doc/rails/enum_must_be_symbolized.rb
@@ -125,19 +126,23 @@ files:
 - lib/rubocop/cop/dev_doc/style/avoid_send.rb
 - lib/rubocop/cop/dev_doc/style/minimize_variable_scope.rb
 - lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb
+- lib/rubocop/cop/dev_doc/style/prefer_public_send.rb
 - lib/rubocop/cop/dev_doc/style/repeated_bracket_read.rb
 - lib/rubocop/cop/dev_doc/style/repeated_safe_navigation_receiver.rb
 - lib/rubocop/cop/dev_doc/style/string_symbol_comparison.rb
+- lib/rubocop/cop/dev_doc/style/tap_block_ignores_value.rb
 - lib/rubocop/cop/dev_doc/test/avoid_glib_travel_freeze.rb
 - lib/rubocop/cop/dev_doc/test/avoid_unit_test.rb
 - lib/rubocop/cop/dev_doc/test/response_assert_equal.rb
 - lib/rubocop/dev_doc.rb
 - lib/rubocop/dev_doc/plugin.rb
 - lib/rubocop/dev_doc/version.rb
+homepage:
 licenses: []
 metadata:
   default_lint_roller_plugin: RuboCop::DevDoc::Plugin
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -152,7 +157,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.4.6
+signing_key:
 specification_version: 4
 summary: RuboCop cops enforcing dev-doc best practices
 test_files: []

data/lib/rubocop/cop/dev_doc/i18n/report_text.rb

@@ -1,112 +0,0 @@
-module RuboCop
-  module Cop
-    module DevDoc
-      module I18n
-        # Report every user-facing text in a glib JSON-UI text prop — both
-        # hardcoded strings and already-localized `t(...)` calls.
-        #
-        # ## Rationale
-        # `DevDoc/I18n/RequireTranslation` flags only *hardcoded* strings; it
-        # stays silent once a value is localized. This cop is the opposite: it
-        # fires on **every** text value, localized or not, so you can sweep a
-        # codebase and collect the full list of user-facing strings (e.g. to
-        # seed a translation catalog or audit coverage).
-        #
-        # It is a tooling aid, not a lint — **disabled by default** and runs at
-        # `info` severity. Run it during a localization pass; it is not meant
-        # for every commit.
-        #
-        # Both the hardcoded form (`view.p text: 'Welcome'`) and the localized
-        # form (`view.p text: t('home.welcome')`) are reported. Blank/whitespace
-        # strings and pure dynamic values (`user.name`) carry no static text and
-        # are skipped — see `DevDoc/I18n/UnverifiedTranslation` for those.
-        #
-        # The watched method names and localizable keys are configurable via
-        # `WatchedMethods:` and `LocalizableKeys:`.
-        #
-        #   📋 Reported — hardcoded text
-        #   view.p text: 'Welcome'
-        #
-        #   📋 Reported — localized text
-        #   view.p text: t('home.welcome')
-        #
-        # @example
-        #   # info (hardcoded text)
-        #   view.p text: 'Welcome'
-        #
-        #   # info (localized text — still reported)
-        #   view.p text: t('home.welcome')
-        #
-        #   # info (interpolated string)
-        #   view.p text: "Hi #{name}"
-        #
-        #   # ignored (blank — no text)
-        #   view.fields_text label: ''
-        #
-        #   # ignored (pure dynamic — no static text)
-        #   view.p text: user.name
-        class ReportText < Base
-          MSG = 'Text for `%<key>s:`: review/collect this for localization.'.freeze
-
-          DEFAULT_WATCHED_METHODS = %w[
-            h1 h2 h3 h4 h5 p label markdown
-            fields_text fields_number fields_select fields_password
-            fields_textarea fields_check fields_checkGroup fields_chipGroup
-            fields_timeZone fields_radioGroup fields_date fields_datetime
-          ].freeze
-
-          DEFAULT_LOCALIZABLE_KEYS = %w[
-            title subtitle subsubtitle label placeholder text
-          ].freeze
-
-          TRANSLATION_METHODS = %i[t translate].freeze
-
-          def on_send(node)
-            return unless watched_methods.include?(node.method_name.to_s)
-
-            node.arguments.each do |arg|
-              next unless arg.hash_type?
-
-              arg.pairs.each { |pair| check_pair(pair) }
-            end
-          end
-          alias on_csend on_send
-
-          private
-
-          def check_pair(pair)
-            key = pair.key
-            return unless key.sym_type?
-            return unless localizable_keys.include?(key.value.to_s)
-            return unless text?(pair.value)
-
-            add_offense(pair.value, message: format(MSG, key: key.value))
-          end
-
-          # Any value that carries static user-facing text: a non-blank string
-          # literal, an interpolated string, or a translation call. Blank strings
-          # and pure dynamic values (`user.name`) carry no text and are skipped.
-          def text?(node)
-            return true if node.dstr_type?
-            return !node.value.strip.empty? if node.str_type?
-
-            translation_call?(node)
-          end
-
-          def translation_call?(node)
-            (node.send_type? || node.csend_type?) &&
-              TRANSLATION_METHODS.include?(node.method_name)
-          end
-
-          def watched_methods
-            cop_config.fetch('WatchedMethods', DEFAULT_WATCHED_METHODS)
-          end
-
-          def localizable_keys
-            cop_config.fetch('LocalizableKeys', DEFAULT_LOCALIZABLE_KEYS)
-          end
-        end
-      end
-    end
-  end
-end