rubocop-dev_doc 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2076123d07503e775a29287eafcd8dc9d8cf6e344eeb4b462d29120fdef12879
-  data.tar.gz: 910414d217e37c808b7626add2b876d24f6ef214a725b373e86dc736acb24ff7
+  metadata.gz: 2d7cebd4d2c1b85850d5a704dc26319f49526040c26d2573824f68461d42ae8c
+  data.tar.gz: 5fede674c17c29dd330e9499a1367c3f1174902b0a76c44d94c7f6683a35d130
 SHA512:
-  metadata.gz: 7681307dae1b8d09d0344c199d4be497bc4c986b4314711ae39550d7d8ced8d8b811d07d98997f8e3fc85d294e6fde1b97c8cb6cdc3c33a40ad3074cda985d62
-  data.tar.gz: a047b648abfcaeb1842158a562c17028601a2f24c67e1f0aa2cdc548377cccd1658dae4b6b68cee1cb4906275a59822f2870160380e71cb5d730c04ce5d44196
+  metadata.gz: 7b3666259413a6d37a6d13765c095005fd8395f1033a6d33de9539616b75d0e3d5091b26ab27ade88069ecd9c678231bd3126f116eb60a36db4e1220c50fefde
+  data.tar.gz: 2fcbae3b394369ab9e969a0edc7f1b7ba2379b4572f73e3311228fe265ab29285ebe34a7635d43f7bf02c9ab8e56921454b94817323c723a473fc37e20999726

data/config/default.yml

@@ -7,6 +7,10 @@ DevDoc/Auth:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
   DocumentationExtension: ".md"
 
+DevDoc/I18n:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  DocumentationExtension: ".md"
+
 DevDoc/Migration:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
   DocumentationExtension: ".md"
@@ -62,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.
@@ -396,3 +414,150 @@ DevDoc/Auth/CurrentUserBranching:
     - "app/helpers/**/*.rb"
     - "app/controllers/concerns/**/*.rb"
     - "app/views/layouts/**/*"
+
+DevDoc/I18n/AvoidTitleizeHumanize:
+  Description: "Avoid `.titleize`/`.humanize` for display text; it's English-only and bypasses I18n. Use `t(...)`."
+  # A review aid, not a clean lint: it can't tell a display string from one
+  # used to build a key or a log line. Off by default and `warning` severity;
+  # run it during a localization pass. The flagged methods are configurable
+  # via `Methods:`.
+  Enabled: false
+  Severity: warning
+  Methods:
+    - titleize
+    - humanize
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"
+
+DevDoc/I18n/RequireTranslation:
+  Description: "Localize user-facing strings in glib JSON-UI props; pass `t(...)` instead of a hardcoded string."
+  Enabled: false
+  # WatchedMethods: glib component builder methods whose hash props carry
+  # user-facing text. LocalizableKeys: the prop names checked on those calls.
+  # Extend both if your project adds custom components or text props.
+  WatchedMethods:
+    - h1
+    - h2
+    - h3
+    - h4
+    - h5
+    - h6
+    - p
+    - label
+    - markdown
+    - html
+    - button
+    - switch
+    - chip
+    - progressCircle
+    - shareButton
+    - fields_text
+    - fields_number
+    - fields_select
+    - fields_password
+    - fields_textarea
+    - fields_check
+    - fields_checkGroup
+    - fields_chipGroup
+    - fields_timeZone
+    - fields_radioGroup
+    - fields_date
+    - fields_datetime
+    - fields_upload
+    - dialogs_alert
+    - dialogs_notification
+    - snackbars_alert
+    - snackbars_select
+    - banners_alert
+    - banners_select
+  LocalizableKeys:
+    - title
+    - subtitle
+    - subsubtitle
+    - label
+    - placeholder
+    - text
+    - message
+    - description
+    - uploadText
+    - leftText
+    - rightText
+    - onLabel
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"
+
+DevDoc/I18n/TranslationKeyPrefix:
+  Description: "Translation keys must start with an allowed namespace prefix (e.g. `hotel.`, `general.`)."
+  Enabled: false
+  # AllowedPrefixes is project-specific, so it defaults to empty and the cop is
+  # a no-op until configured. Matches `t`, `translate`, and `I18n.t`. Only
+  # statically-literal keys are checked; dynamic/interpolated keys are skipped.
+  AllowedPrefixes: []
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"
+    - "app/controllers/**/*.rb"
+    - "app/mailers/**/*.rb"
+    - "app/helpers/**/*.rb"
+
+DevDoc/I18n/ReportText:
+  Description: "Report every user-facing glib text prop — hardcoded and already-localized — to collect all possible texts."
+  # A tooling aid, not a lint: unlike RequireTranslation it fires on *every*
+  # text value (including `t(...)` calls) so you can sweep the codebase and
+  # collect the full list of user-facing strings. Off by default and `info`
+  # severity. Mirrors RequireTranslation's WatchedMethods/LocalizableKeys.
+  Enabled: false
+  Severity: info
+  WatchedMethods:
+    - h1
+    - h2
+    - h3
+    - h4
+    - h5
+    - h6
+    - p
+    - label
+    - markdown
+    - html
+    - button
+    - switch
+    - chip
+    - progressCircle
+    - shareButton
+    - fields_text
+    - fields_number
+    - fields_select
+    - fields_password
+    - fields_textarea
+    - fields_check
+    - fields_checkGroup
+    - fields_chipGroup
+    - fields_timeZone
+    - fields_radioGroup
+    - fields_date
+    - fields_datetime
+    - fields_upload
+    - dialogs_alert
+    - dialogs_notification
+    - snackbars_alert
+    - snackbars_select
+    - banners_alert
+    - banners_select
+  LocalizableKeys:
+    - title
+    - subtitle
+    - subsubtitle
+    - label
+    - placeholder
+    - text
+    - message
+    - description
+    - uploadText
+    - leftText
+    - rightText
+    - onLabel
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"

