rubocop-dev_doc 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f6961dde0d54631bae2f2dae6325183cc678f81701aa06575abab88cc1b0f7b
-  data.tar.gz: cc20cca8c229dca80fbd57d9950794b71560ccb2c13e0ace82c9b6cab0a0c93c
+  metadata.gz: 05e1aabe21621ec2ef5867764976fcfb58d7e0bb42b6224f56065ac17bb5cd8b
+  data.tar.gz: 2adbd5114fa685aaf7240c04df9fadb955d2cba1a0ccfd83d1e8fb44751f9743
 SHA512:
-  metadata.gz: cdf5e192d7d3b526311ca7e9b6d6d3d81a50b3a14d8bd9b4b4a5d4459c0ed4d34c4695e1087e109614cf6f5dc040a12b0e7686f4e4cf509e16f4c9b770a0ccfa
-  data.tar.gz: 3664cc36ac24eb3f1a0bd6061a3671c32695113d50dd87753a35ec13536d02330fa7f10c7188439e90726a9b3a80dac227205cbaf88f539cb668dd7d18ea628d
+  metadata.gz: ffe0a1d90cdf8d0a4dcee8ba865631f9d9c8e3a1e2b3de6af25aa6eb9441a966d715d099e3824e40ec5ec2640c001d9043f375e81fc590732309554b81b80e18
+  data.tar.gz: 1d164d6cc051b8f216384ef334d0b5015a08d52a71cdb9b93e0cf065b6440e9a7285c3d4904d83be92936631b638428ff1dd816f39ace4a76b6053ee98b184b4

data/config/default.yml

@@ -188,6 +188,17 @@ DevDoc/Rails/NoTransactionInController:
   Include:
     - "app/controllers/**/*.rb"
 
+# Same placement rule in an assignment costume: `collection_ids=` on a
+# persisted record writes the join table immediately (no save, no
+# validations), so a controller-side ids write either bypasses the guards the
+# operation's form object/model enforces on its other write paths, or mutates
+# the association even when the surrounding operation fails afterwards.
+DevDoc/Rails/NoCollectionIdsWriterInController:
+  Description: "Association `*_ids=` writers in controllers persist join rows immediately on a persisted record, bypassing validations; move the write into the model method or form object that owns the operation's validations."
+  Enabled: true
+  Include:
+    - "app/controllers/**/*.rb"
+
 DevDoc/Rails/EnumMustBeSymbolized:
   Description: "Declare enums with `enum_symbolize :foo, { … }` instead of a bare `enum`, so the attribute type is set before the enum and the reader returns a symbol."
   Enabled: true
@@ -986,6 +997,18 @@ DevDoc/I18n/TranslationKeyPrefix:
     - "app/mailers/**/*.rb"
     - "app/helpers/**/*.rb"
 
+DevDoc/Rails/SoftFailureInBangMethod:
+  Description: "A bang-named model method must not fail softly (errors on the record + falsy return) — that is `save` semantics; drop the `!` or raise."
+  Enabled: true
+  Include:
+    - "app/models/**/*.rb"
+
+DevDoc/Rails/NoManualRecordInvalid:
+  Description: "Do not raise ActiveRecord::RecordInvalid by hand; only `save!`/`create!` should raise it. Signal domain failure softly via errors + falsy return."
+  Enabled: true
+  Include:
+    - "app/models/**/*.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*

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

@@ -2,13 +2,18 @@ module RuboCop
   module Cop
     module DevDoc
       module Auth
-        # The adjacent-justification contract shared by the auth "flag and make
-        # the developer state the mechanism" cops: an offense is silenced by a
-        # comment containing the cop's marker phrase either on the flagged
-        # node's own line (trailing) or in the contiguous comment block ending
-        # on the line directly above it. Adjacency is the point — a marker
-        # elsewhere in the file justifies nothing. Host cops must provide
-        # `justification_marker`.
+        # The adjacent-justification contract shared by the "flag and make the
+        # developer state the mechanism" cops (the auth family, and
+        # `DevDoc/Migration/AvoidNonNull`'s column-kind markers): an offense is
+        # silenced by a comment containing the cop's marker either on the
+        # flagged node's own line (trailing) or in the contiguous comment block
+        # ending on the line directly above it. Adjacency is the point — a
+        # marker elsewhere in the file justifies nothing. Host cops provide
+        # `justification_marker`, or pass an explicit `marker:` per call. A
+        # String marker matches by substring (suits multi-word phrases); a
+        # Regexp marker matches by `match?` against the downcased comment text
+        # (use `\b` anchors for single-word markers, where substring matching
+        # would let "enumeration" satisfy an `enum` marker).
         #
         # With `standalone_only: true` the upward walk only crosses comment-ONLY
         # lines. Use this when the checked node is a class/module declaration:
