rubocop-dev_doc 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cad88b36f561dcd41b75c42c242bf3af1877081c6df2c43ffeeaf3edbdb9e712
-  data.tar.gz: ae68d462103ffb1bc792bf4cb7bc65e20ecd8eb773a7b729f0194b070833b487
+  metadata.gz: 05e1aabe21621ec2ef5867764976fcfb58d7e0bb42b6224f56065ac17bb5cd8b
+  data.tar.gz: 2adbd5114fa685aaf7240c04df9fadb955d2cba1a0ccfd83d1e8fb44751f9743
 SHA512:
-  metadata.gz: 5a74d067f5e2f0e7ca71f6457a590db627cde1bfe30349bccedaa363b3f7d8a08dc503eb5e301d7056434a03c600fbd85e716f95054d74a98a74b02923e17bba
-  data.tar.gz: 8439d5bb064c8d5211213f2912a6815cc3b4fb26db881f7f0bcd844a7b00ff11bcb457ab4a754c4144758e4dd203263afb51e81b13e6c3c862e7b4ae496b3b5d
+  metadata.gz: ffe0a1d90cdf8d0a4dcee8ba865631f9d9c8e3a1e2b3de6af25aa6eb9441a966d715d099e3824e40ec5ec2640c001d9043f375e81fc590732309554b81b80e18
+  data.tar.gz: 1d164d6cc051b8f216384ef334d0b5015a08d52a71cdb9b93e0cf065b6440e9a7285c3d4904d83be92936631b638428ff1dd816f39ace4a76b6053ee98b184b4

data/config/default.yml

@@ -188,6 +188,17 @@ DevDoc/Rails/NoTransactionInController:
   Include:
     - "app/controllers/**/*.rb"
 
+# Same placement rule in an assignment costume: `collection_ids=` on a
+# persisted record writes the join table immediately (no save, no
+# validations), so a controller-side ids write either bypasses the guards the
+# operation's form object/model enforces on its other write paths, or mutates
+# the association even when the surrounding operation fails afterwards.
+DevDoc/Rails/NoCollectionIdsWriterInController:
+  Description: "Association `*_ids=` writers in controllers persist join rows immediately on a persisted record, bypassing validations; move the write into the model method or form object that owns the operation's validations."
+  Enabled: true
+  Include:
+    - "app/controllers/**/*.rb"
+
 DevDoc/Rails/EnumMustBeSymbolized:
   Description: "Declare enums with `enum_symbolize :foo, { … }` instead of a bare `enum`, so the attribute type is set before the enum and the reader returns a symbol."
   Enabled: true

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

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

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

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

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

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

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

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

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

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

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

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

data/lib/rubocop/dev_doc/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -143,6 +143,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