rubocop-dev_doc 0.5.0.beta1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e13da0de0c2a17314d72cbe4bbeb9882a0ad1f93e4976d2e0548210af1684073
-  data.tar.gz: 57bf1fb471573aaa8417f3a86f9c4eba84ebc1d71d38d397c7cac2d05607d058
+  metadata.gz: 2076123d07503e775a29287eafcd8dc9d8cf6e344eeb4b462d29120fdef12879
+  data.tar.gz: 910414d217e37c808b7626add2b876d24f6ef214a725b373e86dc736acb24ff7
 SHA512:
-  metadata.gz: c302ad93dcb52860f23365fa361df3c1f593d618c6948b7b113eac124e640687345c2e953eca523777377eb27d7f75b4c177c2029dc5ceb71e7c30e0d52d5fab
-  data.tar.gz: bf88a2042d7dce6169ec7b274c1249b4c291518076f1d26c5d5b9f8c5a95699bcd1e343d27970e8809f7ad91fafe67d1206a553b1e5e162f14c59458cf3b0416
+  metadata.gz: 7681307dae1b8d09d0344c199d4be497bc4c986b4314711ae39550d7d8ced8d8b811d07d98997f8e3fc85d294e6fde1b97c8cb6cdc3c33a40ad3074cda985d62
+  data.tar.gz: a047b648abfcaeb1842158a562c17028601a2f24c67e1f0aa2cdc548377cccd1658dae4b6b68cee1cb4906275a59822f2870160380e71cb5d730c04ce5d44196

data/config/default.yml

@@ -7,10 +7,6 @@ DevDoc/Auth:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
   DocumentationExtension: ".md"
 
-DevDoc/I18n:
-  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
-  DocumentationExtension: ".md"
-
 DevDoc/Migration:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
   DocumentationExtension: ".md"
@@ -83,11 +79,12 @@ DevDoc/Migration/DateColumnNaming:
     - "db/migrate/**/*.rb"
 
 DevDoc/Migration/AvoidVagueColumnNames:
-  Description: "Avoid vague column names like `status` or `group`. Use more specific names."
+  Description: "Avoid vague column names like `status`, `group`, or `kind`. Use more specific names."
   Enabled: true
   VagueNames:
     - status
     - group
+    - kind
   Include:
     - "db/migrate/*.rb"
     - "db/migrate/**/*.rb"
@@ -150,10 +147,10 @@ DevDoc/Rails/EnumColumnNotNull:
 DevDoc/Rails/NoBlockPredicateOnRelation:
   Description: "Avoid block-form `count`/`reject`/`select`/`find`/`any?` on AR relations; push the predicate into SQL with `.where(...)` or a scope."
   Enabled: true
+  AdditionalNonRelationMethods: []
   Exclude:
     - "spec/**/*"
     - "test/**/*"
-    - "db/seeds.rb"
     - "db/seeds/**/*.rb"
     - "lib/tasks/**/*.rb"
 
@@ -169,6 +166,10 @@ DevDoc/Style/AvoidSend:
   Description: "Avoid `send`/`public_send` with an explicit receiver; prefer direct calls or safer alternatives."
   Enabled: true
 
+DevDoc/Style/PreferPublicSend:
+  Description: "Prefer `public_send` over `send` — visibility-respecting dispatch surfaces typos/misconfig and documents intent."
+  Enabled: true
+
 DevDoc/Style/RepeatedSafeNavigationReceiver:
   Description: "Avoid using `&.` on the same receiver more than once in a method body — assign once and use `.` after."
   Enabled: true
@@ -181,6 +182,10 @@ DevDoc/Style/MinimizeVariableScope:
   Description: "Assign a variable inside the `if` condition that guards it, to keep its scope local to the branch."
   Enabled: true
 
+DevDoc/Style/TapBlockIgnoresValue:
+  Description: "Flag `tap` whose block ignores the yielded value — `tap` is for operating on the receiver, not eliding a temp var."
+  Enabled: true
+
 DevDoc/Style/AvoidHeadResponse:
   Description: "Avoid `head()` with error statuses; delegate error handling to Rails exceptions or model validations."
   Enabled: true
@@ -311,6 +316,14 @@ DevDoc/Rails/StrongParametersExpect:
   Include:
     - "app/controllers/**/*.rb"
 
+DevDoc/Rails/AvoidRawSql:
+  Description: "Avoid raw SQL — prefer the hash/array form, parameterized fragments, or Arel; disable with a reason when raw SQL is genuinely required."
+  Enabled: true
+
+DevDoc/Rails/AvoidOrderingById:
+  Description: "Avoid `order`/`reorder` by `id` as the primary (sole or leftmost) sort — order by a business column, or use `id` only as a secondary tiebreaker."
+  Enabled: true
+
 # `save!` / `update!` raise on persistence failure, which is what
 # we want in jobs/services/rake tasks — silent `false` returns
 # hide bugs. Excluded for controllers, which lean on `save`
@@ -383,136 +396,3 @@ DevDoc/Auth/CurrentUserBranching:
     - "app/helpers/**/*.rb"
     - "app/controllers/concerns/**/*.rb"
     - "app/views/layouts/**/*"