@@ -17,8 +22,8 @@ module RuboCop
         module AdjacentJustification
           private
 
-          def adjacent_justification?(node, standalone_only: false)
-            marker = justification_marker.downcase
+          def adjacent_justification?(node, standalone_only: false, marker: justification_marker)
+            marker = marker.downcase if marker.is_a?(String)
             comments_by_line = processed_source.comments.group_by { |comment| comment.location.line }
 
             return true if contains_marker?(comments_by_line[node.first_line], marker)
@@ -46,7 +51,10 @@ module RuboCop
           end
 
           def contains_marker?(comments, marker)
-            Array(comments).any? { |comment| comment.text.downcase.include?(marker) }
+            Array(comments).any? do |comment|
+              text = comment.text.downcase
+              marker.is_a?(Regexp) ? marker.match?(text) : text.include?(marker)
+            end
           end
         end
       end

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

@@ -44,9 +44,7 @@ module RuboCop
         #   add_column :checklists, :approval_required, :boolean
         #
         #   ✔️ enum; "unset" is explicit, null: false is justified
-        #   # rubocop:disable DevDoc/Migration/AvoidNonNull -- enum
-        #   add_column :checklists, :approval_requirement, :integer, null: false
-        #   # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #   add_column :checklists, :approval_requirement, :integer, null: false # enum
         #
         #   class Checklist < ApplicationRecord
         #     enum :approval_requirement, { no_approval_needed: 0, approval_by_admins: 1 }
@@ -76,7 +74,7 @@ module RuboCop
         #
         #   ✔️ true binary preference, justified
         #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference; user opt-in
-        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false
+        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false # boolean
         #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
         #
         # NOTE: This cop catches `t.boolean`, `add_column ..., :boolean`,
@@ -104,7 +102,7 @@ module RuboCop
         #
         #   # good (justified boolean)
         #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference
-        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false
+        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false # boolean
         #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
         class AvoidBooleanColumn < Base
           MSG = 'Avoid `boolean` columns; consider a timestamp (approved_at), enum, or model method. ' \

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

@@ -1,3 +1,5 @@
+require_relative '../auth/adjacent_justification'
+
 module RuboCop
   module Cop
     module DevDoc
@@ -50,34 +52,54 @@ module RuboCop
         #   violation), so `null: false` is required, and enforced from the model
         #   side by `DevDoc/Rails/EnumColumnNotNull`. But an enum is a plain
         #   `integer` column, statically indistinguishable from any other
-        #   integer, so THIS cop cannot detect it and WILL flag it. Disable it on
-        #   the line with a brief reason — `-- enum` — so the migration is
-        #   self-documenting: a reader sees at a glance that the column is an enum.
+        #   integer, so THIS cop cannot detect it and WILL flag it. Mark the line
+        #   with an adjacent `# enum` comment (see Markers below) so the
+        #   migration is self-documenting: a reader sees at a glance that the
+        #   column is an enum.
         # - **Boolean columns justified via `DevDoc/Migration/AvoidBooleanColumn`**
         #   — once the developer has justified a boolean through that cop's
         #   escape hatch, NULL is outside {true, false} (just as it is outside an
         #   enum's domain), so `null: false` is required and enforced by the
-        #   sibling cop `DevDoc/Migration/BooleanColumnNotNull`. Disable this cop
-        #   on the line with `-- boolean` so the migration is self-documenting.
+        #   sibling cop `DevDoc/Migration/BooleanColumnNotNull`. Mark the line
+        #   with an adjacent `# boolean` comment.
+        #
+        # ## Markers
+        # The marker is a comment containing the word `enum` or `boolean`, either
+        # trailing the flagged line itself or in the contiguous COMMENT-ONLY
+        # block ending on the line directly above it. A marker trailing a
+        # *previous code line* deliberately does not count — otherwise one
+        # marked column would silence the unmarked column defined on the next
+        # line. Matching is case-insensitive and word-bounded (exactly `enum` /
+        # `boolean`): a prose comment like `# enum — NULL is outside the
+        # enum's domain` satisfies the marker, while `enumeration`, `enums`,
+        # or `enum_type` do not. Adjacency is the point — a marker elsewhere
+        # in the file justifies nothing.
         #
         #   ✔️ Required foreign key (never flagged)
         #   t.belongs_to :user, null: false, foreign_key: true
         #
