rubocop-dev_doc 0.12.1 → 0.13.0

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

@@ -0,0 +1,168 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Classes under `app/services/` must not persist domain records, open
+        # transactions, or enqueue jobs/mailers.
+        #
+        # ## Rationale
+        # `app/services/` is reserved for external-boundary adapters: clients for
+        # third-party APIs, storage backends, and their test doubles. An adapter
+        # talks to an external system and returns data. Anything more is domain
+        # orchestration, and its home routes by what is being orchestrated (see
+        # the orchestration best-practice doc):
+        #
+        # - Transactions and record writes are data-saving orchestration. Home:
+        #   a domain-named `ActiveModel::Model` PORO under `app/models/` (see
+        #   the model best-practice doc) or a method on the model that owns the
+        #   data.
+        # - Enqueues (jobs, mailer sends) are execution-flow control. Home: the
+        #   calling controller or job entry point — ordering is then enforced by
+        #   data flow, because the trigger runs only after the domain call
+        #   returns post-commit. The one exception: an enqueue inseparable from
+        #   a record state change lives in the model behind an explicitly named
+        #   `notify_*`/`send_*` method with a justified per-line disable of
+        #   `DevDoc/Rails/NoPerformLaterInModel`.
+        #
+        # Keeping domain writes out of `app/services/` prevents the "fake-generic
+        # service" failure mode: a `*Service` class with one caller whose generic
+        # name and location advertise reusability it does not have, and whose
+        # existence bypasses the conventions (form-object POROs, model methods,
+        # concerns) the project actually uses for domain logic.
+        #
+        #   ❌
+        #   # app/services/orders/publish_service.rb
+        #   class Orders::PublishService
+        #     def call
+        #       Order.transaction do
+        #         @order.save!
+        #         OrderMailer.with(order: @order).published.deliver_later
+        #       end
+        #     end
+        #   end
+        #
+        #   ✔️
+        #   # app/models/orders/publish.rb — domain PORO owns the transaction and writes,
+        #   # and RETURNS; it does not enqueue (that would trip NoPerformLaterInModel)
+        #   class Orders::Publish
+        #     include ActiveModel::Model
+        #
+        #     def save
+        #       Order.transaction { @order.save! }
+        #     end
+        #   end
+        #
+        #   # app/controllers/orders_controller.rb — the caller triggers the send;
+        #   # it can only run after the PORO's transaction has committed
+        #   OrderMailer.with(order: publish.order).published.deliver_later if publish.save
+        #
+        #   ✔️
+        #   # app/services/payment_gateway.rb — adapter; external calls only
+        #   class PaymentGateway
+        #     def charge(amount_cents)
+        #       @client.post('/charges', amount: amount_cents)
+        #     end
+        #   end
+        #
+        # ## Configurable blocklist for write wrappers
+        # A service can hide its writes behind a model method that persists
+        # internally (e.g. an `add_member_if_missing`-style helper). The cop
+        # cannot see through arbitrary methods; register the known ones via
+        # `KnownWriteWrappers` so those sends flag too. This is a partial
+        # mitigation — reviewers must still catch unregistered wrappers.
+        #
+        # NOTE: Two residuals the cop cannot catch — reviewers own both:
+        # - A service whose writes all go through wrapper methods not listed in
+        #   `KnownWriteWrappers`.
+        # - Read-only domain logic parked in `app/services/` (queries, catalogs,
+        #   pure utilities). Nothing persists, so nothing flags — but its home is
+        #   still `app/models/` or `lib/`.
+        # `Hash#delete` / `Array#insert` collisions are why bare `delete` /
+        # `insert` are not in the tracked list; `delete_all` / `insert_all` are.
+        # Bare `update` IS tracked despite `Hash#update` (a `merge!` alias):
+        # ActiveRecord `update` is a far more common sight in a service than a
+        # Hash mutation, so the rare Hash collision is accepted (disable inline
+        # with a reason) rather than losing detection of `record.update`.
+        #
+        # @example
+        #   # bad
+        #   ApplicationRecord.transaction { order.save! }
+        #
+        #   # bad
+        #   user.folders.find_or_create_by!(name: 'Default')
+        #
+        #   # bad
+        #   OrderMailer.with(order: order).published.deliver_later
+        #
+        #   # good — adapter work: external API call, no domain persistence
+        #   @client.post('/charges', amount: amount_cents)
+        class NoPersistenceInService < Base
+          # Two messages, routed per the orchestration taxonomy: persistence and
+          # transactions move to the model layer; enqueues move to the caller.
+          MSG = '`%<method>s` in app/services — services are external-boundary ' \
+                'adapters and must not persist domain records or enqueue jobs. ' \
+                'Move this into a domain object under app/models.'.freeze
+          ENQUEUE_MSG = '`%<method>s` in app/services — services are external-boundary ' \
+                        'adapters and must not enqueue jobs or send mail. Return data and ' \
+                        'let the calling controller or job trigger the send.'.freeze
+
+          # `with_lock` opens a transaction too (see NoDeliverLaterInTransaction);
+          # an enqueue/write inside it is the same violation in a service.
+          TRANSACTION_METHODS = %i[transaction with_lock].freeze
+
+          # ActiveRecord persistence. Non-bang forms and the find-or-create
+          # family are included (an observed violation used find_or_create_by!).
+          # `delete` and `insert` are deliberately ABSENT: Hash#delete /
+          # Array#insert are common enough to flood false positives;
+          # `delete_all` / `insert_all` remain.
+          PERSISTENCE_METHODS = %i[
+            save save! create create! update update! update_all
+            update_column update_columns update_attribute
+            destroy destroy! destroy_all delete_all
+            insert_all insert_all! upsert upsert_all
+            find_or_create_by find_or_create_by! create_or_find_by create_or_find_by!
+            first_or_create first_or_create! touch increment! decrement! toggle!
+          ].freeze
+
+          # Enqueues/sends — mirror NoDeliverLaterInTransaction::CORE_METHODS,
+          # plus deliver_now (an adapter must not send mail synchronously either).
+          ENQUEUE_METHODS = %i[
+            deliver_later deliver_later! deliver_now perform_later perform_all_later enqueue
+          ].freeze
+
+          # Union of the three fixed lists, pre-computed once for O(1) membership.
+          # KnownWriteWrappers (config) are matched separately as strings — see
+          # tracked_method?.
+          TRACKED_METHODS = (TRANSACTION_METHODS + PERSISTENCE_METHODS + ENQUEUE_METHODS).freeze
+
+          # Config-driven (KnownWriteWrappers), so do NOT use RESTRICT_ON_SEND
+          # (CONTRIBUTING documents this exact exception). Filter inside on_send,
+          # mirroring NoDeliverLaterInTransaction#tracked_method?.
+          def on_send(node)
+            name = node.method_name
+            return unless tracked_method?(name)
+
+            msg = ENQUEUE_METHODS.include?(name) ? ENQUEUE_MSG : MSG
+            add_offense(node.loc.selector, message: format(msg, method: name))
+          end
+
+          # Safe navigation (`a&.save!`) parses as a `csend` node that on_send
+          # does not receive — alias it so `&.` persistence/enqueue/transaction
+          # is caught too. `node.method_name` / `node.loc.selector` are valid on
+          # csend, so the on_send body needs no change.
+          alias on_csend on_send
+
+          private
+
+          def tracked_method?(name)
+            TRACKED_METHODS.include?(name) || known_write_wrappers.include?(name.to_s)
+          end
+
+          def known_write_wrappers
+            cop_config.fetch('KnownWriteWrappers', [])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Controllers must not open transactions (`transaction` / `with_lock`);
+        # a transaction boundary belongs in the model layer.
+        #
+        # ## Rationale
+        # A transaction boundary encodes a domain invariant: which records must
+        # land together for the data to stay consistent. That knowledge belongs
+        # to the layer that owns the data — an ActiveRecord model method or a
+        # domain `ActiveModel::Model` PORO under `app/models/` (see the model
+        # and orchestration best-practice docs). The controller owns request
+        # concerns: param binding, authorization, and deciding *when* to
+        # trigger the operation — not *what* must commit atomically.
+        #
+        # `with_lock` opens a transaction too (see
+        # `DevDoc/Rails/NoDeliverLaterInTransaction`), so it is tracked as well.
+        #
+        #   ❌
+        #   # app/controllers/orders_controller.rb
+        #   def create
+        #     ApplicationRecord.transaction do
+        #       @order.save!
+        #       @order.line_items.create!(line_item_rows)
+        #     end
+        #   end
+        #
+        #   ✔️
+        #   # app/controllers/orders_controller.rb — one call; the model owns the boundary
+        #   def create
+        #     @order.assign_attributes(create_params)
+        #     @order.save_with_line_items!(line_item_rows)
+        #   end
+        #
+        # ## Relationship with DevDoc/Rails/ApplicationRecordTransaction
+        # That cop governs the *spelling* of transactions in the places they
+        # remain legitimate outside `app/models/` (jobs, rake tasks); this cop
+        # removes controllers from that set entirely. Once the write sequence
+        # moves under `app/models/`, that cop's `app/models` exclusion applies
+        # and `SomeModel.transaction` is the sanctioned spelling again.
+        #
+        # ## Exception
+        # Jobs and rake tasks are asynchronous entry points and may open
+        # transactions (the job best-practice doc assumes idempotent writes);
+        # they are out of scope via `Include`. When adopting this cop on an
+        # existing codebase with a backlog, pin it off by name with a measured
+        # backlog comment and schedule the migration as its own wave.
+        #
+        # NOTE: Limitations — reviewers own both:
+        # - A transaction opened inside a non-model helper the controller calls
+        #   (e.g. a `lib/` utility wrapping a block in a transaction) is
+        #   invisible to this cop.
+        # - Receiver-agnostic matching means a domain reader genuinely named
+        #   `transaction` (e.g. `payment.transaction` returning an associated
+        #   record) false-positives — disable inline with a reason.
+        #
+        # @example
+        #   # bad
+        #   ApplicationRecord.transaction do
+        #     order.save!
+        #     order.line_items.create!(rows)
+        #   end
+        #
+        #   # bad
+        #   member.with_lock { member.upgrade! }
+        #
+        #   # good — the model or domain PORO owns the transaction
+        #   order.save_with_line_items!(rows)
+        class NoTransactionInController < Base
+          MSG = '`%<method>s` in a controller — a transaction boundary is data-saving ' \
+                'orchestration and belongs to the layer that owns the domain invariant. Move the ' \
+                'write sequence into a model method or domain PORO under app/models.'.freeze
+
+          # Fixed two-method set, so RESTRICT_ON_SEND applies (unlike the
+          # config-driven NoPersistenceInService). Receiver-agnostic: any
+          # receiver spelling (`ApplicationRecord.`, `SomeModel.`, bare) opens
+          # the same boundary.
+          RESTRICT_ON_SEND = %i[transaction with_lock].freeze
+
+          def on_send(node)
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+
+          # Safe navigation (`record&.with_lock`) parses as a csend node that
+          # on_send does not receive — alias it so `&.` is caught too.
+          alias on_csend on_send
+        end
+      end
+    end
+  end
+end

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