data/lib/rubocop/cop/dev_doc/i18n/avoid_titleize_humanize.rb

@@ -0,0 +1,59 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Warn when `.titleize` or `.humanize` is used to derive display text.
+        #
+        # ## Rationale
+        # `titleize`/`humanize` turn an identifier into an English phrase
+        # (`'sign_up'.titleize # => 'Sign Up'`). When that result is shown to a
+        # user it bypasses the I18n catalog and can only ever read as English —
+        # it can't be translated. Localize the text with a `t(...)` lookup
+        # instead of transforming a symbol/column name at render time.
+        #
+        # This can't tell a display string from one used to build a key or a
+        # log line, so it is a **review aid**: disabled by default, `warning`
+        # severity, and scoped to view files. Run it during a localization pass.
+        #
+        #   ⚠️ English-only — can't be translated
+        #   view.h1 text: status.titleize
+        #   view.p text: user.role.humanize
+        #
+        #   ✔️ Resolved through I18n
+        #   view.h1 text: t("status.#{status}")
+        #
+        # @example
+        #   # warning
+        #   view.h1 text: status.titleize
+        #
+        #   # warning
+        #   view.p text: model_name.humanize
+        #
+        #   # good
+        #   view.h1 text: t("status.#{status}")
+        class AvoidTitleizeHumanize < Base
+          MSG = 'Avoid `.%<method>s` for display text: the result is ' \
+                'English-only and bypasses I18n. Use `t(...)` instead.'.freeze
+
+          DEFAULT_METHODS = %w[titleize humanize].freeze
+
+          def on_send(node)
+            return unless forbidden_methods.include?(node.method_name.to_s)
+
+            add_offense(
+              node.loc.selector,
+              message: format(MSG, method: node.method_name)
+            )
+          end
+          alias on_csend on_send
+
+          private
+
+          def forbidden_methods
+            cop_config.fetch('Methods', DEFAULT_METHODS)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/i18n/localizable_props.rb