-        #   ✔️ Enum (flagged here — disable with a brief `-- enum` reason)
-        #   # rubocop:disable DevDoc/Migration/AvoidNonNull -- enum
+        #   ✔️ Enum, marker trailing the line
+        #   add_column :orders, :status, :integer, null: false # enum
+        #
+        #   ✔️ Enum, marker in the comment above
+        #   # enum — NULL is outside the enum's domain
         #   add_column :orders, :status, :integer, null: false
-        #   # rubocop:enable DevDoc/Migration/AvoidNonNull
         #
-        #   ✔️ Boolean (flagged here — disable with a brief `-- boolean` reason)
-        #   # rubocop:disable DevDoc/Migration/AvoidNonNull -- boolean
+        #   ✔️ Boolean (justified through AvoidBooleanColumn's escape hatch)
         #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference
-        #   add_column :things, :flag, :boolean, null: false
+        #   add_column :things, :flag, :boolean, null: false # boolean
         #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
-        #   # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #
+        # A `# rubocop:disable` directive still silences the cop like any other
+        # (RuboCop-level behavior), but the marker is the sanctioned form —
+        # consumer projects that police inline disables (e.g. via
+        # `Style/DisableCopsWithinSourceCodeDirective`'s `AllowedCops`) can drop
+        # this cop from their allowed-disables list once existing sites carry
+        # markers.
         #
         # NOTE: This cop is deliberately NOT enum-aware. It could read the
         # model's `enum` declarations and skip those columns, but requiring an
-        # explicit per-line disable is intentional: it forces the developer to
+        # explicit per-line marker is intentional: it forces the developer to
         # signal that the column is an enum, which documents the migration. A
         # silent skip would hide that intent.
         #
@@ -85,8 +107,10 @@ module RuboCop
         # API: `change_column_null(table, column, false)` and
         # `change_column(table, column, type, null: false)`. Both express the same
         # constraint as `null: false` on a definition (the add-nullable -> backfill
-        # -> tighten step), so a legit enum/boolean tightening disables this cop
-        # inline with `-- enum`/`-- boolean`, exactly as for a new column.
+        # -> tighten step), so a legit enum/boolean tightening carries the same
+        # `# enum`/`# boolean` marker, exactly as for a new column. When the
+        # tightening runs inside a loop, put the marker on the line of the
+        # `change_column_null` call itself.
         #
         # NOTE: This cop only flags `null: false` (and the equivalent `false` arg
         # of `change_column_null`). It does not flag `null: true` (redundant but
@@ -105,17 +129,27 @@ module RuboCop
         #   # bad (same tightening, via change_column)
         #   change_column :users, :name, :string, null: false
         #
-        #   # bad (enum without a disable — the cop flags it; disable with `-- enum`)
+        #   # bad (enum without a marker — the cop flags it)
         #   t.integer :processing_status, null: false
         #
         #   # good
         #   add_column :users, :name, :string
         #
+        #   # good (enum, marked)
+        #   t.integer :processing_status, null: false # enum
+        #
         #   # good (required foreign key — never flagged)
         #   t.belongs_to :user, null: false, foreign_key: true
         class AvoidNonNull < Base
+          include Auth::AdjacentJustification
+
           MSG = 'Avoid `null: false` on regular columns; enforce presence in the model layer. ' \
-                'If this is an enum column, disable this cop on the line with a brief reason, e.g. `-- enum`.'.freeze
+                'If this is an enum or justified boolean column, mark the line with an adjacent ' \
+                '`# enum` / `# boolean` comment.'.freeze
+
+          # Word-bounded so an incidental "enumeration" in a comment cannot
+          # satisfy the marker. Comment text is downcased before matching.
+          KIND_MARKER = /\b(?:enum|boolean)\b/
 
           # Column-definition helpers that take a `null:` option. Deliberately
           # EXCLUDES `references` / `belongs_to` (and the separate `add_reference`
