rubocop-dev_doc 0.5.0.beta1 → 0.6.0.beta1

data/lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb

@@ -43,6 +43,13 @@ module RuboCop
         #     end
         #   end
         #
+        # ## Forms covered
+        # The cop catches `default:` set at column-creation time AND `default:`
+        # set later via `change_column_default(..., to: <non-nil>)`. Both are
+        # the same anti-pattern — a permanent default living in the schema.
+        # `change_column_default(..., to: nil)` (removing a default) is not
+        # flagged; that is the cleanup form.
+        #
         # ## Exception (auto-detected)
         # For performance reasons (large tables with millions of records) or when
         # using `null: false`, you may temporarily set a default and then
@@ -51,6 +58,10 @@ module RuboCop
         # for the same table and column anywhere in the same method body (`def
         # change` / `def up`), including inside `reversible do |dir| dir.up`.
         #
+        # The exception applies symmetrically:
+        # - `add_column ... default: X` paired with `change_column_default ... to: nil` → no offense
+        # - `change_column_default ... to: X` paired with `change_column_default ... to: nil` → no offense
+        #
         #   ✔ (no offense — two-step pattern auto-detected)
         #   add_column :users, :profile_completion_rate, :float, default: 0.0
         #   change_column_default :users, :profile_completion_rate, from: 0.0, to: nil
@@ -62,14 +73,22 @@ module RuboCop
         #   # bad
         #   t.string :status, default: 'active'
         #
+        #   # bad — permanent default set via change_column_default
+        #   change_column_default :users, :score, from: nil, to: 0
+        #
         #   # good
         #   add_column :users, :score, :integer
         #
         #   # good (temporary default immediately removed — two-step pattern)
         #   add_column :users, :score, :integer, default: 0
         #   change_column_default :users, :score, from: 0, to: nil
+        #
+        #   # good (removing an existing default)
+        #   change_column_default :users, :score, from: 0, to: nil
         class AvoidColumnDefault < Base
           MSG = 'Avoid setting `default:` in migrations. Keep business logic defaults in the application layer.'.freeze
