rubocop-dev_doc 0.6.0.beta1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfa7b6778294801c95bb37bb3c15a2c4b30f81e9b915ba3ee548475c4adc9cd4
-  data.tar.gz: 6606b6c2b6745b2c54f63a89a7b3ae1b4ce3bfb60dda96a471dc51e33232e802
+  metadata.gz: 2d7cebd4d2c1b85850d5a704dc26319f49526040c26d2573824f68461d42ae8c
+  data.tar.gz: 5fede674c17c29dd330e9499a1367c3f1174902b0a76c44d94c7f6683a35d130
 SHA512:
-  metadata.gz: adc4743bfba263e139f6ca4cc5abbc213c427a46081e0aa5bc12be84ae96cc26f5b37eb218707449ca4566e5fca6958534f9581104c0d92c97f83e2ef17003b2
-  data.tar.gz: f8aa2b1f19d0f1a628f86ae58b19ed71ba6c5f508fd3247203909f459fb22deeef7777fc5de17509af04a0e4618aebd95c1b19a6fdf78fe53c72f97db063e261
+  metadata.gz: 7b3666259413a6d37a6d13765c095005fd8395f1033a6d33de9539616b75d0e3d5091b26ab27ade88069ecd9c678231bd3126f116eb60a36db4e1220c50fefde
+  data.tar.gz: 2fcbae3b394369ab9e969a0edc7f1b7ba2379b4572f73e3311228fe265ab29285ebe34a7635d43f7bf02c9ab8e56921454b94817323c723a473fc37e20999726

data/config/default.yml

@@ -66,6 +66,20 @@ DevDoc/Migration/AvoidNonNull:
     - "db/migrate/*.rb"
     - "db/migrate/**/*.rb"
 
+DevDoc/Migration/AvoidBooleanColumn:
+  Description: "Avoid `boolean` columns; prefer a timestamp, enum, or model method that better models the data."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+DevDoc/Migration/BooleanColumnNotNull:
+  Description: "Boolean columns must carry `null: false` — NULL is outside {true, false}."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
 # Intentionally global (no Include) — these patterns are risky in any file, not only migrations.
 # Add project-specific Exclude entries (e.g. db/seeds.rb, lib/tasks/**/*.rb) in your .rubocop.yml
 # for places where bulk operations are intentional and performance-critical.

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

