rubocop-dev_doc 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c36d2d77bcdffd7f74968817e83dbdb75134e3e3d63b953127e4475f7c1841f9
-  data.tar.gz: db6ef7a22d41f10f30e6e6ffedfdb1c7605bc849907290930f9d1eae4f0c49b4
+  metadata.gz: 1f6961dde0d54631bae2f2dae6325183cc678f81701aa06575abab88cc1b0f7b
+  data.tar.gz: cc20cca8c229dca80fbd57d9950794b71560ccb2c13e0ace82c9b6cab0a0c93c
 SHA512:
-  metadata.gz: a874f22bc4773c0abaeb6de19587b5c1934061d40fb608831b2c725d060acdc39c8817689f38cab35041d1a67d99cfc12daf995a4bc3780fcc91a4f99901dfcb
-  data.tar.gz: 9966867628667e9fee6dd869345d1943e936db024a426b6dbd7433f14ae93396c5d8edeffba3a97b1259aac8f831ada7f288d93fdfceb14c34b4893d03fe613d
+  metadata.gz: cdf5e192d7d3b526311ca7e9b6d6d3d81a50b3a14d8bd9b4b4a5d4459c0ed4d34c4695e1087e109614cf6f5dc040a12b0e7686f4e4cf509e16f4c9b770a0ccfa
+  data.tar.gz: 3664cc36ac24eb3f1a0bd6061a3671c32695113d50dd87753a35ec13536d02330fa7f10c7188439e90726a9b3a80dac227205cbaf88f539cb668dd7d18ea628d

data/config/default.yml

@@ -250,10 +250,14 @@ DevDoc/Style/TapBlockIgnoresValue:
   Enabled: true
 
 DevDoc/Style/AvoidHeadResponse:
-  Description: "Avoid `head()` with error statuses; delegate error handling to Rails exceptions or model validations."
+  Description: "Avoid `head()` with error or no-content statuses; render a body (an exception page, validation errors, or an action spec) instead."
   Enabled: true
   Include:
     - "app/controllers/**/*.rb"
+  # Error statuses: delegate to Rails exceptions / model validations.
+  # No-content "successes" (no_content/reset_content): a bodyless response is
+  # ambiguous to a backend-driven JSON client -- render an action response,
+  # even an empty one.
   FlaggedStatuses:
     - not_found
     - unprocessable_entity
@@ -263,6 +267,8 @@ DevDoc/Style/AvoidHeadResponse:
     - conflict
     - gone
     - method_not_allowed
+    - no_content
+    - reset_content
     - "404"
     - "422"
     - "403"
@@ -271,6 +277,8 @@ DevDoc/Style/AvoidHeadResponse:
     - "409"
     - "410"
     - "405"
+    - "204"
+    - "205"
 
 DevDoc/Migration/AvoidConditionalSchemaChanges:
   Description: "Avoid conditional schema helpers (`add_column_if_not_exists`, `column_exists?`, etc.) in migrations."
@@ -293,6 +301,54 @@ DevDoc/Migration/NoCreateJoinTable:
     - "db/migrate/*.rb"
     - "db/migrate/**/*.rb"
 