@@ -0,0 +1,109 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Shared traversal for the glib JSON-UI localization cops
+        # (`RequireTranslation`, `ReportText`).
+        #
+        # It locates user-facing text values on watched glib component calls and
+        # hands each `(key, value_node)` to the including cop's
+        # `#inspect_localizable`, which decides whether to report. Three call
+        # shapes are covered:
+        #
+        #   * hash prop:           `view.p text: '...'`
+        #   * nested hash prop:    `view.icon tooltip: { text: '...' }`
+        #   * jbuilder positional: `json.title '...'`
+        #
+        # Nested hashes (and hashes inside arrays, e.g. select options) are
+        # walked to any depth, so a localizable key is found wherever it sits.
+        #
+        # The watched method names and localizable keys are configurable via
+        # `WatchedMethods:` and `LocalizableKeys:`.
+        module LocalizableProps
+          DEFAULT_WATCHED_METHODS = %w[
+            h1 h2 h3 h4 h5 h6 p label markdown html
+            button switch chip progressCircle shareButton
+            fields_text fields_number fields_select fields_password
+            fields_textarea fields_check fields_checkGroup fields_chipGroup
+            fields_timeZone fields_radioGroup fields_date fields_datetime
+            fields_upload
+            dialogs_alert dialogs_notification
+            snackbars_alert snackbars_select
+            banners_alert banners_select
+          ].freeze
+
+          DEFAULT_LOCALIZABLE_KEYS = %w[
+            title subtitle subsubtitle label placeholder text
+            message description uploadText leftText rightText onLabel
+          ].freeze
+
+          TRANSLATION_METHODS = %i[t translate].freeze
+
+          def on_send(node)
+            if watched_methods.include?(node.method_name.to_s)
+              node.arguments.each { |arg| each_localizable(arg) }
+            end
+
+            check_jbuilder_positional(node)
+          end
+          alias on_csend on_send
+
+          private
+
+          # Walk a value, handing every localizable `(key, value)` pair found at
+          # any depth to the cop: top-level hash pairs, nested hashes, and
+          # hashes nested inside arrays (e.g. select options / menu buttons).
+          def each_localizable(node)
+            case node.type
+            when :hash
+              node.pairs.each do |pair|
+                key = pair.key
+                if key.sym_type? && localizable_keys.include?(key.value.to_s)
+                  inspect_localizable(key.value, pair.value)
+                end
+
+                each_localizable(pair.value)
+              end
+            when :array
+              node.children.each { |child| each_localizable(child) }
+            end
+          end
+
+          # jbuilder positional form: `json.title 'Forms'`. The method name is
+          # the key and the first argument is the value. Restricted to the
+          # jbuilder root `json` so ordinary `obj.text('...')` calls aren't
+          # mistaken for localizable props.
+          def check_jbuilder_positional(node)
+            return unless localizable_keys.include?(node.method_name.to_s)
+            return unless json_receiver?(node.receiver)
+
+            value = node.first_argument
+            return unless value
+
+            inspect_localizable(node.method_name, value)
+          end
+
+          def json_receiver?(node)
+            return false unless node
+
+            (node.send_type? && node.method_name == :json && node.receiver.nil?) ||
+              (node.lvar_type? && node.children.first == :json)
+          end
+
+          def translation_call?(node)
+            (node.send_type? || node.csend_type?) &&
+              TRANSLATION_METHODS.include?(node.method_name)
+          end
+
+          def watched_methods
+            cop_config.fetch('WatchedMethods', DEFAULT_WATCHED_METHODS)
+          end
+
+          def localizable_keys
+            cop_config.fetch('LocalizableKeys', DEFAULT_LOCALIZABLE_KEYS)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/i18n/report_text.rb