@@ -0,0 +1,135 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid `boolean` columns; prefer an alternative that better models
+        # the data.
+        #
+        # ## Rationale
+        # A boolean column collapses a domain into exactly two states, but
+        # most "is X?" questions are richer than that in practice. The
+        # constraint pushes developers past the path-of-least-resistance
+        # `add_column :boolean` toward a shape that captures what the data
+        # actually means.
+        #
+        # The question to ask before reaching for `t.boolean` is:
+        # "what does NULL mean here?" — and if the answer is "unset" or
+        # "not yet decided", that semantic should be explicit in the
+        # schema, not silently smuggled in as a third boolean state.
+        #
+        # Consider the alternatives in order:
+        #
+        # ### 1. Timestamp — when the flag implies a moment in time
+        # If the boolean answers "did X happen?", a timestamp gives both
+        # the answer (`approved_at.present?`) AND the moment it happened
+        # (`approved_at`), for free. A boolean gives only the first.
+        #
+        #   ❌ `approved` loses the moment of approval
+        #   add_column :submissions, :approved, :boolean
+        #
+        #   ✔️ `approved_at` answers both "is it approved?" and "when?"
+        #   add_column :submissions, :approved_at, :datetime
+        #
+        # This pattern dominates the codebase (`published_at`, `deleted_at`,
+        # `archived_at`, `completed_at`, etc.) for good reason.
+        #
+        # ### 2. Enum — when "unset" is a meaningful state, or a third
+        # value is plausible
+        # An enum with an explicit "no_X_needed" value models "unset"
+        # honestly. NULL is outside an enum's domain (a type violation),
+        # so the column can carry `null: false` without controversy — see
+        # `DevDoc/Rails/EnumColumnNotNull`.
+        #
+        #   ❌ nullable boolean; nil is a silent third state
+        #   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
+        #
+        #   class Checklist < ApplicationRecord
+        #     enum :approval_requirement, { no_approval_needed: 0, approval_by_admins: 1 }
+        #   end
+        #
+        # ### 3. Model method — when the flag is derived from other data
+        # If the answer can be computed from existing columns or
+        # associations, do not store it. A method keeps the source of
+        # truth singular.
+        #
+        #   ❌ denormalises role into a column
+        #   add_column :users, :is_admin, :boolean
+        #
+        #   ✔️ derived from `role`
+        #   class User < ApplicationRecord
+        #     def admin?
+        #       role == "admin"
+        #     end
+        #   end
+        #
+        # ### 4. Boolean — only when none of the above apply
+        # A genuine binary preference with no meaningful third state
+        # (e.g. `auto_renew`, `communication_allowed`). Inline-disable
+        # this cop with a brief `-- boolean` reason. The column MUST also
+        # carry `null: false` — enforced by the sibling cop
+        # `DevDoc/Migration/BooleanColumnNotNull`.
+        #
+        #   ✔️ true binary preference, justified
+        #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference; user opt-in
+        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
+        #
+        # NOTE: This cop catches `t.boolean`, `add_column ..., :boolean`,
+        # and `change_column ..., :boolean` (a type change to boolean).
+        # `change_column_type` migrations to a non-boolean type are not
+        # flagged — that is the cleanup direction.
+        #
+        # NOTE: This cop is deliberately NOT timestamp-aware. It cannot
+        # tell whether a `:datetime` column would have been a better fit;
+        # that judgment is the developer's at review time. The role of
+        # this cop is to force the moment of judgment, not to make it.
+        #
+        # @example
+        #   # bad
+        #   add_column :users, :is_admin, :boolean
+        #
+        #   # bad
+        #   t.boolean :approved
+        #
+        #   # good (timestamp alternative)
+        #   add_column :submissions, :approved_at, :datetime
+        #
+        #   # good (enum alternative)
+        #   add_column :checklists, :approval_requirement, :integer
+        #
+        #   # good (justified boolean)
+        #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference
+        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
+        class AvoidBooleanColumn < Base
+          MSG = 'Avoid `boolean` columns; consider a timestamp (approved_at), enum, or model method. ' \
+                'If a boolean is genuinely the right shape, disable this cop with a brief `-- boolean` reason ' \
+                'and ensure the column carries `null: false` (see DevDoc/Migration/BooleanColumnNotNull).'.freeze
+
+          def_node_matcher :boolean_column?, <<~PATTERN
+            (send _ {:boolean} ...)
+          PATTERN
+
+          def_node_matcher :add_column_boolean?, <<~PATTERN
+            (send _ :add_column _ _ (sym :boolean) ...)
+          PATTERN
+
+          def_node_matcher :change_column_to_boolean?, <<~PATTERN
+            (send _ :change_column _ _ (sym :boolean) ...)
+          PATTERN
+
+          def on_send(node)
+            return unless boolean_column?(node) || add_column_boolean?(node) || change_column_to_boolean?(node)
+
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -26,6 +26,12 @@ module RuboCop
         #   ❌ Regular column
         #   add_column :users, :profile_completion_rate, :float, null: false
         #
+        #   ❌ Tightening an existing column to NOT NULL
+        #   change_column_null :users, :name, false
+        #
+        #   ❌ Same tightening, via change_column
+        #   change_column :users, :name, :string, null: false
+        #
         #   ✔️ Regular column
         #   add_column :users, :profile_completion_rate, :float
         #
@@ -47,6 +53,12 @@ module RuboCop
         #   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.
+        # - **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.
         #
         #   ✔️ Required foreign key (never flagged)
         #   t.belongs_to :user, null: false, foreign_key: true
@@ -56,20 +68,41 @@ module RuboCop
         #   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
+        #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference
+        #   add_column :things, :flag, :boolean, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
+        #   # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #
         # 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
         # signal that the column is an enum, which documents the migration. A
         # silent skip would hide that intent.
         #
