rubocop-dev_doc 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cad88b36f561dcd41b75c42c242bf3af1877081c6df2c43ffeeaf3edbdb9e712
-  data.tar.gz: ae68d462103ffb1bc792bf4cb7bc65e20ecd8eb773a7b729f0194b070833b487
+  metadata.gz: 11175a594b0adb68ca20c3e2ff0ef414d1136d55152cd010a8d95ee26601a759
+  data.tar.gz: 460f211f62e554bead8cd267a4c3e918159eccff748d2d03f0f06b56454d025e
 SHA512:
-  metadata.gz: 5a74d067f5e2f0e7ca71f6457a590db627cde1bfe30349bccedaa363b3f7d8a08dc503eb5e301d7056434a03c600fbd85e716f95054d74a98a74b02923e17bba
-  data.tar.gz: 8439d5bb064c8d5211213f2912a6815cc3b4fb26db881f7f0bcd844a7b00ff11bcb457ab4a754c4144758e4dd203263afb51e81b13e6c3c862e7b4ae496b3b5d
+  metadata.gz: 5b5a9ae0aed54ff1979d4deb8313ef53e0e8b3d831e9d3bbdabaf9c4d9c3897acd7486054cbd012222453c9e6dbcd0054821ea83ddac71c1231bc51d7be6072e
+  data.tar.gz: e6acacc3e7f65769104c90d5043a08c6385983ab6c9f38db8088ff30193044ac1cd6e14b365c1cbf521de52d445b84e9c4312f75e2dcb6ab93370077a8134bed

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
@@ -392,6 +403,18 @@ DevDoc/Rails/ApplicationRecordTransaction:
   Exclude:
     - "app/models/**/*.rb"
 
+DevDoc/Rails/ApplicationModelBase:
+  Description: "Inherit the app's ApplicationModel root instead of including ActiveModel::Model directly (three-way rule, backend/03_model.md item 9)."
+  # Disabled by default: requires the project to have an ApplicationModel root
+  # over glib-web's Glib::Model. Enable per project, scoped to app/models; the
+  # root itself and any engine-side base need excluding where they legitimately
+  # carry the include.
+  Enabled: false
+  Include:
+    - "app/models/**/*.rb"
+  Exclude:
+    - "app/models/application_model.rb"
+
 DevDoc/Style/AvoidOptionsHash:
   Description: "Use keyword arguments instead of `**options` — typos raise `ArgumentError`; options hashes swallow them silently."
   Enabled: true

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

@@ -0,0 +1,138 @@
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Runtime check: every CLASS defined by a file under `app/models/`
+      # (excluding `concerns/`) must descend from one of the project's domain
+      # base classes. Runs with the app loaded, so real ancestry is checked —
+      # intermediate family bases and indirect inheritance resolve correctly,
+      # which is exactly what a per-file static cop cannot do.
+      #
+      # Wrapped by the Minitest module `DomainClassBase` below — see that
+      # module for the rationale.
+      class DomainClassBaseChecker
+        # The three-way rule (best_practices/backend/en/03_model.md item 9):
+        # persisted -> ApplicationRecord; table-less but form-backed ->
+        # ApplicationModel; plain domain logic -> PlainModel.
+        DEFAULT_BASE_CLASS_NAMES = %w[ApplicationRecord ApplicationModel PlainModel].freeze
+
+        def initialize(project_root, base_class_names: DEFAULT_BASE_CLASS_NAMES, allowed_paths: [])
+          @project_root = Pathname(project_root)
+          @base_class_names = base_class_names
+          @allowed_paths = allowed_paths
+        end
+
+        # Returns an Array<String> of offender descriptions, or `[]` when
+        # every model class descends from an allowed base. Modules are skipped:
+        # the three-way rule classifies CLASSES — namespaces, function-bag
+        # modules, and concerns carry no instance state to classify.
+        def offenders
+          bases = @base_class_names.map(&:constantize)
+
+          model_files.filter_map do |path|
+            constant = constant_for(path)
+            next if constant.nil? # module or namespace-only file
+            next if bases.any? { |base| constant <= base }
+
+            "  #{relative(path)}: #{constant.name} < #{constant.superclass.name} — #{hint_for(constant)}"
+          end
+        end
+
+        private
+
+        def model_files
+          Dir.glob(@project_root.join('app/models/**/*.rb')).reject do |path|
+            relative = relative(path)
+            relative.start_with?('app/models/concerns/') ||
+              @allowed_paths.any? { |allowed| relative.start_with?(allowed) }
+          end
+        end
+
+        # Zeitwerk guarantees the file defines the constant its path names, so
+        # deriving it from the path (rather than parsing the source) is exact,
+        # and nested helper classes (e.g. error classes inside a model) are
+        # never enumerated.
+        def constant_for(path)
+          name = relative(path).delete_prefix('app/models/').delete_suffix('.rb').camelize
+          constant = name.constantize
+          constant.is_a?(Class) ? constant : nil
+        end
+
+        def hint_for(constant)
+          if constant.include?(ActiveModel::Model)
+            'it includes ActiveModel::Model, so inherit ApplicationModel instead'
+          else
+            'inherit PlainModel (or ApplicationRecord/ApplicationModel if it persists or backs a form)'
+          end
+        end
+
+        def relative(path)
+          Pathname(path).relative_path_from(@project_root).to_s
+        end
+      end
+
+      # Domain-class base tripwire: every class under `app/models/` must be one
+      # of the project's three kinds — persisted (ApplicationRecord),
+      # form-backed (ApplicationModel), or plain domain logic (PlainModel).
+      #
+      # ## Rationale
+      # The three-way rule (backend/03_model.md item 9) makes the author
+      # classify each domain class at creation time; the base's docstring then
+      # states the contract that kind carries. Static analysis cannot enforce
+      # totality — RuboCop sees one file at a time, so it cannot resolve
+      # whether `class Foo < SomeFamilyBase` ultimately reaches an allowed
+      # base. This lint checks real ancestry with the app loaded, so
+      # intermediate bases resolve and the rule is enforced literally.
+      # `Rails/ApplicationRecord` and `DevDoc/Rails/ApplicationModelBase`
+      # remain useful beside it for editor-time feedback on the two common
+      # direct mistakes.
+      #
+      # NOTE: Limitations:
+      # - Only classes whose files live under `app/models/` are checked; a
+      #   domain class parked elsewhere is invisible (placement itself is the
+      #   orchestration taxonomy's reviewer-owned residual).
+      # - Modules are skipped by design (namespaces, function-bag modules,
+      #   concerns) — the rule classifies classes.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class (Rails test env) in a
+      # project whose three bases exist. Override the constants on the test
+      # class to rename bases or exempt a sanctioned file:
+      #
+      #   class DomainClassBaseTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::DomainClassBase
+      #     # DOMAIN_BASE_CLASS_NAMES = %w[ApplicationRecord ApplicationModel PlainModel].freeze
+      #     # ALLOWED_DOMAIN_CLASS_PATHS = %w[app/models/legacy/].freeze
+      #   end
+      module DomainClassBase
+        # Defaults. Per-project override: redefine the constants on the test
+        # class that includes this module.
+        DOMAIN_BASE_CLASS_NAMES = DomainClassBaseChecker::DEFAULT_BASE_CLASS_NAMES
+        ALLOWED_DOMAIN_CLASS_PATHS = [].freeze
+
+        def test_every_model_class_descends_from_a_domain_base
+          offenders = DomainClassBaseChecker.new(
+            Rails.root,
+            base_class_names: self.class::DOMAIN_BASE_CLASS_NAMES,
+            allowed_paths: self.class::ALLOWED_DOMAIN_CLASS_PATHS
+          ).offenders
+
+          assert offenders.empty?, domain_class_base_message(offenders)
+        end
+
+        private
+
+        def domain_class_base_message(offenders)
+          "Classes under app/models must descend from one of " \
+            "#{self.class::DOMAIN_BASE_CLASS_NAMES.join(' / ')} — the three-way rule " \
+            "(backend/03_model.md item 9): persisted -> ApplicationRecord, form-backed " \
+            "-> ApplicationModel, plain domain logic -> PlainModel. If a class is a " \
+            "sanctioned exception, add its path to ALLOWED_DOMAIN_CLASS_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/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/application_model_base.rb