+# The exact inverse of Rails/BulkChangeTable (disabled below) — the two must
+# never both be enabled. Whether this gem's `Enabled: false` for the stock cop
+# reaches a project is plugin-load-order dependent (the last-loaded extension's
+# default wins), so projects should ALSO disable Rails/BulkChangeTable
+# explicitly in their own .rubocop.yml.
+# SafeAutoCorrect false: removing `bulk:` turns one combined ALTER TABLE into
+# N separate statements on adapters that support bulk — identical end schema,
+# but a behavior change for unapplied migrations, so it only fires under -A.
+DevDoc/Migration/NoBulkChangeTable:
+  Description: "Avoid `bulk:` on `change_table` — a MySQL optimization that is a no-op on PostgreSQL."
+  Enabled: true
+  SafeAutoCorrect: false
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+# The reference-options trio. Each of a reference's three options gets the
+# enforcement shape its house position calls for:
+# - foreign_key: has one right value (constrain) -> enforce the VALUE.
+# - null: both values are legitimate -> enforce EXPLICITNESS (either passes).
+# - index: the default is already correct -> enforce SILENCE (flag redundancy).
+# Net effect: everything written on a reference line is a decision, everything
+# omitted is doctrine.
+DevDoc/Migration/RequireReferenceForeignKey:
+  Description: "Non-polymorphic references must carry `foreign_key: true` (or a `to_table:` hash)."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+DevDoc/Migration/ExplicitNullOnReference:
+  Description: "References must state `null:` explicitly — optional and mandatory are both legitimate."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+# Autocorrect is safe here (unlike NoBulkChangeTable): on Migration[5.0]+ the
+# index is created either way, so removing `index: true` cannot change the
+# resulting schema — and Migration[4.2] classes, where the compatibility layer
+# flips the default and the option IS load-bearing, are skipped entirely.
+DevDoc/Migration/RedundantReferenceIndex:
+  Description: "`index: true` is redundant on references — they are indexed by default since Rails 5."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
 # This cop is heuristic: it matches column names whose last segment is a known
 # monetary word. Enable it in your project's .rubocop.yml and extend MonetaryNames
 # if your domain uses different names. Disabled by default to avoid false positives.
@@ -467,10 +523,29 @@ Rails/SaveBang:
 # demands trips DevDoc/Migration/AvoidColumnDefault (on the backfill `default:`)
 # and Rails/ReversibleMigration (on `t.change_default`), neither disable-able
 # inline, for the standard add-column-then-drop-default backfill — making the
-# three rules mutually unsatisfiable. Off for all projects.
+# three rules mutually unsatisfiable. Off for all projects — and the opposite
+# direction is enforced by DevDoc/Migration/NoBulkChangeTable above, so this
+# must stay off wherever that cop is enabled. NOTE: whether this entry reaches
+# a consumer is plugin-load-order dependent — the last-loaded extension's
+# default wins (measured on rubocop 1.86: `plugins: [rubocop-rails,
+# rubocop-dev_doc]` resolves to false, the reverse order to true) — so
+# projects should disable it explicitly in their own .rubocop.yml.
 Rails/BulkChangeTable:
   Enabled: false
 
+# Fires on `add_reference ... null: false` — the exact line complying with
+# DevDoc/Migration/ExplicitNullOnReference produces for a mandatory FK, so the
+# two collide on the same token. Little is lost by turning it off: its
+# add_column half is covered more strictly by DevDoc/Migration/AvoidNonNull,
+# and its add_reference half contradicts house doctrine (mandatory FKs carry
+# `null: false`; a populated-table migration fails loudly at migrate time and
+# uses the add-nullable -> backfill -> tighten pattern instead — note its
+# suggested remedy, `change_column_null`, is itself flagged by AvoidNonNull).
+# Same load-order caveat as Rails/BulkChangeTable above: disable it in the
+# project's .rubocop.yml too.
+Rails/NotNullColumn:
+  Enabled: false
+
 # Superseded by DevDoc/Style/CaseElseDecision below: same detection, but the
 # offense message carries the raise/report/fall-through decision framework
 # instead of upstream's "Missing else statement" (which teaches the wrong

data/lib/rubocop/cop/dev_doc/hash_pair_removal.rb

