rubocop-dev_doc 0.12.2 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4840aa1ca5c8a4ee2f5dfcb5b2e6880dbe7966d451b8502e0983e8eb63e9b04c
-  data.tar.gz: 4cc9d0f5a9e352f4b361b831250e5683242a0b35578b8abb43eb3535a18c9a1c
+  metadata.gz: c36d2d77bcdffd7f74968817e83dbdb75134e3e3d63b953127e4475f7c1841f9
+  data.tar.gz: db6ef7a22d41f10f30e6e6ffedfdb1c7605bc849907290930f9d1eae4f0c49b4
 SHA512:
-  metadata.gz: 8c66389a73be82ba697f12708c89023851dc246caa0b3439a389948c8490b0b903a8dd14b90e7f54fa33698bc5e441fe50db7465d5d808e46db72086da0a5305
-  data.tar.gz: 69fd78aefb3b759863f7a45e3de18bb84bdccf52e1485a4dac0ea9151e0790fcbfa13c1a45d6dffd79bd6fbfff478020231b8b5aafc1d3e9f7a21b2668437fbf
+  metadata.gz: a874f22bc4773c0abaeb6de19587b5c1934061d40fb608831b2c725d060acdc39c8817689f38cab35041d1a67d99cfc12daf995a4bc3780fcc91a4f99901dfcb
+  data.tar.gz: 9966867628667e9fee6dd869345d1943e936db024a426b6dbd7433f14ae93396c5d8edeffba3a97b1259aac8f831ada7f288d93fdfceb14c34b4893d03fe613d

data/config/default.yml

@@ -169,6 +169,25 @@ DevDoc/Rails/NoPerformLaterInModel:
   Include:
     - "app/models/**/*.rb"
 
+DevDoc/Rails/NoPersistenceInService:
+  Description: "app/services is for external-boundary adapters; domain persistence and transactions belong in a domain PORO or model method under app/models, enqueues at the calling controller/job."
+  Enabled: true
+  Include:
+    - "app/services/**/*.rb"
+  KnownWriteWrappers: []
+
+# Data-saving orchestration placement (see
+# best_practices/backend/en/12_orchestration.md): a transaction boundary
+# encodes which records must land together — a domain invariant owned by the
+# model layer, not the request layer. Jobs and rake tasks are deliberately
+# outside Include: they are asynchronous entry points and may transact
+# (best_practices/backend/en/08_job.md assumes idempotent writes).
+DevDoc/Rails/NoTransactionInController:
+  Description: "Controllers must not open transactions (`transaction`/`with_lock`); move the write sequence into a model method or domain PORO under app/models."
+  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

data/lib/dev_doc/test/best_practice_lints.rb

@@ -1,5 +1,7 @@
 require_relative 'lints/cron_schedule'
 require_relative 'lints/duplicate_snapshot'
+require_relative 'lints/enqueue_disable_naming'
+require_relative 'lints/external_io_boundary'
 require_relative 'lints/no_file_excludes'
 
 module DevDoc
@@ -24,6 +26,8 @@ module DevDoc
       def self.included(base)
         base.include Lints::CronSchedule
         base.include Lints::DuplicateSnapshot
+        base.include Lints::EnqueueDisableNaming
+        base.include Lints::ExternalIoBoundary
         base.include Lints::NoFileExcludes
       end
     end

data/lib/dev_doc/test/lints/enqueue_disable_naming.rb