@@ -139,14 +173,17 @@ module RuboCop
           # step. Flagged so the cop cannot be sidestepped by choice of API: a
           # regular column tightened to NOT NULL is held to the same standard as one
           # declared NOT NULL up front. A legit enum/boolean tightening resolves at
-          # the disable site, exactly as for a new column.
+          # the marker site, exactly as for a new column.
           def_node_matcher :change_column_null_false, <<~PATTERN
             (send _ :change_column_null _ _ $false ...)
           PATTERN
 
           def on_send(node)
             flag = offense_node(node)
-            add_offense(flag) if flag
+            return unless flag
+            return if kind_marker?(node, flag)
+
+            add_offense(flag)
           end
 
           private
@@ -158,6 +195,17 @@ module RuboCop
             change_column_null_false(node) || column_null_false_pair(node)
           end
 
+          # Checked from both the call's first line and the offending
+          # `null: false` pair's own line, so a multi-line call accepts the
+          # marker trailing either. standalone_only: the upward walk crosses
+          # comment-only lines exclusively — a marker trailing a PREVIOUS code
+          # line (the column defined one line up, the enclosing create_table,
+          # an earlier argument of this very call) must not silence this one.
+          def kind_marker?(node, flag)
+            adjacent_justification?(node, marker: KIND_MARKER, standalone_only: true) ||
+              adjacent_justification?(flag, marker: KIND_MARKER, standalone_only: true)
+          end
+
           def column_null_false_pair(node)
             return unless column_method?(node)
 

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

@@ -24,8 +24,8 @@ module RuboCop
         # the boolean case: that cop flags `null: false` on regular
         # columns (including booleans, which it cannot distinguish from
         # other types); this cop REQUIRES `null: false` on booleans. The
-        # contradiction is resolved at the disable site: when the
-        # developer disables `AvoidNonNull` on a boolean with `-- boolean`
+        # contradiction is resolved at the marker site: when the
+        # developer marks the `AvoidNonNull` line with `# boolean`
         # (alongside the `AvoidBooleanColumn` disable), this cop fires if
         # `null: false` is missing.
         #
@@ -47,9 +47,7 @@ module RuboCop
         #       end
         #     end
         #
-        #     # rubocop:disable DevDoc/Migration/AvoidNonNull -- boolean
-        #     change_column_null :table, :flag, false
-        #     # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #     change_column_null :table, :flag, false # boolean
         #   end
         #
         # The application layer is the source of truth for the default

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

@@ -27,12 +27,11 @@ module RuboCop
         # ## Interaction with AvoidNonNull
         # An enum is a plain `integer` column, so `AvoidNonNull` cannot tell it
         # apart from a regular integer and WILL flag the `null: false` you add
-        # to satisfy this cop. Disable it on that migration with a brief `-- enum`
-        # reason, so the migration is self-documenting:
+        # to satisfy this cop. Mark the migration line with an adjacent `# enum`
+        # comment (that cop's sanctioned marker), so the migration is
+        # self-documenting:
         #
-        #   # rubocop:disable DevDoc/Migration/AvoidNonNull -- enum
-        #   add_column :orders, :status, :integer, null: false
-        #   # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #   add_column :orders, :status, :integer, null: false # enum
         #
         # NOTE: This cop reads `db/schema.rb` and does nothing if it is absent
         # (e.g. projects using `structure.sql`). It also relies on the schema

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