@@ -0,0 +1,52 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      # Shared autocorrect helper for deleting one pair from a method call's
+      # options hash. The removal range is anchored on neighbouring AST nodes
+      # rather than walked-over whitespace, so newlines between arguments are
+      # handled without corrupting the code.
+      #
+      # Callers must skip the correction when `pair_removal_range` returns nil
+      # or when the range crosses a comment (`crosses_comment?`) — deleting a
+      # range that overlaps a comment would corrupt it.
+      module HashPairRemoval
+        private
+
+        # For a single-pair hash the preceding argument is the anchor (and a
+        # braced hash is removed whole); otherwise the neighbouring pair is.
+        # A hash containing a `**kwsplat` is bailed on entirely (nil): the
+        # anchors navigate `pairs`, which excludes kwsplats, so a splat between
+        # anchor and victim would silently fall inside the deleted range.
+        def pair_removal_range(node, options, pair)
+          return nil unless options.children.size == options.pairs.size
+
+          if options.pairs.one?
+            lone_pair_range(node, options, pair)
+          else
+            sibling_pair_range(options, pair)
+          end
+        end
+
+        def lone_pair_range(node, options, pair)
+          index = node.arguments.index(options)
+          return nil if index.zero?
+
+          victim = options.braces? ? options : pair
+          node.arguments[index - 1].source_range.end.join(victim.source_range.end)
+        end
+
+        def sibling_pair_range(options, pair)
+          pairs = options.pairs
+          index = pairs.index(pair)
+          return pair.source_range.begin.join(pairs[1].source_range.begin) if index.zero?
+
+          pairs[index - 1].source_range.end.join(pair.source_range.end)
+        end
+
+        def crosses_comment?(range)
+          processed_source.comments.any? { |comment| comment.source_range.overlaps?(range) }
+        end
+      end
+    end
+  end
+end

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

@@ -90,8 +90,10 @@ module RuboCop
         #
         # NOTE: This cop only flags `null: false` (and the equivalent `false` arg
         # of `change_column_null`). It does not flag `null: true` (redundant but
-        # harmless), and it does not require foreign keys to carry `null: false`
-        # — adding it to an FK is encouraged but not enforced here.
+        # harmless on regular columns), and it never requires anything of foreign
+        # keys — whether a reference is mandatory is a genuine per-reference
+        # decision, so the sibling cop `DevDoc/Migration/ExplicitNullOnReference`
+        # requires that decision to be STATED (either value passes).
         #
         # @example
         #   # bad

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