@@ -25,6 +25,18 @@ module RuboCop
         # one only when you are sure a controller test genuinely cannot reach the
         # path, not because it is quicker to write.
         #
+        # And even when a controller genuinely can't reach a path, a unit test is
+        # warranted only if SOME entry point — a request or a job — can. A defect no
+        # legitimate path can trigger is not a live bug; it is theoretical. Countless
+        # variables could be nil in isolation yet never are, because the caller already
+        # guaranteed otherwise — chase one such unreachable case with a test and a
+        # nil-guard and you owe the same for a million more. If nothing reaches the
+        # path, the "bug" is dead code: work out how to REMOVE it, don't just
+        # record it as "known safe". Removal is usually surgical — the dead part
+        # (a redundant branch, an unreachable warn), not the whole method; reach
+        # for a "why it is safe" comment only when removal isn't clean. Accepting
+        # dead code is how this class of bug hides in the first place.
+        #
         # This cop flags only the literal `< ActiveSupport::TestCase`
         # superclass. The blessed blackbox bases —
         # `ActionDispatch::IntegrationTest`, `Glib::IntegrationTest`,

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

@@ -43,7 +43,12 @@ module RuboCop
         #    comes from); stock phrases ("the controller merely surfaces the
         #    model's errors") do not count, and a header that misstates the
         #    mechanism is worse than none — verify the claim by tracing the