@@ -0,0 +1,141 @@
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Framework-agnostic check: finds every inline disable of
+      # `DevDoc/Rails/NoPerformLaterInModel` under `app/models/` and returns
+      # offender descriptions for directives whose enclosing method name does
+      # not signal the enqueue (`notify_*` / `send_*` / `deliver_*`).
+      #
+      # Wrapped by the Minitest module `EnqueueDisableNaming` below — see that
+      # module for the rationale.
+      class EnqueueDisableNamingChecker
+        DIRECTIVE = %r{rubocop:(?:disable|todo)[^#]*DevDoc/Rails/NoPerformLaterInModel}
+        # Handles the inline-visibility form (`private def foo`) too — without
+        # it, a disable inside such a method would false-positive as
+        # "no enclosing method".
+        DEF_PATTERN = /\A(\s*)(?:private\s+|protected\s+|public\s+)?def\s+(?:self\.)?([a-zA-Z_][a-zA-Z0-9_]*[!?=]?)/
+
+        # Bare `notify`/`send`/`deliver` (with optional !/?) count too — the
+        # prefix convention is about the verb being first, not about
+        # requiring a suffix.
+        DEFAULT_NAME_PATTERN = /\A(?:notify|send|deliver)(?:_|[!?]?\z)/
+
+        def initialize(project_root, name_pattern: DEFAULT_NAME_PATTERN)
+          @project_root = Pathname(project_root)
+          @name_pattern = name_pattern
+        end
+
+        # Returns an Array<String> of offender descriptions, or `[]` when
+        # every disable sits inside a conforming method.
+        def offenders
+          Dir.glob(@project_root.join('app/models/**/*.rb')).flat_map do |path|
+            file_offenders(path)
+          end
+        end
+
+        private
+
+        def file_offenders(path)
+          lines = File.readlines(path)
+          lines.each_index.filter_map do |index|
+            next unless lines[index].match?(DIRECTIVE)
+
+            method_name = enclosing_method_name(lines, index)
+            next if method_name&.match?(@name_pattern)
+
+            described = method_name ? "method `#{method_name}`" : 'no enclosing method'
+            "  #{relative(path)}:#{index + 1}: #{described}"
+          end
+        end
+
+        # Nearest `def` above the directive that is still open at the
+        # directive's line — a def is closed by an `end` at (or left of) its
+        # own indentation. Indentation-based, which the standard Layout cops
+        # make reliable; an `end` inside a heredoc is the known blind spot.
+        def enclosing_method_name(lines, directive_index)
+          same_line = DEF_PATTERN.match(lines[directive_index])
+          return same_line[2] if same_line
+
+          (directive_index - 1).downto(0) do |i|
+            def_match = DEF_PATTERN.match(lines[i])
+            next unless def_match
+
+            return def_match[2] unless closed_before?(lines, i, directive_index, def_match[1].size)
+          end
+          nil
+        end
+
+        def closed_before?(lines, def_index, directive_index, def_indent)
+          ((def_index + 1)...directive_index).any? do |i|
+            end_match = /\A(\s*)end\b/.match(lines[i])
+            end_match && end_match[1].size <= def_indent
+          end
+        end
+
+        def relative(path)
+          Pathname(path).relative_path_from(@project_root).to_s
+        end
+      end
+
+      # Naming tripwire for the sanctioned `NoPerformLaterInModel` escape:
+      # every inline disable of that cop in `app/models/` must sit inside an
+      # explicitly named `notify_*` / `send_*` / `deliver_*` method.
+      #
+      # ## Rationale
+      # A model-level enqueue is legitimate only when it is inseparable from a
+      # record state change (see the orchestration best-practice doc,
+      # execution-flow category) — and the convention that makes that
+      # legitimate is TWO-part: a justified per-line disable AND an explicit
+      # method name that announces the side effect at every call site. The
+      # meta-guard (`Style/DisableCopsWithinSourceCodeDirective`) reviews who
+      # may disable; nothing machine-checks the naming half. This lint closes
+      # that: a disable inside `finalize` or at class level fails the suite.
+      #
+      # NOTE: Limitations:
+      # - Enclosing-method detection is indentation-based (reliable under the
+      #   standard Layout cops); an `end` keyword inside a heredoc between the
+      #   `def` and the directive can misattribute the method.
+      # - The lint validates the NAME only. Whether the enqueue is genuinely
+      #   state-coupled — the justification for the disable — stays with the
+      #   reviewer.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class (Rails test env). To
+      # change the accepted verb prefixes, redefine the constant on the test
+      # class:
+      #
+      #   class EnqueueDisableNamingTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::EnqueueDisableNaming
+      #     # ENQUEUE_METHOD_NAME_PATTERN = /\A(?:notify|send|deliver|dispatch)_/
+      #   end
+      module EnqueueDisableNaming
+        # Default verb prefixes. Per-project override: redefine the constant
+        # on the test class that includes this module.
+        ENQUEUE_METHOD_NAME_PATTERN = EnqueueDisableNamingChecker::DEFAULT_NAME_PATTERN
+
+        def test_model_enqueue_disables_sit_in_explicitly_named_methods
+          offenders = EnqueueDisableNamingChecker.new(
+            Rails.root,
+            name_pattern: self.class::ENQUEUE_METHOD_NAME_PATTERN
+          ).offenders
+
+          assert offenders.empty?, enqueue_disable_naming_message(offenders)
+        end
+
+        private
+
+        def enqueue_disable_naming_message(offenders)
+          "Inline disables of DevDoc/Rails/NoPerformLaterInModel are sanctioned " \
+            "only inside an explicitly named notify_*/send_*/deliver_* method — " \
+            "the name announces the side effect at every call site " \
+            "(backend/12_orchestration.md). Rename the enclosing method, or move " \
+            "the enqueue to the calling controller if it is not coupled to a " \
+            "record state change.\n\n" \
+            "Offenders:\n#{offenders.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/dev_doc/test/lints/external_io_boundary.rb

@@ -0,0 +1,132 @@
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Framework-agnostic check: scans Ruby sources under `app/` (excluding
+      # `app/services/`) for HTTP-client tokens and returns offender
+      # descriptions for every hit.
+      #
+      # Wrapped by the Minitest module `ExternalIoBoundary` below — see that
+      # module for the rationale.
+      class ExternalIoBoundaryChecker
+        # The generic Ruby HTTP-client surface. Provider SDKs (Stripe, AWS,
+        # etc.) are project vocabulary and belong in the per-project token
+        # override on the `ExternalIoBoundary` module, not here.
+        DEFAULT_HTTP_CLIENT_TOKENS = %w[
+          Net::HTTP Faraday HTTParty RestClient OpenURI URI.open Typhoeus Excon Curl
+        ].freeze
+
+        def initialize(project_root, tokens: DEFAULT_HTTP_CLIENT_TOKENS, allowed_paths: [])
+          @project_root = Pathname(project_root)
+          @tokens = tokens
+          @allowed_paths = allowed_paths
+        end
+
+        # Returns an Array<String> of offender descriptions
+        # ("  app/models/foo.rb:12: Net::HTTP"), or `[]` when the boundary
+        # holds. Token matching is boundary-aware, so `Net::HTTP` does not
+        # fire on `Net::HTTPSuccess` and `Curl` does not fire on `Curly`.
+        def offenders
+          ruby_files.flat_map { |path| file_offenders(path) }
+        end
+
+        private
+
+        def ruby_files
+          Dir.glob(@project_root.join('app/**/*.rb')).reject do |path|
+            relative = relative(path)
+            relative.start_with?('app/services/') ||
+              @allowed_paths.any? { |allowed| relative.start_with?(allowed) }
+          end
+        end
+
+        def file_offenders(path)
+          [].tap do |offenders|
+            File.foreach(path).with_index(1) do |line, lineno|
+              token = @tokens.find { |candidate| code_portion(line).match?(token_pattern(candidate)) }
+              offenders << "  #{relative(path)}:#{lineno}: #{token}" if token
+            end
+          end
+        end
+
+        # Comments never count: full-line comments are dropped, and trailing
+        # ` # ...` comments are stripped (string interpolation survives —
+        # `#{` has no space after the hash).
+        def code_portion(line)
+          line.sub(/\A\s*#.*/, '').sub(/\s#\s.*/, '')
+        end
+
+        def token_pattern(token)
+          /(?<![A-Za-z0-9_])#{Regexp.escape(token)}(?![A-Za-z0-9_])/
+        end
+
+        def relative(path)
+          Pathname(path).relative_path_from(@project_root).to_s
+        end
+      end
+
+      # External-I/O boundary tripwire: HTTP-client code must live only in
+      # `app/services/` adapters.
+      #
+      # ## Rationale
+      # External-I/O sequencing (requests, retries, provider fallback,
+      # pagination) is the one kind of orchestration whose home is
+      # `app/services/` — see `best_practices/backend/en/12_orchestration.md`.
+      # `DevDoc/Rails/NoPersistenceInService` enforces the inward half of that
+      # boundary (adapters cannot persist or enqueue); this lint enforces the
+      # outward half: no HTTP client leaks into models, controllers, jobs, or
+      # views, where it would be unmockable, untracked, and invisible to the
+      # adapter conventions. A tripwire rather than a cop because it guards an
+      # invariant that currently holds — there is nothing for a cop's
+      # observed-violation justification gate to measure.
+      #
+      # NOTE: Limitations:
+      # - Matching is textual (per line, comments stripped) over `app/**/*.rb`
+      #   only — an HTTP call assembled via `Object.const_get` or made from
+      #   `lib/` is invisible.
+      # - Only the generic Ruby HTTP clients are in the default token list;
+      #   add each provider SDK your project uses (e.g. `Stripe`) via the
+      #   per-project override.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class (Rails test env). To
+      # extend the token list or exempt a sanctioned path, redefine the
+      # constants on the test class:
+      #
+      #   class ExternalIoBoundaryTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::ExternalIoBoundary
+      #     # HTTP_CLIENT_TOKENS =
+      #     #   (ExternalIoBoundaryChecker::DEFAULT_HTTP_CLIENT_TOKENS + %w[Stripe]).freeze
+      #     # ALLOWED_EXTERNAL_IO_PATHS = %w[app/middleware/proxy.rb].freeze
+      #   end
+      module ExternalIoBoundary
+        # Defaults. Per-project override: redefine the constants on the test
+        # class that includes this module.
+        HTTP_CLIENT_TOKENS = ExternalIoBoundaryChecker::DEFAULT_HTTP_CLIENT_TOKENS
+        ALLOWED_EXTERNAL_IO_PATHS = [].freeze
+
+        def test_no_http_clients_outside_app_services
+          offenders = ExternalIoBoundaryChecker.new(
+            Rails.root,
+            tokens: self.class::HTTP_CLIENT_TOKENS,
+            allowed_paths: self.class::ALLOWED_EXTERNAL_IO_PATHS
+          ).offenders
+
+          assert offenders.empty?, external_io_boundary_message(offenders)
+        end
+
+        private
+
+        def external_io_boundary_message(offenders)
+          "HTTP-client code outside app/services — external-I/O sequencing " \
+            "belongs in an app/services adapter (backend/12_orchestration.md). " \
+            "Move the call behind an adapter that returns data; if this site is " \
+            "a sanctioned exception, add it to ALLOWED_EXTERNAL_IO_PATHS on the " \
+            "including test class with a comment.\n\n" \
+            "Offenders:\n#{offenders.join("\n")}"
+        end
+      end
+    end
+  end
+end

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

@@ -2,18 +2,32 @@ module RuboCop
   module Cop
     module DevDoc
       module Rails
-        # Avoid `perform_later` calls inside model files.
+        # Avoid `perform_later`/`deliver_later` calls inside model files.
         #
         # ## Rationale
-        # Avoid using ActiveJob inside Models, because:
+        # Enqueuing a job or mailer is execution-flow control — deciding *when*
+        # a side effect fires — and its home is the calling controller or job
+        # entry point (see the orchestration best-practice doc), because:
         #
         # - It is prone to conflicts between `transaction` and `perform_later`
         #   (the job may run before the transaction commits and read stale data
         #   — see `DevDoc/Rails/NoDeliverLaterInTransaction`).
-        # - Execution flow control should be done in the Controller, not in the
-        #   Model.
-        # - If it really must be done in the Model, name the method explicitly
-        #   so the side effect is obvious at the call site.
+        # - Flow control belongs to the Controller, not the Model. This governs
+        #   the *trigger* only: the mail itself stays composed in the Mailer
+        #   (parameters, templates — see the controller best-practice doc); the
+        #   controller merely calls `deliver_later`. Reuse across controllers
+        #   goes in a controller concern — DRY alone never justifies pushing a
+        #   trigger into a model.
+        # - The exception: an enqueue inseparable from a record state change
+        #   (e.g. a throttle stamp and its send that must never be split across
+        #   a boundary) stays in the model behind an explicitly named
+        #   `notify_*`/`send_*` method, so the side effect is obvious at the
+        #   call site.
+        #
+        # The boundary test: is the enqueue bound to a state change on this
+        # record, or is ordering already enforced by data flow (the caller can
+        # only enqueue with values that exist after the domain call returns)?
+        # The latter is flow control — trigger it from the controller.
         #
         #   ❌  (in app/models/order.rb)
         #   def finalize
@@ -21,18 +35,20 @@ module RuboCop
         #     OrderJob.perform_later(self)
         #   end
         #
-        #   ✔️ Explicit method name signals the side effect; reviewers
-        #     immediately see that this should not be called inside a
+        #   ✔️ State-coupled enqueue behind an explicit `notify_*` name; the
+        #     side effect is obvious at the call site, and reviewers
+        #     immediately see that this must not be called inside a
         #     `transaction` block.
-        #   def save_with_email_sending
-        #     save!
+        #   def notify_finalized
+        #     update!(finalize_notified_at: Time.current)
         #     OrderJob.perform_later(self)
         #   end
         #
         # NOTE: This cop flags *any* `perform_later` in `app/models/**/*.rb`,
         # including the legitimate "explicitly named method" case above. The
         # cop is intentionally conservative — disable per-line with a rubocop
-        # comment when you have deliberately followed the naming convention.
+        # comment stating the justification when you have deliberately followed
+        # the naming convention.
         #
         # @example
         #   # bad (in app/models/order.rb)
@@ -41,9 +57,9 @@ module RuboCop
         #     OrderJob.perform_later(self)
         #   end
         #
-        #   # good — explicit method communicates the side effect
-        #   def finalize_with_job
-        #     save!
+        #   # good — state-coupled enqueue behind an explicitly named method
+        #   def notify_finalized
+        #     update!(finalize_notified_at: Time.current)
         #     OrderJob.perform_later(self)
         #   end
         class NoPerformLaterInModel < Base

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.2".freeze
+    VERSION = "0.13.1".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.13.1
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-14 00:00:00.000000000 Z
+date: 2026-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -96,6 +96,8 @@ files:
 - 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
@@ -138,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