-    - "app/controllers/application_controller.rb"
-
-DevDoc/I18n/RequireTranslation:
-  Description: "Localize user-facing strings in glib JSON-UI props; pass `t(...)` instead of a hardcoded string."
-  Enabled: false
-  # WatchedMethods: glib component builder methods whose hash props carry
-  # user-facing text. LocalizableKeys: the prop names checked on those calls.
-  # Extend both if your project adds custom components or text props.
-  WatchedMethods:
-    - 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
-  LocalizableKeys:
-    - title
-    - subtitle
-    - subsubtitle
-    - label
-    - placeholder
-    - text
-  Include:
-    - "app/views/**/*.jbuilder"
-    - "app/views/**/*.rb"
-
-DevDoc/I18n/TranslationKeyPrefix:
-  Description: "Translation keys must start with an allowed namespace prefix (e.g. `hotel.`, `general.`)."
-  Enabled: false
-  # AllowedPrefixes is project-specific, so it defaults to empty and the cop is
-  # a no-op until configured. Matches `t`, `translate`, and `I18n.t`. Only
-  # statically-literal keys are checked; dynamic/interpolated keys are skipped.
-  AllowedPrefixes: []
-  Include:
-    - "app/views/**/*.jbuilder"
-    - "app/views/**/*.rb"
-    - "app/controllers/**/*.rb"
-    - "app/mailers/**/*.rb"
-    - "app/helpers/**/*.rb"
-
-DevDoc/I18n/UnverifiedTranslation:
-  Description: "Warn when a glib text prop is set from a non-literal value that isn't a `t(...)` call — it may be an unlocalized string."
-  # A review aid, not a clean lint: it can't tell a stashed literal from
-  # dynamic data (`user.name`) or a translation reached via a variable. Off by
-  # default and `info` severity — run it during a localization pass. Mirrors
-  # RequireTranslation's WatchedMethods/LocalizableKeys.
-  Enabled: false
-  Severity: info
-  WatchedMethods:
-    - 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
-  LocalizableKeys:
-    - title
-    - subtitle
-    - subsubtitle
-    - label
-    - placeholder
-    - text
-  Include:
-    - "app/views/**/*.jbuilder"
-    - "app/views/**/*.rb"
-
-DevDoc/I18n/ReportText:
-  Description: "Report every user-facing glib text prop — hardcoded and already-localized — to collect all possible texts."
-  # A tooling aid, not a lint: unlike RequireTranslation it fires on *every*
-  # text value (including `t(...)` calls) so you can sweep the codebase and
-  # collect the full list of user-facing strings. Off by default and `info`
-  # severity. Mirrors RequireTranslation's WatchedMethods/LocalizableKeys.
-  Enabled: false
-  Severity: info
-  WatchedMethods:
-    - 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
-  LocalizableKeys:
-    - title
-    - subtitle
-    - subsubtitle
-    - label
-    - placeholder
-    - text
-  Include:
-    - "app/views/**/*.jbuilder"
-    - "app/views/**/*.rb"

data/lib/rubocop/cop/dev_doc/auth/current_user_branching.rb

@@ -56,13 +56,56 @@ module RuboCop
         #
         # ## Allowed paths (Exclude:)
         # By default the cop is silent in:
-        #   app/policies/**/*.rb
+        #   app/policies/**/*.rb          ← auth-dependent checks belong here
         #   app/helpers/**/*.rb
         #   app/controllers/concerns/**/*.rb
-        #   app/views/layouts/**/*
-        #   app/controllers/application_controller.rb
+        #   app/views/layouts/**/*        ← display branching (nav bars, etc.)
         #
-        # Override via `Exclude:` in your `.rubocop.yml`.
+        # Override via `Exclude:` in your `.rubocop.yml`. Note: literal file
+        # paths (e.g. `app/controllers/application_controller.rb`) in
+        # `.rubocop.yml` `Exclude:` lists are flagged by the
+        # `DevDoc::Test::Lints::NoFileExcludes` lint — they hide the
+        # suppression from readers of that file. If `ApplicationController`
+        # needs an exception, use an inline `# rubocop:disable` at the
+        # specific line with a reason.
+        #
+        # ## Before disabling inline, consider the Policy
+        # The Policy exclusion is not accidental — it's the canonical
+        # Rails home for auth-dependent branching. If the flagged line
+        # is an authorization check (`return if @record.accessible_by?(current_user)`,
+        # `if current_user.admin?`, etc.), the right move is almost
+        # always to push that check into a Pundit policy method, not
+        # disable inline. The controller becomes
+        # `return unless policy(@record).access?` — same behaviour,
+        # no `current_user` reference in the controller, and the auth
+        # logic is reusable + testable in isolation.
+        #
+        # Even better: declare `glib_authorize_resource` at the
+        # controller level. glib-web runs the appropriate policy
+        # method before each action automatically, so the per-action
+        # `verify_access` / `authorize @record` line is usually not
+        # needed at all — the controller body no longer references
+        # `current_user` because the auth check has moved out of the
+        # action entirely. See `best_practices/backend/en/05_controller.md`
+        # item #7 for the canonical pattern.
+        #
+        #   ❌ Auth check in the controller — flagged
+        #   def verify_access
+        #     return if @support_question.accessible_by?(current_user)
+        #     # ... token fallback ...
+        #   end
+        #
+        #   ✔️ Same check in the Policy — silently allowed
+        #   # app/policies/support_question_policy.rb
+        #   def access?
+        #     user.present? && record.accessible_by?(user)
+        #   end
+        #
+        #   # in the controller:
+        #   def verify_access
+        #     return if policy(@support_question).access?
+        #     # ... token fallback ...
+        #   end
         #
         # NOTE: The cop does not autocorrect — there is no mechanical fix. The
         # right response depends on developer intent: drop the branch (if auth

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[