-        #    write path before writing it. Base classes are allowlisted here
+        #    write path before writing it. The entry point named must be REAL:
+        #    trace that a request or job actually reaches the path — if nothing
+        #    does, there is nothing to wire (the "defect" is dead code, not a
+        #    live bug — remove it, usually just the dead part rather than the
+        #    whole method; comment only if removal isn't clean). Base classes
+        #    are allowlisted here
         #    (`RequireUnitBase`, default true): a *Test class must subclass a
         #    `UnitBaseClasses` member — plain ActiveSupport::TestCase is
         #    rejected as an unexamined default, so the confession base is

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.12.1".freeze
+    VERSION = "0.13.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-13 00:00:00.000000000 Z
+date: 2026-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -93,15 +93,23 @@ files:
 - lib/dev_doc/test/lints/cop_drift_check.rb
 - lib/dev_doc/test/lints/cop_drift_test.rb
 - lib/dev_doc/test/lints/cron_schedule.rb
+- lib/dev_doc/test/lints/cross_tenant_canary_check.rb
+- lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb
 - lib/dev_doc/test/lints/duplicate_snapshot.rb
+- lib/dev_doc/test/lints/enqueue_disable_naming.rb
+- lib/dev_doc/test/lints/external_io_boundary.rb
 - lib/dev_doc/test/lints/http_driven_controller_tests.rb
 - lib/dev_doc/test/lints/no_file_excludes.rb
 - lib/dev_doc/test/pseudo_i18n_crawler.rb
 - lib/rubocop-dev_doc.rb
+- lib/rubocop/cop/dev_doc/auth/adjacent_justification.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching_helpers.rb
 - lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb
+- lib/rubocop/cop/dev_doc/auth/login_only_policy_justification.rb
+- lib/rubocop/cop/dev_doc/auth/no_record_presence_in_policy.rb
 - lib/rubocop/cop/dev_doc/auth/role_predicate_outside_policy.rb
+- lib/rubocop/cop/dev_doc/auth/unscoped_find_justification.rb
 - lib/rubocop/cop/dev_doc/i18n/avoid_titleize_humanize.rb
 - lib/rubocop/cop/dev_doc/i18n/localizable_props.rb
 - lib/rubocop/cop/dev_doc/i18n/report_text.rb
@@ -132,6 +140,8 @@ files:
 - 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_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/strong_parameters_expect.rb
 - lib/rubocop/cop/dev_doc/route/no_custom_actions.rb
 - lib/rubocop/cop/dev_doc/route/resource_name_number.rb