@@ -0,0 +1,56 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Inherit the app's `ApplicationModel` root instead of including
+        # `ActiveModel::Model` directly in a class under `app/models`.
+        #
+        # ## Rationale
+        # Table-less form-backed domain objects follow the three-way rule
+        # (backend/03_model.md item 9): persisted classes inherit
+        # `ApplicationRecord`, form-backed POROs inherit `ApplicationModel`
+        # (a thin app root over `Glib::Model`, which carries the shared
+        # mechanics such as `attr_id_list`), and plain domain logic inherits
+        # `PlainModel`. A direct `include ActiveModel::Model` bypasses the
+        # shared root: the class silently misses the shared mechanics, and the
+        # author never makes the which-kind-is-this decision the rule exists
+        # to force. This is the ActiveModel analog of `Rails/ApplicationRecord`.
+        #
+        # This cop gives editor-time feedback on the single most common direct
+        # mistake; totality (every model class descends from one of the three
+        # bases, through any intermediate family base) is enforced at test time
+        # by `DevDoc::Test::Lints::DomainClassBase`, since resolving indirect
+        # ancestry is beyond per-file static analysis.
+        #
+        # Disabled by default: enable it in projects whose `ApplicationModel`
+        # root exists (it requires glib-web's `Glib::Model`).
+        #
+        # @example
+        #   # bad
+        #   class BulkOperation
+        #     include ActiveModel::Model
+        #   end
+        #
+        #   # good
+        #   class BulkOperation < ApplicationModel
+        #   end
+        class ApplicationModelBase < Base
+          MSG = 'Inherit `ApplicationModel` instead of including `ActiveModel::Model` directly — ' \
+                'the shared root carries the form-object mechanics (backend/03_model.md item 9).'.freeze
+
+          RESTRICT_ON_SEND = %i[include].freeze
+
+          def_node_matcher :active_model_include?, <<~PATTERN
+            (send nil? :include (const (const {nil? cbase} :ActiveModel) :Model))
+          PATTERN
+
+          def on_send(node)
+            return unless active_model_include?(node)
+
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end

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/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.15.0".freeze
+    VERSION = "0.17.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -95,6 +95,7 @@ files:
 - 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/domain_class_base.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
@@ -133,6 +134,7 @@ files:
 - lib/rubocop/cop/dev_doc/migration/require_primary_key.rb
 - lib/rubocop/cop/dev_doc/migration/require_reference_foreign_key.rb
 - lib/rubocop/cop/dev_doc/migration/require_timestamps.rb
+- lib/rubocop/cop/dev_doc/rails/application_model_base.rb
 - lib/rubocop/cop/dev_doc/rails/application_record_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_bypassing_validation.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb
@@ -143,6 +145,7 @@ 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