@@ -0,0 +1,129 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Controllers must not call association `*_ids=` writers; the write
+        # belongs behind the model method or form-object PORO that owns the
+        # operation's validations.
+        #
+        # ## Rationale
+        # `collection_ids=` looks like plain attribute assignment but is not:
+        # on a persisted record it writes the join table IMMEDIATELY — no save
+        # call, no validations, no surrounding transaction. In a controller
+        # that produces two failure modes:
+        #
+        # - **Validation asymmetry.** The create path routes through a form
+        #   object whose validations guard the association (say, "at least one
+        #   tag"); a later-added update action assigns `record.tag_ids = ...`
+        #   directly, and every one of those guards silently stops existing on
+        #   the second write path. Nothing fails loudly — the update simply
+        #   never consults the rules that create enforces.
+        # - **Partial writes.** The association mutates even when the
+        #   surrounding operation fails afterwards: clear `record.tag_ids = []`
+        #   and then fail to save a status flag, and the two halves are left
+        #   inconsistent with no transaction to roll the join rows back.
+        #
+        # Both are the data-saving-orchestration placement rule (see the
+        # orchestration best-practice doc, category 1) wearing an assignment
+        # costume: which rows must land together, and under which guards, is
+        # domain knowledge. Move the write into a model method or the
+        # form-object PORO that owns the operation's validations, so updates
+        # travel the same validation path as creates.
+        #
+        #   ❌ Hand-rolled update path — join rows written before save!, guards skipped
+        #   def update
+        #     @article.category = update_params[:category]
+        #     @article.tag_ids = checked_tag_ids
+        #     @article.save!
+        #   end
+        #
+        #   ✔️ The model method owns the write and its guards
+        #   def update
+        #     @article.update_with_tags!(update_params, tag_ids: checked_tag_ids)
+        #   end
+        #
+        # ## Relationship with DevDoc/Rails/AvoidBypassingValidation
+        # Same bypass family, different signal: that cop matches a fixed list
+        # of ActiveRecord method names repo-wide, while `*_ids=` is a NAME
+        # PATTERN that is perfectly legitimate on form objects (common under
+        # `app/models/`). The pattern is only dependable where a direct ids
+        # write is either a validation bypass or misplaced orchestration —
+        # controllers — so it lives in this scoped cop instead.
+        #
+        # ## Exception
+        # The receiver's type is statically invisible, so this cop flags every
+        # `*_ids=` spelling, including ones that persist nothing: an `ActiveModel`
+        # form object, a not-yet-saved record (its ids apply at save time, under
+        # validations), or a non-AR object such as a presenter or OpenStruct.
+        # Those are ordinary params→object binding (orchestration category 2) —
+        # disable inline, naming why nothing persists:
+        #
+        #   # rubocop:disable DevDoc/Rails/NoCollectionIdsWriterInController
+        #   # -- ArticleImport is an ActiveModel PORO; nothing persists
+        #
+        #   # rubocop:disable DevDoc/Rails/NoCollectionIdsWriterInController
+        #   # -- @article is built in this action and unsaved; ids apply at save,
+        #   #    under validations
+        #
+        # NOTE: Spellings with the same immediate-write behavior that this cop
+        # cannot see, for reviewers: the plain collection writer
+        # (`record.tags = [...]`) — indistinguishable from an attribute write —
+        # a STANDALONE `assign_attributes(tag_ids: [...])` on a persisted record
+        # (mass assignment invokes the same writer, with no transaction around
+        # it), and dynamic dispatch (`record.send(:tag_ids=, x)`). By contrast,
+        # `update`/`update!` with an ids key is NOT in this class: Rails wraps
+        # assign_attributes + save in a transaction precisely so those join-row
+        # writes roll back when validations fail (see the comment inside
+        # `ActiveRecord::Persistence#update!`).
+        #
+        # @example
+        #   # bad
+        #   @article.tag_ids = checked_tag_ids
+        #
+        #   # bad
+        #   article&.tag_ids = []
+        #
+        #   # bad — op-assign calls the same writer
+        #   @article.tag_ids += [tag.id]
+        #
+        #   # good — the model method owns the write and its validations
+        #   @article.update_with_tags!(update_params, tag_ids: checked_tag_ids)
+        class NoCollectionIdsWriterInController < Base
+          MSG = '`%<method>s` in a controller — on a persisted record a collection `_ids=` writer ' \
+                'updates the join table immediately, skipping the owner\'s save and validations. Move the ' \
+                'write into the model method or form-object PORO that owns the operation\'s validations.'.freeze
+
+          # Dynamic name pattern, so RESTRICT_ON_SEND cannot apply (it is
+          # static); the filter runs inside on_send instead.
+          IDS_WRITER = /\A\w+_ids=\z/
+
+          def on_send(node)
+            return unless node.assignment_method?
+            return unless IDS_WRITER.match?(node.method_name.to_s)
+
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+
+          # Safe navigation (`record&.tag_ids = x`) parses as a csend node that
+          # on_send does not receive — alias it so `&.` is caught too.
+          alias on_csend on_send
+
+          # Op-assigns (`record.tag_ids += [x]`, `||=`, `&&=`) call the same
+          # writer but parse as op_asgn/or_asgn/and_asgn nodes whose inner send
+          # is the READER (`tag_ids`, no `=`), so on_send never sees a match.
+          def on_op_asgn(node)
+            lhs = node.children.first
+            return unless lhs.type?(:send, :csend)
+
+            writer = "#{lhs.method_name}="
+            return unless IDS_WRITER.match?(writer)
+
+            add_offense(lhs.loc.selector, message: format(MSG, method: writer))
+          end
+          alias on_or_asgn on_op_asgn
+          alias on_and_asgn on_op_asgn
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Flag hand-raised (or hand-constructed) `ActiveRecord::RecordInvalid`
+        # in model code. Only Active Record's own bang persistence
+        # (`save!`/`create!`/`update!`) should raise it.
+        #
+        # ## Rationale
+        # `RecordInvalid` is the exception Active Record raises when a bang
+        # persistence call fails validation. Raising it by hand to signal a
+        # domain precondition ("only drafts can be approved") borrows the
+        # framework's exception to smuggle soft-failure data (the errors on
+        # the record) through a raise — and the caller then needs a rescue
+        # plus a comment explaining that the errors are already on the model.
+        # The soft shape says the same thing without the detour: add the
+        # error, return false, and let the caller check the result and render
+        # `record.errors` exactly as it does for a plain failed `save`.
+        #
+        #   ❌ hand-raised to reuse the rescue/rendering machinery
+        #   def approve!
+        #     errors.add(:base, 'Only drafts can be approved') unless draft?
+        #     raise ActiveRecord::RecordInvalid.new(self) if errors.any?
+        #
+        #     update!(approved_at: Time.current)
+        #   end
+        #
+        #   ✔️ soft failure — the caller checks the return and renders errors
+        #   def approve
+        #     unless draft?
+        #       errors.add(:base, 'Only drafts can be approved')
+        #       return false
+        #     end
+        #     self.approved_at = Time.current
+        #     save
+        #   end
+        #
+        # ## Relationship with `DevDoc/Rails/SoftFailureInBangMethod`
+        # The two cops close the two spellings of the same confusion: that one
+        # catches soft failure hiding under a raising name; this one catches a
+        # raise simulating a validation failure. Together they funnel
+        # controller-invoked domain actions to the soft non-bang shape.
+        #
+        # ## Exception
+        # Re-raising a rescued `RecordInvalid` (`raise e`, or a bare `raise`
+        # inside the rescue) is not flagged — the exception originated in
+        # Active Record, not by hand. A genuine need to construct one (for
+        # example, aborting a batch import through machinery that renders
+        # `RecordInvalid` specifically) takes an inline disable stating the
+        # reason.
+        #
+        # NOTE: Indirection is not detected — the class stashed in a variable
+        # before raising, or an app-defined `RecordInvalid` subclass —
+        # reviewers must cover those.
+        class NoManualRecordInvalid < Base
+          MSG = 'Do not raise `ActiveRecord::RecordInvalid` by hand — only Active Record persistence ' \
+                '(`save!`, `create!`) should raise it. Signal domain failure softly: add to `errors` ' \
+                'and return false.'.freeze
+
+          RESTRICT_ON_SEND = %i[new raise fail].freeze
+
+          def_node_matcher :record_invalid_const?, <<~PATTERN
+            (const (const {nil? cbase} :ActiveRecord) :RecordInvalid)
+          PATTERN
+
+          def on_send(node)
+            if node.method_name == :new
+              return unless record_invalid_const?(node.receiver)
+            else
+              return unless node.receiver.nil?
+
+              # `raise ActiveRecord::RecordInvalid.new(...)` is already flagged
+              # at the `.new` itself; this branch covers the class-only form
+              # `raise ActiveRecord::RecordInvalid`.
+              argument = node.first_argument
+              return unless argument && record_invalid_const?(argument)
+            end
+
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,210 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Flag a `!`-named model method that signals failure softly — errors on
+        # the record and a falsy return instead of a raise. Soft failure is
+        # `save` semantics and belongs to a non-bang name.
+        #
+        # ## Rationale
+        # By convention a `!` method signals failure by raising, the way
+        # `save!`/`create!` do (`DevDoc/Style/RedundantGuardAfterBang` polices
+        # call sites under the same assumption). Rails' non-bang `save` is the
+        # opposite contract: validation errors land on the record, the call
+        # returns false, and the caller — typically a controller rendering
+        # `record.errors` — checks the result. A domain-action method that
+        # wears the `!` while failing softly mixes the two contracts: callers
+        # cannot tell whether to rescue or to check the return value, call
+        # sites accrete rescue blocks and comments explaining what the name
+        # should have said, and the naming convention other code relies on
+        # stops being trustworthy.
+        #
+        # Controller-invoked domain actions (finalize, publish, approve, ...)
+        # should normally take the soft shape under a non-bang name: assign
+        # attributes, add any precondition errors, return `save`'s boolean —
+        # the controller then renders the errors exactly as it does for a
+        # plain failed `save`, with no rescue. Reserve the `!` for methods
+        # that raise on failure (delegating to `save!`/`update!` is the common
+        # case), for callers — jobs, migrations, internal invariants — that
+        # want the exception.
+        #
+        #   ❌ soft failure under a bang name — the `!` lies
+        #   def publish!
+        #     if archived?
+        #       errors.add(:base, 'Archived posts cannot be published')
+        #       return
+        #     end
+        #     self.published_at = Time.current
+        #     save
+        #   end
+        #
+        #   ❌ return-gated non-bang save under a bang name — same lie
+        #   def archive!
+        #     self.archived_at = Time.current
+        #     transaction do
+        #       next unless save
+        #       items.each { |item| item.update!(archived: true) }
+        #     end
+        #   end
+        #
+        #   ✔️ same behavior, honest name — `save` semantics, non-bang
+        #   def publish
+        #     if archived?
+        #       errors.add(:base, 'Archived posts cannot be published')
+        #       return false
+        #     end
+        #     self.published_at = Time.current
+        #     save
+        #   end
+        #
+        #   ✔️ raising bang — the `!` is earned
+        #   def publish!
+        #     raise ArgumentError, 'already archived' if archived?
+        #
+        #     update!(published_at: Time.current)
+        #   end
+        #
+        # A bang-named custom validator that adds errors by design should
+        # simply drop its `!` — validators are the canonical soft-failure
+        # shape.
+        #
+        # ## Relationship with `DevDoc/Rails/NoManualRecordInvalid`
+        # The two cops close the two spellings of the same confusion. This cop
+        # catches soft failure hiding under a raising name; that one catches a
+        # hand-raised `ActiveRecord::RecordInvalid` simulating a validation
+        # failure. Together they funnel controller-invoked domain actions to
+        # the soft non-bang shape, while leaving genuinely raising bang
+        # methods untouched.
+        #
+        # NOTE: Only a literal `raise`/`fail` (`Kernel.`-qualified included)
+        # in the method's own body counts as raise semantics — a nested `def`
+        # is a separate method whose raises and soft signals both stay its
+        # own. Delegating to `save!` on the happy path does NOT excuse an
+        # `errors.add`-and-return on a precondition path — that mixed
+        # contract is exactly what this cop exists to catch. Blind spots
+        # reviewers must cover: soft failure hidden entirely in a callee
+        # (the method returns a callee's false without touching `errors`),
+        # a persistence boolean stashed in a variable before branching,
+        # methods defined via `define_method`/DSL, and failure signalled
+        # through a custom exception swallowed internally.
+        class SoftFailureInBangMethod < Base
+          MSG = 'Bang method `%<method>s` %<signal>s — a `!` name promises raise-on-failure. ' \
+                'Drop the `!` (soft `save` semantics), or raise on the failing path.'.freeze
+
+          # `create` is omitted: receiverless `create` in an instance method is
+          # not a persistence call on self.
+          SOFT_PERSISTENCE = %i[save update destroy].freeze
+
+          # Writes to self's own errors only; `other_record.errors.add` is a
+          # statement about another object, not this method's failure contract.
+          def_node_matcher :own_errors_write?, <<~PATTERN
+            ({send csend} ({send csend} {nil? self} :errors) {:add :import} ...)
+          PATTERN
+
+          def_node_matcher :own_soft_persistence?, <<~PATTERN
+            ({send csend} {nil? self} {:save :update :destroy} ...)
+          PATTERN
+
+          # `Kernel.raise`/`::Kernel.raise` is the same raise, spelled
+          # explicitly.
+          def_node_matcher :raising_call?, <<~PATTERN
+            (send {nil? (const {nil? cbase} :Kernel)} {:raise :fail} ...)
+          PATTERN
+
+          def on_def(node)
+            return unless bang_name?(node.method_name)
+            return if node.body.nil?
+            return if contains_raise?(node)
+
+            signal = soft_signal(node)
+            return unless signal
+
+            add_offense(node.loc.name, message: format(MSG, method: node.method_name, signal: signal))
+          end
+          alias on_defs on_def
+
+          private
+
+          # The unary negation operator defines as `def !`, which is not a
+          # bang method.
+          def bang_name?(name)
+            string = name.to_s
+            string.end_with?('!') && string != '!'
+          end
+
+          # Any literal raise/fail (Kernel-qualified included) means the
+          # method enforces raise semantics on some path; path-sensitive
+          # analysis is not attempted.
+          def contains_raise?(node)
+            each_own_send(node).any? { |sent| raising_call?(sent) }
+          end
+
+          def soft_signal(node)
+            return 'sets `errors` without raising' if each_own_send(node).any? { |sent| own_errors_write?(sent) }
+
+            gated = each_own_send(node).find do |sent|
+              own_soft_persistence?(sent) && condition_position?(sent, node)
+            end
+            return unless gated
+
+            format('branches on non-bang `%<name>s` instead of raising', name: gated.method_name)
+          end
+
+          # Sends belonging to this method body only — a nested def (inside a
+          # metaprogrammed class body, etc.) is its own method with its own
+          # contract, so neither its raises nor its soft signals count here.
+          def each_own_send(def_node)
+            def_node.each_descendant(:send, :csend).select do |sent|
+              sent.each_ancestor(:def, :defs).first.equal?(def_node)
+            end
+          end
+
+          # True when the call's boolean flows into a branch condition
+          # (`if save`, `next unless save`, `save && ...`) — the soft-failure
+          # idiom. The walk crosses only value-transparent wrappers
+          # (parentheses, `!`), so a call whose value is discarded inside a
+          # block or consumed as an argument is not a signal; a bare
+          # discarded `save` is BangSaveInTransaction's territory, not a
+          # naming signal.
+          def condition_position?(node, def_node)
+            child = node
+            node.each_ancestor do |ancestor|
+              return false if boundary?(ancestor, def_node)
+
+              verdict = branch_verdict(ancestor, child)
+              return verdict unless verdict.nil?
+
+              child = ancestor
+            end
+            false
+          end
+
+          def boundary?(ancestor, def_node)
+            ancestor.equal?(def_node) || ancestor.def_type? || ancestor.defs_type?
+          end
+
+          # true/false end the walk; nil crosses a value-transparent wrapper
+          # (parentheses, `!`) and continues with the wrapper as the child.
+          def branch_verdict(ancestor, child)
+            case ancestor.type
+            when :and, :or then true
+            when :if, :while, :until, :while_post, :until_post, :case
+              condition_of?(ancestor, child)
+            when :begin, :kwbegin then nil
+            when :send, :csend then negation_of?(ancestor, child) ? nil : false
+            else false
+            end
+          end
+
+          def condition_of?(ancestor, child)
+            !ancestor.condition.nil? && ancestor.condition.equal?(child)
+          end
+
+          def negation_of?(ancestor, child)
+            ancestor.method_name == :! && !ancestor.receiver.nil? && ancestor.receiver.equal?(child)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.14.0".freeze
+    VERSION = "0.16.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -143,10 +143,13 @@ files:
 - lib/rubocop/cop/dev_doc/rails/enum_column_not_null.rb
 - lib/rubocop/cop/dev_doc/rails/enum_must_be_symbolized.rb
 - lib/rubocop/cop/dev_doc/rails/no_block_predicate_on_relation.rb
+- lib/rubocop/cop/dev_doc/rails/no_collection_ids_writer_in_controller.rb
 - lib/rubocop/cop/dev_doc/rails/no_deliver_later_in_transaction.rb
+- lib/rubocop/cop/dev_doc/rails/no_manual_record_invalid.rb
 - lib/rubocop/cop/dev_doc/rails/no_perform_later_in_model.rb
 - lib/rubocop/cop/dev_doc/rails/no_persistence_in_service.rb
 - lib/rubocop/cop/dev_doc/rails/no_transaction_in_controller.rb
+- lib/rubocop/cop/dev_doc/rails/soft_failure_in_bang_method.rb
 - lib/rubocop/cop/dev_doc/rails/strong_parameters_expect.rb
 - lib/rubocop/cop/dev_doc/route/no_custom_actions.rb
 - lib/rubocop/cop/dev_doc/route/resource_name_number.rb