@@ -0,0 +1,76 @@
+require_relative 'localizable_props'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Report every user-facing text in a glib JSON-UI text prop — both
+        # hardcoded strings and already-localized `t(...)` calls.
+        #
+        # ## Rationale
+        # `DevDoc/I18n/RequireTranslation` flags only *hardcoded* strings; it
+        # stays silent once a value is localized. This cop is the opposite: it
+        # fires on **every** text value, localized or not, so you can sweep a
+        # codebase and collect the full list of user-facing strings (e.g. to
+        # seed a translation catalog or audit coverage).
+        #
+        # It is a tooling aid, not a lint — **disabled by default** and runs at
+        # `info` severity. Run it during a localization pass; it is not meant
+        # for every commit.
+        #
+        # Both the hardcoded form (`view.p text: 'Welcome'`) and the localized
+        # form (`view.p text: t('home.welcome')`) are reported. Blank/whitespace
+        # strings and pure dynamic values (`user.name`) carry no static text and
+        # are skipped.
+        #
+        # The watched method names and localizable keys are configurable via
+        # `WatchedMethods:` and `LocalizableKeys:`.
+        #
+        #   📋 Reported — hardcoded text
+        #   view.p text: 'Welcome'
+        #
+        #   📋 Reported — localized text
+        #   view.p text: t('home.welcome')
+        #
+        # @example
+        #   # info (hardcoded text)
+        #   view.p text: 'Welcome'
+        #
+        #   # info (localized text — still reported)
+        #   view.p text: t('home.welcome')
+        #
+        #   # info (interpolated string)
+        #   view.p text: "Hi #{name}"
+        #
+        #   # ignored (blank — no text)
+        #   view.fields_text label: ''
+        #
+        #   # ignored (pure dynamic — no static text)
+        #   view.p text: user.name
+        class ReportText < Base
+          include LocalizableProps
+
+          MSG = 'Text for `%<key>s:`: review/collect this for localization.'.freeze
+
+          private
+
+          def inspect_localizable(key, value)
+            return unless text?(value)
+
+            add_offense(value, message: format(MSG, key: key))
+          end
+
+          # Any value that carries static user-facing text: a non-blank string
+          # literal, an interpolated string, or a translation call. Blank strings
+          # and pure dynamic values (`user.name`) carry no text and are skipped.
+          def text?(node)
+            return true if node.dstr_type?
+            return !node.value.strip.empty? if node.str_type?
+
+            translation_call?(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/i18n/require_translation.rb

@@ -0,0 +1,95 @@
+require_relative 'localizable_props'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Flag hardcoded user-facing strings in glib JSON-UI component props.
+        #
+        # ## Rationale
+        # Glib components render text from props like `text:`, `label:`, and
+        # `title:`. Passing a string literal ships untranslatable copy — it can
+        # never be localized and bypasses the I18n catalog. Pass `t('...')` (or
+        # any non-literal) so the text resolves through the locale files.
+        #
+        # Hash props (`view.p text: '...'`), nested hash props
+        # (`view.icon tooltip: { text: '...' }`) and the jbuilder positional
+        # form (`json.title '...'`) are all checked. Empty/whitespace strings
+        # are ignored — they carry no user-facing text. An interpolated string
+        # (`"Hi #{name}"`) is flagged because its literal portions are still
+        # hardcoded copy — unless it interpolates a `t(...)` (or
+        # `translate`/`I18n.t`) call, which is treated as positive localization
+        # and left alone.
+        #
+        # The watched method names and localizable keys are configurable via
+        # `WatchedMethods:` and `LocalizableKeys:`.
+        #
+        #   ❌ Hardcoded — can't be translated
+        #   view.p text: 'Welcome'
+        #   view.fields_text label: 'Email'
+        #   view.icon tooltip: { text: 'Share' }
+        #   json.title 'Forms'
+        #
+        #   ✔️ Resolved through I18n
+        #   view.p text: t('home.welcome')
+        #   view.fields_text label: t('user.email')
+        #   view.p text: "#{t('home.welcome')}, #{user.name}"
+        #
+        # @example
+        #   # bad
+        #   view.p text: 'Welcome'
+        #
+        #   # bad
+        #   view.fields_text label: 'Email'
+        #
+        #   # bad (nested hash prop)
+        #   view.icon tooltip: { text: 'Share' }
+        #
+        #   # bad (jbuilder positional)
+        #   json.title 'Forms'
+        #
+        #   # bad (interpolation, but no translation call)
+        #   view.p text: "Hi #{name}"
+        #
+        #   # good
+        #   view.p text: t('home.welcome')
+        #
+        #   # good (interpolates a translation call)
+        #   view.p text: "#{t('home.greeting')} #{user.name}"
+        #
+        #   # good (non-literal — not flagged)
+        #   view.p text: user.name
+        class RequireTranslation < Base
+          include LocalizableProps
+
+          MSG = 'Localize this string: pass `t(...)` instead of a hardcoded ' \
+                'string for `%<key>s:`.'.freeze
+
+          private
+
+          def inspect_localizable(key, value)
+            return unless hardcoded_string?(value)
+
+            add_offense(value, message: format(MSG, key: key))
+          end
+
+          # A plain string literal is hardcoded copy unless it's blank. A `dstr`
+          # (interpolated string) is hardcoded copy too — unless it interpolates
+          # a translation call, which counts as positive localization.
+          def hardcoded_string?(node)
+            return !localized_interpolation?(node) if node.dstr_type?
+            return false unless node.str_type?
+
+            !node.value.strip.empty?
+          end
+
+          def localized_interpolation?(node)
+            node.each_descendant(:send, :csend).any? do |call|
+              TRANSLATION_METHODS.include?(call.method_name)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb

@@ -0,0 +1,89 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Require translation keys to start with an allowed namespace prefix.
+        #
+        # ## Rationale
+        # A flat translation catalog drifts into collisions and dead keys.
+        # Requiring every `t(...)` key to start with an agreed namespace (e.g.
+        # `hotel.`, `general.`) keeps the locale files organized and makes it
+        # obvious which feature owns a key.
+        #
+        # The allowed prefixes are project-specific, so `AllowedPrefixes:`
+        # defaults to empty and the cop does nothing until a project configures
+        # it. Matches `t`, `translate`, and `I18n.t` (the receiver is ignored).
+        #
+        # Only statically-literal keys are checked. A key built from
+        # interpolation (`t("#{prefix}.foo")`) or a variable (`t(key)`) can't be
+        # verified and is skipped. A key that begins with a literal segment
+        # (`t("hotel.#{id}")`) is checked against that leading segment.
+        #
+        #   ❌ No recognized prefix
+        #   t('welcome.title')
+        #
+        #   ✔️ Namespaced
+        #   t('general.welcome.title')
+        #   t('hotel.rooms.heading')
+        #
+        # @example AllowedPrefixes: ['hotel.', 'general.']
+        #   # bad
+        #   t('welcome.title')
+        #
+        #   # bad (lazy key has no namespace)
+        #   t('.title')
+        #
+        #   # good
+        #   t('hotel.rooms.heading')
+        #
+        #   # good (variable suffix, literal prefix is checked)
+        #   t("general.#{key}")
+        #
+        #   # not checked (fully dynamic key)
+        #   t("#{prefix}.title")
+        class TranslationKeyPrefix < Base
+          MSG = 'Translation key `%<key>s` must start with an allowed ' \
+                'prefix: %<prefixes>s.'.freeze
+
+          RESTRICT_ON_SEND = %i[t translate].freeze
+
+          def on_send(node)
+            prefixes = allowed_prefixes
+            return if prefixes.empty?
+
+            key_node = node.first_argument
+            return unless key_node
+
+            leading = leading_literal(key_node)
+            return if leading.nil?
+            return if prefixes.any? { |prefix| leading.start_with?(prefix) }
+
+            add_offense(key_node, message: format(MSG, key: key_node.source, prefixes: prefixes_display(prefixes)))
+          end
+
+          private
+
+          # The statically-known leading portion of the key, or nil when the key
+          # is dynamic (a variable, or a string that begins with interpolation).
+          def leading_literal(node)
+            case node.type
+            when :str then node.value
+            when :sym then node.value.to_s
+            when :dstr
+              first = node.children.first
+              first&.str_type? ? first.value : nil
+            end
+          end
+
+          def allowed_prefixes
+            Array(cop_config['AllowedPrefixes'])
+          end
+
+          def prefixes_display(prefixes)
+            prefixes.map { |prefix| "`#{prefix}`" }.join(', ')
+          end
+        end
+      end
+    end
+  end
+end

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.5.0".freeze
+    VERSION = "0.7.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-27 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -72,14 +72,14 @@ 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: []
@@ -94,13 +94,20 @@ files:
 - lib/rubocop-dev_doc.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching.rb
 - lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.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
+- 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