-        # NOTE: This cop only flags `null: false`. 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.
+        # NOTE: This cop also flags NOT NULL set on an existing column, by either
+        # 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.
+        #
+        # 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.
         #
         # @example
         #   # bad
         #   add_column :users, :name, :string, null: false
         #
+        #   # bad (tightening an existing column to NOT NULL)
+        #   change_column_null :users, :name, false
+        #
+        #   # 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`)
         #   t.integer :processing_status, null: false
         #
@@ -91,28 +124,56 @@ module RuboCop
             json jsonb bigint
           ].freeze
 
-          RESTRICT_ON_SEND = (COLUMN_METHODS + %i[add_column]).freeze
+          RESTRICT_ON_SEND = (COLUMN_METHODS + %i[add_column change_column change_column_null]).freeze
 
           def_node_matcher :null_false_pair, <<~PATTERN
             (hash <$(pair (sym :null) (false)) ...>)
           PATTERN
 
+          # Matches `change_column_null :table, :column, false` (and the optional
+          # trailing-default 4-arg form). The `false` arg IS the NOT NULL directive
+          # — the same constraint as `null: false` on a definition, just applied to
+          # an existing column via the standard add-nullable -> backfill -> tighten
+          # 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.
+          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
+          end
+
+          private
+
+          # The node whose NOT NULL directive offends: the `false` arg of
+          # `change_column_null`, or the `null: false` pair on a regular column
+          # definition. nil when there is nothing to flag.
+          def offense_node(node)
+            change_column_null_false(node) || column_null_false_pair(node)
+          end
+
+          def column_null_false_pair(node)
             return unless column_method?(node)
 
             options = node.arguments.find(&:hash_type?)
             return unless options
 
-            pair = null_false_pair(options)
-            return unless pair
-
-            add_offense(pair)
+            null_false_pair(options)
           end
 
-          private
-
+          # Methods that define or change a regular column and carry an options
+          # hash where `null:` may appear: the `t.<type>` helpers plus
+          # `add_column`/`change_column`. (`change_column_null` is handled
+          # separately — its NOT NULL directive is a positional `false`, not an
+          # options pair.)
           def column_method?(node)
-            node.method?(:add_column) || COLUMN_METHODS.include?(node.method_name)
+            node.method?(:add_column) ||
+              node.method?(:change_column) ||
+              COLUMN_METHODS.include?(node.method_name)
           end
         end
       end

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

