rubocop-dev_doc 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f6961dde0d54631bae2f2dae6325183cc678f81701aa06575abab88cc1b0f7b
-  data.tar.gz: cc20cca8c229dca80fbd57d9950794b71560ccb2c13e0ace82c9b6cab0a0c93c
+  metadata.gz: cad88b36f561dcd41b75c42c242bf3af1877081c6df2c43ffeeaf3edbdb9e712
+  data.tar.gz: ae68d462103ffb1bc792bf4cb7bc65e20ecd8eb773a7b729f0194b070833b487
 SHA512:
-  metadata.gz: cdf5e192d7d3b526311ca7e9b6d6d3d81a50b3a14d8bd9b4b4a5d4459c0ed4d34c4695e1087e109614cf6f5dc040a12b0e7686f4e4cf509e16f4c9b770a0ccfa
-  data.tar.gz: 3664cc36ac24eb3f1a0bd6061a3671c32695113d50dd87753a35ec13536d02330fa7f10c7188439e90726a9b3a80dac227205cbaf88f539cb668dd7d18ea628d
+  metadata.gz: 5a74d067f5e2f0e7ca71f6457a590db627cde1bfe30349bccedaa363b3f7d8a08dc503eb5e301d7056434a03c600fbd85e716f95054d74a98a74b02923e17bba
+  data.tar.gz: 8439d5bb064c8d5211213f2912a6815cc3b4fb26db881f7f0bcd844a7b00ff11bcb457ab4a754c4144758e4dd203263afb51e81b13e6c3c862e7b4ae496b3b5d

data/config/default.yml

@@ -986,6 +986,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/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.15.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.15.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -144,9 +144,11 @@ files:
 - 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_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