+          MSG_CHANGE = 'Avoid setting a non-nil default via `change_column_default`. ' \
+                       'Keep business logic defaults in the application layer.'.freeze
 
           COLUMN_METHODS = %i[
             string integer float boolean datetime date text binary decimal
@@ -84,9 +103,22 @@ module RuboCop
             (send _ :change_column_default (sym $_) (sym $_) (hash <(pair (sym :to) (nil)) ...>))
           PATTERN
 
+          # change_column_default(:table, :col, ..., to: <non-nil>, ...) — captures table + col.
+          def_node_matcher :change_column_default_to_non_nil?, <<~PATTERN
+            (send _ :change_column_default (sym $_) (sym $_) (hash <(pair (sym :to) !nil) ...>))
+          PATTERN
+
           def on_send(node)
-            return unless column_method?(node)
+            if node.method?(:change_column_default)
+              check_change_column_default(node)
+            elsif column_method?(node)
+              check_column_method(node)
+            end
+          end
+
+          private
 
+          def check_column_method(node)
             options = node.arguments.find(&:hash_type?)
             return unless options && has_default_option?(options)
             return if two_step_pattern?(node)
@@ -94,7 +126,16 @@ module RuboCop
             add_offense(find_default_pair(options))
           end
 
-          private
+          def check_change_column_default(node)
+            captures = change_column_default_to_non_nil?(node)
+            return unless captures
+
+            table_name, col_name = captures
+            return if cancelled_in_same_method?(node, table_name, col_name)
+
+            options = node.arguments.find(&:hash_type?)
+            add_offense(find_to_pair(options), message: MSG_CHANGE)
+          end
 
           def column_method?(node)
             node.method?(:add_column) || COLUMN_METHODS.include?(node.method_name)
@@ -104,10 +145,20 @@ module RuboCop
             options.pairs.find { |p| p.key.sym_type? && p.key.value == :default }
           end
 
+          def find_to_pair(options)
+            options.pairs.find { |p| p.key.sym_type? && p.key.value == :to }
+          end
+
           def two_step_pattern?(node)
             table_name, col_name = extract_table_and_column(node)
             return false unless table_name && col_name
 
+            cancelled_in_same_method?(node, table_name, col_name)
+          end
+
+          # Is there a `change_column_default(..., to: nil)` for the same
+          # (table, col) anywhere in the enclosing method? Used by both forms.
+          def cancelled_in_same_method?(node, table_name, col_name)
             enclosing_def = node.each_ancestor(:def).first
             return false unless enclosing_def
 

data/lib/rubocop/cop/dev_doc/migration/avoid_vague_column_names.rb

@@ -2,20 +2,24 @@ module RuboCop
   module Cop
     module DevDoc
       module Migration
-        # Avoid vague column names like `status` or `group`.
+        # Avoid vague column names like `status`, `group`, or `kind`.
         #
         # ## Rationale
         # Use more specific names that describe the domain context. A column
         # named `status` reveals nothing about *what* status it tracks; a column
         # named `processing_status` makes the intent obvious at the call site.
+        # `kind` is the same shape — a content-free "what variety" label that
+        # reads no better than `type` (which Rails reserves for STI).
         #
         #   ❌
         #   t.string :status
         #   add_column :orders, :group, :integer
+        #   t.integer :kind
         #
         #   ✔️
         #   t.string :processing_status
         #   add_column :orders, :user_group, :integer
+        #   t.integer :membership_kind
         #
         # ## Note about `type`
         # `type` is reserved by Rails for Single Table Inheritance (STI). Even
@@ -29,10 +33,12 @@ module RuboCop
         #   # bad
         #   t.string :status
         #   add_column :orders, :group, :integer
+        #   t.integer :kind
         #
         #   # good
         #   t.string :processing_status
         #   add_column :orders, :user_group, :integer
+        #   t.integer :membership_kind
         class AvoidVagueColumnNames < Base
           MSG = 'Avoid vague column name `%<name>s`. Use a more specific name that includes context.'.freeze
 

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

@@ -0,0 +1,167 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Avoid ordering by `id` as the primary (sole or leftmost) sort.
+        #
+        # ## Rationale
+        # `order(id: ...)` / `order(:id)` sorts by the primary key, which
+        # reflects insertion order (and, for UUIDs, random order) rather
+        # than a column the reader can reason about. It makes a list read
+        # as "most recent" by accident, hides the real ordering intent,
+        # and silently breaks the moment rows are imported out of sequence
+        # or the primary key type changes.
+        #
+        # Order by a meaningful business column instead, and reach for
+        # `id` only as a **secondary** key to break ties deterministically:
+        #
+        #   ❌ Primary key is not a sort the reader can reason about
+        #   Snapshot.order(id: :desc)
+        #
+        #   ✔️ Business column carries the intent
+        #   Snapshot.order(created_at: :desc)
+        #
+        #   ✔️ `id` as a deterministic tiebreaker — never the primary sort
+        #   Snapshot.order(created_at: :desc, id: :desc)
+        #
+        # See `best_practices/backend/en/05_controller.md` — always `.order()`
+        # when displaying more than one record, and reserve `order(id: ...)`
+        # for the rare case where id-ordering is genuinely intended.
+        #
+        # ## Scope
+        # Flags `order` and `reorder` where `:id` is the **sole** ordering
+        # column or the **leftmost** (primary) one, in hash form
+        # (`order(id: :desc)`), symbol form (`order(:id)`,
+        # `order(:id, :name)`), or array form (`order([:id])`).
+        #
+        # Only the FIRST argument is inspected — it is the primary sort;
+        # every later argument is a tiebreaker. Raw-SQL string ordering
+        # (`order("id")`, `order("id DESC")`) is the domain of
+        # `DevDoc/Rails/AvoidRawSql`, so this cop defers the moment its
+        # leading argument is a string, an `Arel.sql(...)`, or anything
+        # other than a hash/symbol/array — the primary sort can't be read
+        # statically, and flagging would risk a false positive on a
+        # tiebreaker.
+        #
+        # NOTE: Each `order`/`reorder` call is inspected in isolation, so a
+        # chained form like `rel.order(:created_at).order(id: :desc)` is
+        # flagged even though Rails *appends* chained `order` calls — making
+        # `id` a secondary tiebreaker there. The deterministic-tiebreaker
+        # idiom this cop endorses is the single-call hash/symbol form
+        # (`order(created_at: :desc, id: :desc)`); prefer that, or disable
+        # inline with a reason when the chained form is genuinely intended.
+        #
+        # ## `id` as a secondary key is allowed
+        # `order(created_at: :desc, id: :desc)` is the standard pattern for
+        # deterministic ordering — `id` only breaks ties after the business
+        # column. The cop allows `:id` in any non-primary position:
+        #
+        #   ✔️ `id` breaks ties only — primary sort is `created_at`
+        #   Snapshot.order(created_at: :desc, id: :desc)
+        #   Snapshot.order(:created_at, :id)
+        #
+        # ## Exception
+        # When `id` is genuinely the intended primary sort (rare — usually a
+        # sign something is special about the code), suppress the offense
+        # with an inline disable comment and a brief reason — e.g. an
+        # append-only audit log where `id` is creation order, so
+        # id-ordering is the real intent rather than an accident.
+        #
+        # NOTE: A named scope or model method that wraps the offense hides
+        # it at the call site — `scope :newest, -> { order(id: :desc) }` is
+        # flagged in the model file, but callers of `.newest` are not. The
+        # cop flags the definition, which is where the decision belongs.
+        #
+        # NOTE: Prefer `order(created_at: :desc)` for deterministic
+        # results — see `best_practices/backend/en/05_controller.md` #4.
+        # The rare legitimate `order(id:)` cases (see Exception above) —
+        # e.g. a test grabbing a record a controller just created, where
+        # `created_at` ties across one request and `id` is the only
+        # reliable insertion-order proxy — take an inline disable with a
+        # reason, not a blanket `Exclude` of `spec/**`/`test/**` (that
+        # silences accidental id-ordering in tests).
+        #
+        # @example
+        #   # bad — `id` is the sole or primary sort
+        #   Snapshot.order(id: :desc)
+        #   Snapshot.order(:id)
+        #   Snapshot.order(id: :desc, created_at: :desc)
+        #   Snapshot.order(:id, :created_at)
+        #   submission.snapshots.reorder(id: :asc)
+        #
+        #   # good — business column primary, `id` as a tiebreaker
+        #   Snapshot.order(created_at: :desc)
+        #   Snapshot.order(created_at: :desc, id: :desc)
+        #   Snapshot.order(:created_at, :id)
+        class AvoidOrderingById < Base
+          MSG = 'Ordering by `id` as the primary sort exposes the primary ' \
+                "key's insertion order rather than a meaningful column. " \
+                'Order by a business column (e.g. `created_at:`), or move ' \
+                '`id` to a secondary position as a deterministic tiebreaker. ' \
+                'Disable with a reason when `id` is genuinely the intended ' \
+                'primary sort.'.freeze
+
+          RESTRICT_ON_SEND = %i[order reorder].freeze
+
+          def on_send(node)
+            first = first_ordering_column(node)
+            return unless first
+            return unless id_column?(first)
+
+            add_offense(node.loc.selector)
+          end
+
+          # Safe navigation (`rel&.order(id: :desc)`) parses as a `:csend`
+          # node, which `on_send` does not visit — alias it so the same
+          # check covers both dispatch forms.
+          alias on_csend on_send
+
+          private
+
+          # The leftmost ordering column, or nil when the primary sort
+          # isn't statically knowable. Only the FIRST argument is inspected
+          # — it alone is the primary sort; every later argument is a
+          # tiebreaker.
+          #
+          #   order(:created_at, id: :desc) → :created_at  (id secondary)
+          #   order(id: :desc)              → :id pair key
+          #   order([:id])                  → :id           (array recurses)
+          #
+          # Returns nil (defers) for a raw-SQL string (`DevDoc/Rails/
+          # AvoidRawSql` owns it) AND for any other non-structured leading
+          # arg — an `Arel.sql` node, a helper call, a splat, a literal —
+          # because the primary sort can't be read statically and flagging
+          # would risk a false positive on what may be a tiebreaker.
+          def first_ordering_column(node)
+            ordering_column_of(node.arguments.first)
+          end
+
+          # Resolve the primary sort from a single argument node, recursing
+          # into an array (`order([:id])`) so the array form matches the
+          # bare-symbol form.
+          def ordering_column_of(arg)
+            return nil unless arg
+            return nil if arg.str_type? || arg.dstr_type?
+            return first_hash_key(arg) if arg.hash_type?
+            return ordering_column_of(arg.children.first) if arg.array_type?
+            return arg if arg.sym_type?
+
+            nil
+          end
+
+          def first_hash_key(hash_node)
+            pair = hash_node.pairs.first
+            return nil unless pair
+
+            key = pair.key
+            key if key&.sym_type?
+          end
+
+          def id_column?(node)
+            node.sym_type? && node.value == :id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -22,12 +22,19 @@ module RuboCop
         #   class Order < ApplicationRecord
         #     def save_with_confirmation_email
         #       transaction do
-        #         save!
-        #         OrderMailer.confirmation(self).deliver_later
+        #         saved = save
+        #         invoice.save! if saved
         #       end
+        #       OrderMailer.confirmation(self).deliver_later if saved
         #     end
         #   end
         #
+        # The `deliver_later` is *outside* the transaction deliberately —
+        # `DevDoc/Rails/NoDeliverLaterInTransaction` flags mailers/jobs
+        # queued inside a transaction (the job may run before commit and
+        # read stale data). The `saved` local leaks out of the block
+        # (Ruby's normal scoping), gating the mailer on actual success.
+        #
         # ## When you have multiple call sites needing the same guard
         # The single-method-per-place pattern above works when there is one
         # natural call site. When several controllers/jobs/bulk operations all
@@ -101,8 +108,11 @@ module RuboCop
         #
         #   # good
         #   def save_with_confirmation
-        #     transaction { save! }
-        #     send_confirmation
+        #     transaction do
+        #       saved = save
+        #       invoice.save! if saved
+        #     end
+        #     send_confirmation if saved
         #   end
         class AvoidRailsCallbacks < Base
           CALLBACKS = %i[

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