@@ -0,0 +1,122 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Boolean columns must carry `null: false`.
+        #
+        # ## Rationale
+        # `null: false` is reserved for cases where NULL has no meaningful
+        # interpretation — and a justified boolean is one of those cases.
+        # NULL is outside the column's stated domain of {true, false}: it
+        # is neither value, and every read site has to silently coerce it
+        # (`nil || false == false`) or risk a footgun.
+        #
+        # The line is drawn here for standardization and non-subjectivity.
+        # Whether a *regular* column should be present is a business
+        # decision open to debate (see `DevDoc/Migration/AvoidNonNull`),
+        # but once the developer has justified a boolean via
+        # `DevDoc/Migration/AvoidBooleanColumn`'s escape hatch, the
+        # boolean's non-null-ness is objective — it does not depend on
+        # any further business decision — so it is enforced mechanically
+        # rather than argued column-by-column.
+        #
+        # This cop is the inverse of `DevDoc/Migration/AvoidNonNull` for
+        # 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`
+        # (alongside the `AvoidBooleanColumn` disable), this cop fires if
+        # `null: false` is missing.
+        #
+        # ## Adding `null: false` to a table with existing rows
+        # Postgres refuses to add a NOT NULL column to a non-empty table
+        # without a backfill. Use the model-validations backfill pattern
+        # (sanctioned by `DevDoc/Migration/AvoidColumnDefault`):
+        #
+        #   def change
+        #     add_column :table, :flag, :boolean
+        #
+        #     reversible do |dir|
+        #       dir.up do
+        #         Table.reset_column_information
+        #         Table.where(flag: nil).find_each do |t|
+        #           t.flag = false
+        #           t.save!
+        #         end
+        #       end
+        #     end
+        #
+        #     # rubocop:disable DevDoc/Migration/AvoidNonNull -- boolean
+        #     change_column_null :table, :flag, false
+        #     # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #   end
+        #
+        # The application layer is the source of truth for the default
+        # value on new records (e.g. via `after_initialize` or a factory).
+        # `default:` in the migration is still disallowed by
+        # `DevDoc/Migration/AvoidColumnDefault`.
+        #
+        # ## Interaction with AvoidBooleanColumn
+        # These two cops fire together on every boolean addition:
+        #
+        # - `AvoidBooleanColumn`: "reconsider using a boolean at all"
+        # - `BooleanColumnNotNull`: "if you do, it must be NOT NULL"
+        #
+        # Satisfy both by either changing the column type (timestamp /
+        # enum / model method) or, for a justified boolean, disabling
+        # `AvoidBooleanColumn` with `-- boolean` AND ensuring `null: false`
+        # is present so this cop does not fire.
+        #
+        # NOTE: This cop catches `t.boolean`, `add_column ..., :boolean`, and
+        # `change_column ..., :boolean` (a type change to boolean) without
+        # `null: false`. It does NOT scan `db/schema.rb` for legacy debt — it
+        # only enforces the invariant on declarations it can see. Existing
+        # nullable booleans are surfaced by inspection, not by this cop.
+        #
+        # @example
+        #   # bad - nullable boolean
+        #   add_column :users, :active, :boolean
+        #
+        #   # bad - nullable boolean in a create_table block
+        #   create_table :things do |t|
+        #     t.boolean :flag
+        #   end
+        #
+        #   # good - boolean carries null: false
+        #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference
+        #   add_column :things, :flag, :boolean, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
+        class BooleanColumnNotNull < Base
+          MSG = 'Boolean columns must carry `null: false` — NULL is outside {true, false}. ' \
+                'Backfill existing rows via the model, then `change_column_null`.'.freeze
+
+          def_node_matcher :boolean_column?, <<~PATTERN
+            (send _ {:boolean} ...)
+          PATTERN
+
+          def_node_matcher :add_column_boolean?, <<~PATTERN
+            (send _ :add_column _ _ (sym :boolean) ...)
+          PATTERN
+
+          def_node_matcher :change_column_to_boolean?, <<~PATTERN
+            (send _ :change_column _ _ (sym :boolean) ...)
+          PATTERN
+
+          def_node_matcher :null_false_pair, <<~PATTERN
+            (hash <$(pair (sym :null) (false)) ...>)
+          PATTERN
+
+          def on_send(node)
+            return unless boolean_column?(node) || add_column_boolean?(node) || change_column_to_boolean?(node)
+
+            options = node.arguments.find(&:hash_type?)
+            return if options && null_false_pair(options)
+
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.6.0.beta1".freeze
+    VERSION = "0.7.0".freeze
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.6.0.beta1
+  version: 0.7.0
 platform: ruby
 authors:
 - dev-doc contributors
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -71,14 +72,16 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.29'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.29'
+description:
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -97,12 +100,14 @@ files:
 - lib/rubocop/cop/dev_doc/i18n/require_translation.rb
 - lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb
 - lib/rubocop/cop/dev_doc/migration/amount_column_in_cents.rb
+- lib/rubocop/cop/dev_doc/migration/avoid_boolean_column.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_bypassing_validation.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_conditional_schema_changes.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_json_column.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_non_null.rb
 - 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/no_create_join_table.rb
 - lib/rubocop/cop/dev_doc/migration/prefer_belongs_to.rb
@@ -139,10 +144,12 @@ files:
 - lib/rubocop/dev_doc.rb
 - lib/rubocop/dev_doc/plugin.rb
 - lib/rubocop/dev_doc/version.rb
+homepage:
 licenses: []
 metadata:
   default_lint_roller_plugin: RuboCop::DevDoc::Plugin
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -157,7 +164,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.4.6
+signing_key:
 specification_version: 4
 summary: RuboCop cops enforcing dev-doc best practices
 test_files: []