@@ -0,0 +1,85 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Every reference must state `null:` explicitly.
+        #
+        # ## Rationale
+        # For regular columns the house rule is nullable
+        # (`DevDoc/Migration/AvoidNonNull`), so an absent `null:` is
+        # unambiguous — silence IS the decision. Foreign-key columns are the
+        # exception that `AvoidNonNull` deliberately carves out: optional and
+        # mandatory are both completely legitimate, a genuine per-reference
+        # business decision. But a legitimate decision that is never written down is
+        # indistinguishable from an omission — a bare reference reads as "did
+        # the developer forget?".
+        #
+        # This cop requires the decision to be stated. Either value passes;
+        # `null: true` is not redundant here, it is the self-documenting
+        # spelling of "optional by design".
+        #
+        #   ❌ Ambiguous — optional by design, or forgotten?
+        #   t.belongs_to :organization, foreign_key: true
+        #
+        #   ✔️ Mandatory, stated
+        #   t.belongs_to :organization, foreign_key: true, null: false
+        #
+        #   ✔️ Optional, stated
+        #   t.belongs_to :organization, foreign_key: true, null: true
+        #
+        # Polymorphic references are held to the same rule — their
+        # optionality is just as much a decision.
+        #
+        # ## Relationship with Rails/NotNullColumn
+        # The stock cop flags `add_reference ... null: false` (NOT NULL added
+        # to a possibly-populated table without a default) — the exact line
+        # complying with THIS cop produces for a mandatory FK, so the two
+        # collide. Consumers disable `Rails/NotNullColumn`: its `add_column`
+        # half is covered more strictly by `DevDoc/Migration/AvoidNonNull`,
+        # and its `add_reference` half contradicts house doctrine (a
+        # populated-table migration fails loudly at migrate time and uses the
+        # add-nullable -> backfill -> tighten pattern instead). This gem's
+        # default config disables it, but that propagation is load-order
+        # dependent (see `NoBulkChangeTable`'s docstring) — disable it in the
+        # project's `.rubocop.yml` too.
+        #
+        # NOTE: This cop enforces that optionality is stated; the sibling cop
+        # `DevDoc/Migration/RequireReferenceForeignKey` enforces the
+        # constraint's presence, and
+        # `DevDoc/Migration/RedundantReferenceIndex` removes the one reference
+        # option whose default is already correct. Together: everything
+        # written on a reference is a decision, everything omitted is
+        # doctrine.
+        #
+        # @example
+        #   # bad
+        #   t.belongs_to :user, foreign_key: true
+        #
+        #   # good
+        #   t.belongs_to :user, foreign_key: true, null: false
+        #
+        #   # good
+        #   t.belongs_to :user, foreign_key: true, null: true
+        class ExplicitNullOnReference < Base
+          MSG = 'State `null:` explicitly — optional and mandatory are both legitimate ' \
+                'for a reference, so omission reads as an unmade decision.'.freeze
+
+          RESTRICT_ON_SEND = %i[belongs_to references add_reference add_belongs_to].freeze
+
+          def on_send(node)
+            options = node.arguments.find(&:hash_type?)
+            return if options && null_stated?(options)
+
+            add_offense(node.loc.selector)
+          end
+
+          private
+
+          def null_stated?(options)
+            options.pairs.any? { |pair| pair.key.sym_type? && pair.key.value == :null }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+require_relative '../hash_pair_removal'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid the `bulk:` option on `change_table`.
+        #
+        # ## Rationale
+        # `bulk: true` combines multiple ALTER TABLE sub-commands into a single
+        # statement. That is a MySQL/MariaDB optimization — it avoids repeated
+        # full-table rewrites there — but consuming projects run PostgreSQL,
+        # where ALTER sub-commands are cheap metadata operations and `bulk:` is
+        # a no-op that only adds noise.
+        #
+        # Worse, the combined form conflicts with the standard
+        # add-column-then-drop-default backfill pattern: inside a `bulk: true`
+        # block it trips `DevDoc/Migration/AvoidColumnDefault` (on the backfill
+        # `default:`) and `Rails/ReversibleMigration` (on `t.change_default`),
+        # neither of which can be disabled inline.
+        #
+        #   ❌
+        #   change_table :users, bulk: true do |t|
+        #     t.string :token
+        #     t.datetime :closed_at
+        #   end
+        #
+        #   ✔️
+        #   change_table :users do |t|
+        #     t.string :token
+        #     t.datetime :closed_at
+        #   end
+        #
+        # ## Relationship with Rails/BulkChangeTable
+        # This cop is the exact inverse of `Rails/BulkChangeTable`, which
+        # DEMANDS `bulk: true` whenever several ALTERs touch one table. The two
+        # cannot both be enabled. This gem's default config disables
+        # `Rails/BulkChangeTable`, but whether that default reaches a project
+        # is plugin-load-order dependent — the last-loaded extension's default
+        # wins, so a project listing `rubocop-dev_doc` before `rubocop-rails`
+        # still gets rubocop-rails' `Enabled: true`. Disable it explicitly in
+        # the project's `.rubocop.yml` rather than relying on load order.
+        #
+        # NOTE: When a comment sits between `change_table`'s arguments, the cop
+        # flags the option but does not autocorrect (removing the range would
+        # corrupt the comment) — delete the option manually.
+        #
+        # @example
+        #   # bad
+        #   change_table :users, bulk: true do |t|
+        #     t.string :token
+        #   end
+        #
+        #   # good
+        #   change_table :users do |t|
+        #     t.string :token
+        #   end
+        class NoBulkChangeTable < Base
+          extend AutoCorrector
+          include HashPairRemoval
+
+          MSG = 'Avoid `bulk:` on `change_table` — a MySQL optimization that is a no-op on PostgreSQL.'.freeze
+          RESTRICT_ON_SEND = %i[change_table].freeze
+
+          def on_send(node)
+            options = node.arguments.find(&:hash_type?)
+            return unless options
+
+            options.pairs.each { |pair| check_pair(node, options, pair) }
+          end
+
+          private
+
+          def check_pair(node, options, pair)
+            return unless bulk_key?(pair.key)
+
+            range = pair_removal_range(node, options, pair)
+            if range.nil? || crosses_comment?(range)
+              add_offense(pair)
+            else
+              add_offense(pair) { |corrector| corrector.remove(range) }
+            end
+          end
+
+          def bulk_key?(key)
+            (key.sym_type? || key.str_type?) && key.value.to_s == 'bulk'
+          end
+
+          def crosses_comment?(range)
+            processed_source.comments.any? { |comment| comment.source_range.overlaps?(range) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+require_relative '../hash_pair_removal'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid the redundant `index: true` on references.
+        #
+        # ## Rationale
+        # `belongs_to` / `references` / `add_reference` default to
+        # `index: true` since Rails 5 — the index is created whether or not
+        # the option is written. An explicit `index: true` therefore does
+        # nothing except make every future reader wonder whether it does
+        # (and imply, wrongly, that references without it are unindexed).
+        #
+        # The option is only meaningful when it *overrides* the default:
+        # `index: false` to opt out, or a hash to customize
+        # (`index: { unique: true }`). Those forms pass untouched.
+        #
+        #   ❌ Redundant — this index exists anyway
+        #   t.belongs_to :user, foreign_key: true, null: false, index: true
+        #
+        #   ✔️
+        #   t.belongs_to :user, foreign_key: true, null: false
+        #
+        #   ✔️ Meaningful override
+        #   t.belongs_to :user, foreign_key: true, null: false, index: { unique: true }
+        #
+        # NOTE: This cop removes the one reference option whose default is
+        # already correct; the sibling cops
+        # `DevDoc/Migration/RequireReferenceForeignKey` and
+        # `DevDoc/Migration/ExplicitNullOnReference` require the two options
+        # that ARE decisions to be made and stated. Together: everything
+        # written on a reference is a decision, everything omitted is
+        # doctrine.
+        #
+        # NOTE: When a comment sits between the call's arguments, the cop
+        # flags the option but does not autocorrect (removing the range would
+        # corrupt the comment) — delete the option manually.
+        #
+        # NOTE: Migrations declared `< ActiveRecord::Migration[4.2]` are
+        # skipped entirely: the 4.2 compatibility layer flips the reference
+        # default to `index: false`, so there `index: true` is meaningful —
+        # removing it would drop the index on a from-zero `db:migrate`.
+        #
+        # @example
+        #   # bad
+        #   t.belongs_to :user, foreign_key: true, index: true
+        #
+        #   # good
+        #   t.belongs_to :user, foreign_key: true
+        #
+        #   # good (meaningful override)
+        #   t.belongs_to :user, foreign_key: true, index: { unique: true }
+        class RedundantReferenceIndex < Base
+          extend AutoCorrector
+          include HashPairRemoval
+
+          MSG = '`index: true` is redundant — references are indexed by default since Rails 5.'.freeze
+
+          RESTRICT_ON_SEND = %i[belongs_to references add_reference add_belongs_to].freeze
+
+          def on_send(node)
+            options = node.arguments.find(&:hash_type?)
+            return unless options
+            return if legacy_migration?(node)
+
+            options.pairs.each { |pair| check_pair(node, options, pair) }
+          end
+
+          private
+
+          # `ActiveRecord::Migration[4.2]` compatibility flips the reference
+          # default to `index: false` (see compatibility.rb's V4_2), so inside
+          # such a class `index: true` is load-bearing, not redundant.
+          def legacy_migration?(node)
+            node.each_ancestor(:class).any? do |klass|
+              superclass = klass.children[1]
+              next false unless superclass&.send_type? && superclass.method?(:[])
+
+              version = superclass.first_argument
+              version&.numeric_type? && version.value < 5.0
+            end
+          end
+
+          def check_pair(node, options, pair)
+            return unless index_key?(pair.key) && pair.value.true_type?
+
+            range = pair_removal_range(node, options, pair)
+            if range.nil? || crosses_comment?(range)
+              add_offense(pair)
+            else
+              add_offense(pair) { |corrector| corrector.remove(range) }
+            end
+          end
+
+          def index_key?(key)
+            (key.sym_type? || key.str_type?) && key.value.to_s == 'index'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Every non-polymorphic reference must carry a truthy `foreign_key:`.
+        #
+        # ## Rationale
+        # `foreign_key: true` (or a `to_table:` hash) is pure referential
+        # integrity — never a business decision — so the house rule is that
+        # every reference carries the DB-level constraint. Rails defaults
+        # references to NO constraint, which means both an omitted option and
+        # an explicit `foreign_key: false` silently ship an unconstrained
+        # column, indistinguishable from an oversight.
+        #
+        # This cop makes the constraint the enforced default and turns the
+        # rare deliberate exception into a documented, greppable site: keep
+        # `foreign_key: false` on the line and disable this cop with a brief
+        # reason.
+        #
+        #   ❌ Omitted — reads as "never decided"
+        #   t.belongs_to :author, null: false
+        #
+        #   ❌ Explicit false without justification
+        #   t.belongs_to :author, null: false, foreign_key: false
+        #
+        #   ✔️
+        #   t.belongs_to :author, null: false, foreign_key: true
+        #
+        #   ✔️ Cross-table naming
+        #   add_reference :posts, :reviewer, foreign_key: { to_table: :users }
+        #
+        #   ✔️ Deliberate exception, self-documenting
+        #   # rubocop:disable DevDoc/Migration/RequireReferenceForeignKey -- append-only audit table
+        #   t.belongs_to :snapshot, null: false, foreign_key: false
+        #   # rubocop:enable DevDoc/Migration/RequireReferenceForeignKey
+        #
+        # ## Exception
+        # Polymorphic references (`polymorphic: true`) are skipped — a
+        # polymorphic column points at many tables, so no single FK constraint
+        # can exist.
+        #
+        # NOTE: A reference whose constraint is added separately via
+        # `add_foreign_key` later in the migration (the pattern engine-vendored
+        # migrations use) is still flagged — the cop cannot reliably match the
+        # two up. Prefer the inline `foreign_key:` option; for vendored engine
+        # migrations, disable with a reason or exclude the file.
+        #
+        # NOTE: This cop enforces the constraint's presence; the sibling cop
+        # `DevDoc/Migration/ExplicitNullOnReference` enforces that the
+        # column's optionality is stated, and
+        # `DevDoc/Migration/RedundantReferenceIndex` removes the one reference
+        # option whose default is already correct. Together: everything
+        # written on a reference is a decision, everything omitted is
+        # doctrine.
+        #
+        # @example
+        #   # bad
+        #   t.belongs_to :author
+        #
+        #   # bad
+        #   t.belongs_to :author, foreign_key: false
+        #
+        #   # good
+        #   t.belongs_to :author, foreign_key: true
+        #
+        #   # good (polymorphic — no constraint possible)
+        #   t.belongs_to :item, polymorphic: true
+        class RequireReferenceForeignKey < Base
+          MSG = 'Add `foreign_key: true` (or a `to_table:` hash); a deliberate exception ' \
+                'keeps `foreign_key: false` plus a reasoned disable of this cop.'.freeze
+
+          RESTRICT_ON_SEND = %i[belongs_to references add_reference add_belongs_to].freeze
+
+          def on_send(node)
+            options = node.arguments.find(&:hash_type?)
+            return if polymorphic?(options)
+
+            pair = foreign_key_pair(options)
+            if pair.nil?
+              add_offense(node.loc.selector)
+            elsif pair.value.false_type? || pair.value.nil_type?
+              add_offense(pair)
+            end
+          end
+
+          private
+
+          # Any `polymorphic:` value other than literal false/nil counts as
+          # polymorphic — a non-literal value can't be resolved statically, and
+          # demanding an impossible FK would be a worse failure than skipping.
+          def polymorphic?(options)
+            return false unless options
+
+            options.pairs.any? do |pair|
+              pair.key.sym_type? && pair.key.value == :polymorphic &&
+                !pair.value.false_type? && !pair.value.nil_type?
+            end
+          end
+
+          def foreign_key_pair(options)
+            return nil unless options
+
+            options.pairs.find { |pair| pair.key.sym_type? && pair.key.value == :foreign_key }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -38,8 +38,16 @@ module RuboCop
         # (e.g. projects using `structure.sql`). It also relies on the schema
         # being current, resolves the table name by Rails convention (STI,
         # `self.table_name` overrides, or namespaced models may not resolve),
-        # recognizes only the positional `enum :name, …` form, and skips
-        # silently if the backing column cannot be found in the schema.
+        # recognizes the positional `enum :name, …` form (and glib's
+        # `enum_symbolize`; see below), and skips silently if the backing
+        # column cannot be found in the schema.
+        #
+        # Glib's `enum_symbolize :name, { … }` (which declares the enum itself)
+        # is recognized too — its presence validation guards the app layer, but
+        # this cop is about the DB-level guarantee, which validations cannot
+        # provide (`update_column`, `update_all`, `insert_all`, raw SQL). The
+        # legacy two-line form (`enum :name, …` + `enum_symbolize :name`) is
+        # covered via its bare `enum` line.
         #
         # @example
         #   # bad - the `status` column is nullable in db/schema.rb
@@ -51,16 +59,26 @@ module RuboCop
         #   class Order < ApplicationRecord
         #     enum :status, { active: 0, archived: 1 }
         #   end
+        #
+        # @example Glib's `enum_symbolize`
+        #   # bad - the same rule applies; the column must still be `null: false`
+        #   class Order < ApplicationRecord
+        #     enum_symbolize :status, { active: 0, archived: 1 }
+        #   end
         class EnumColumnNotNull < Base
           include ActiveRecordHelper
 
           MSG = 'Enum column `%<name>s` should be `null: false` — NULL is outside an enum\'s domain. ' \
                 'Model "unset" as an explicit enum value.'.freeze
 
-          RESTRICT_ON_SEND = %i[enum].freeze
+          RESTRICT_ON_SEND = %i[enum enum_symbolize].freeze
 
+          # `enum_symbolize` matches only its full (value-declaring) form; the
+          # legacy `enum_symbolize :name` (no values) is not an enum declaration —
+          # the bare `enum` line above it is, and is matched separately.
           def_node_matcher :enum_call, <<~PATTERN
-            (send nil? :enum (sym $_) ...)
+            {(send nil? :enum (sym $_) ...)
+             (send nil? :enum_symbolize (sym $_) {hash array} ...)}
           PATTERN
 
           def on_send(node)

data/lib/rubocop/cop/dev_doc/style/avoid_head_response.rb

@@ -2,7 +2,7 @@ module RuboCop
   module Cop
     module DevDoc
       module Style
-        # Avoid `head()` with error status codes in controllers.
+        # Avoid `head()` with error or no-content status codes in controllers.
         #
         # ## Rationale
         # Using `head()` for error responses returns an empty body with no
@@ -10,8 +10,15 @@ module RuboCop
         # to Rails exceptions (e.g. `ActiveRecord::RecordNotFound`) or model
         # validations instead, which give the client more context.
         #
-        # Success statuses like `:ok`, `:no_content`, and `:accepted` are
-        # legitimate uses of `head()` and are not flagged.
+        # `head :no_content` (and `:reset_content`) is flagged for a different
+        # reason: in a backend-driven JSON UI a bodyless "success" is
+        # ambiguous — the client needs a response body (even an empty action
+        # spec) to know what to do. A production `head :no_content` escape
+        # hatch surfaced as an error snackbar in front of a customer before
+        # this was flagged.
+        #
+        # Success statuses that normally carry a body (`:ok`, `:accepted`)
+        # are legitimate uses of `head()` and are not flagged.
         #
         # The set of flagged statuses is configurable via `FlaggedStatuses:`.
         #
@@ -26,12 +33,18 @@ module RuboCop
         #     @user = User.find(params[:id])
         #   end
         #
-        #   ✔️ Success response — empty body is correct here
+        #   ❌ Bodyless success — a JSON-driven client learns nothing
         #   def destroy
         #     @resource.destroy!
         #     head :no_content
         #   end
         #
+        #   ✔️ Tell the client what to do, even when that is "nothing"
+        #   def destroy
+        #     @resource.destroy!
+        #     render json: {}
+        #   end
+        #
         # @example
         #   # bad
         #   head(:not_found)
@@ -39,10 +52,10 @@ module RuboCop
         #   # bad
         #   head(:unprocessable_entity)
         #
-        #   # good (success status — not flagged)
+        #   # bad (bodyless success — ambiguous to a JSON-driven client)
         #   head(:no_content)
         #
-        #   # good (success status — not flagged)
+        #   # good (success status with a body expected — not flagged)
         #   head(:ok)
         #
         #   # good (dynamic status — not flagged to avoid false positives)
@@ -51,13 +64,18 @@ module RuboCop
           MSG = 'Avoid `head(%<status>s)` for error handling. ' \
                 'Delegate to Rails exceptions or model validations instead.'.freeze
 
+          NO_CONTENT_MSG = 'Avoid `head(%<status>s)`: a bodyless response tells a JSON-driven ' \
+                           'client nothing. Render an action response (even an empty one) instead.'.freeze
+
           RESTRICT_ON_SEND = %i[head].freeze
 
-          DEFAULT_FLAGGED_STATUSES = %w[
+          NO_CONTENT_STATUSES = %w[no_content reset_content 204 205].freeze
+
+          DEFAULT_FLAGGED_STATUSES = (%w[
             not_found unprocessable_entity forbidden unauthorized
             bad_request conflict gone method_not_allowed
             404 422 403 401 400 409 410 405
-          ].freeze
+          ] + NO_CONTENT_STATUSES).freeze
 
           def on_send(node)
             # `self.head(...)` is the same controller call — a bare receiver
@@ -68,7 +86,8 @@ module RuboCop
             return unless status_node
             return unless flagged_literal?(status_node)
 
-            add_offense(node.loc.selector, message: format(MSG, status: status_display(status_node)))
+            template = NO_CONTENT_STATUSES.include?(status_node.value.to_s) ? NO_CONTENT_MSG : MSG
+            add_offense(node.loc.selector, message: format(template, status: status_display(status_node)))
           end
 
           private

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.13.1".freeze
+    VERSION = "0.14.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-25 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -110,6 +110,7 @@ files:
 - lib/rubocop/cop/dev_doc/auth/no_record_presence_in_policy.rb
 - lib/rubocop/cop/dev_doc/auth/role_predicate_outside_policy.rb
 - lib/rubocop/cop/dev_doc/auth/unscoped_find_justification.rb
+- lib/rubocop/cop/dev_doc/hash_pair_removal.rb
 - lib/rubocop/cop/dev_doc/i18n/avoid_titleize_humanize.rb
 - lib/rubocop/cop/dev_doc/i18n/localizable_props.rb
 - lib/rubocop/cop/dev_doc/i18n/report_text.rb
@@ -124,9 +125,13 @@ files:
 - lib/rubocop/cop/dev_doc/migration/avoid_vague_column_names.rb
 - lib/rubocop/cop/dev_doc/migration/boolean_column_not_null.rb
 - lib/rubocop/cop/dev_doc/migration/date_column_naming.rb
+- lib/rubocop/cop/dev_doc/migration/explicit_null_on_reference.rb
+- lib/rubocop/cop/dev_doc/migration/no_bulk_change_table.rb
 - lib/rubocop/cop/dev_doc/migration/no_create_join_table.rb
 - lib/rubocop/cop/dev_doc/migration/prefer_belongs_to.rb
+- lib/rubocop/cop/dev_doc/migration/redundant_reference_index.rb
 - 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_record_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_bypassing_validation.rb