rubocop-dev_doc 0.1.0 → 0.3.0

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

@@ -43,18 +43,18 @@ module RuboCop
         #     end
         #   end
         #
-        # ## Exception
+        # ## Exception (auto-detected)
         # For performance reasons (large tables with millions of records) or when
         # using `null: false`, you may temporarily set a default and then
-        # immediately remove it in the same migration:
+        # immediately remove it in the same migration. The cop suppresses the
+        # offense when it detects a matching `change_column_default ..., to: nil`
+        # for the same table and column anywhere in the same method body (`def
+        # change` / `def up`), including inside `reversible do |dir| dir.up`.
         #
-        #   ✔
+        #   ✔ (no offense — two-step pattern auto-detected)
         #   add_column :users, :profile_completion_rate, :float, default: 0.0
         #   change_column_default :users, :profile_completion_rate, from: 0.0, to: nil
         #
-        # NOTE: This cop currently flags the first line of the exception pattern.
-        # The follow-up `change_column_default ..., to: nil` is not auto-detected.
-        #
         # @example
         #   # bad
         #   add_column :users, :score, :integer, default: 0
@@ -65,7 +65,7 @@ module RuboCop
         #   # good
         #   add_column :users, :score, :integer
         #
-        #   # good (temporary default immediately removed)
+        #   # good (temporary default immediately removed — two-step pattern)
         #   add_column :users, :score, :integer, default: 0
         #   change_column_default :users, :score, from: 0, to: nil
         class AvoidColumnDefault < Base
@@ -80,19 +80,74 @@ module RuboCop
             (hash <(pair (sym :default) _) ...>)
           PATTERN
 
+          def_node_matcher :change_column_default_to_nil?, <<~PATTERN
+            (send _ :change_column_default (sym $_) (sym $_) (hash <(pair (sym :to) (nil)) ...>))
+          PATTERN
+
           def on_send(node)
-            return unless node.method?(:add_column) || COLUMN_METHODS.include?(node.method_name)
+            return unless column_method?(node)
+
+            options = node.arguments.find(&:hash_type?)
+            return unless options && has_default_option?(options)
+            return if two_step_pattern?(node)
 
-            check_options(node.arguments.find(&:hash_type?))
+            add_offense(find_default_pair(options))
           end
 
           private
 
-          def check_options(options)
-            return unless options && has_default_option?(options)
+          def column_method?(node)
+            node.method?(:add_column) || COLUMN_METHODS.include?(node.method_name)
+          end
+
+          def find_default_pair(options)
+            options.pairs.find { |p| p.key.sym_type? && p.key.value == :default }
+          end
+
+          def two_step_pattern?(node)
+            table_name, col_name = extract_table_and_column(node)
+            return false unless table_name && col_name
+
+            enclosing_def = node.each_ancestor(:def).first
+            return false unless enclosing_def
+
+            enclosing_def.each_descendant(:send).any? do |sibling|
+              cancels_default?(sibling, table_name, col_name)
+            end
+          end
+
+          def extract_table_and_column(node)
+            node.method?(:add_column) ? add_column_pair(node) : column_def_pair(node)
+          end
+
+          def add_column_pair(node)
+            t = node.arguments[0]
+            c = node.arguments[1]
+            [t.value, c.value] if t&.sym_type? && c&.sym_type?
+          end
+
+          def column_def_pair(node)
+            c = node.arguments[0]
+            return unless c&.sym_type?
+
+            t = enclosing_table_sym(node)
+            [t.value, c.value] if t
+          end
+
+          def enclosing_table_sym(node)
+            table_block = node.each_ancestor(:block).find do |b|
+              %i[create_table change_table].include?(b.method_name)
+            end
+            return unless table_block
+
+            arg = table_block.send_node.arguments[0]
+            arg if arg&.sym_type?
+          end
 
-            default_pair = options.pairs.find { |p| p.key.sym_type? && p.key.value == :default }
-            add_offense(default_pair)
+          def cancels_default?(node, table_name, col_name)
+            change_column_default_to_nil?(node) do |t, c|
+              t == table_name && c == col_name
+            end
           end
         end
       end

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

@@ -0,0 +1,89 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Flag conditional schema-change helpers (`add_column_if_not_exists`,
+        # `column_exists?`, etc.) inside migration files.
+        #
+        # ## Rationale
+        # Migrations are deterministic state transitions: "DB was at state N;
+        # after this migration it is at state N+1." Conditional schema helpers
+        # imply "I don't know what state the DB is in," which contradicts the
+        # migration model and hides schema drift.
+        #
+        # If a column "might already exist," that is a symptom — investigate
+        # why before papering over it with a defensive guard.
+        #
+        # The escape hatch is a per-line `rubocop:disable` comment with a
+        # rationale explaining the known-drift repair.
+        #
+        #   ❌ hides drift; state is unknown
+        #   add_column_if_not_exists :users, :something, :string
+        #   add_column :users, :bar, :string unless column_exists?(:users, :bar)
+        #
+        #   ✔️ declarative state transition
+        #   add_column :users, :something, :string
+        #
+        #   ✔️ documented one-shot drift repair (escape hatch)
+        #   # rubocop:disable DevDoc/Migration/AvoidConditionalSchemaChanges
+        #   add_column_if_not_exists :users, :something, :string
+        #   # rubocop:enable DevDoc/Migration/AvoidConditionalSchemaChanges
+        #
+        # @example
+        #   # bad
+        #   add_column_if_not_exists :users, :something, :string
+        #
+        #   # bad
+        #   add_index_if_not_exists :users, :email
+        #
+        #   # bad
+        #   remove_column_if_exists :users, :legacy
+        #
+        #   # bad (predicate guard shape)
+        #   add_column :users, :foo, :string unless column_exists?(:users, :foo)
+        #
+        #   # good
+        #   add_column :users, :something, :string
+        class AvoidConditionalSchemaChanges < Base
+          IF_NOT_EXISTS_METHODS = %i[
+            add_column_if_not_exists
+            add_index_if_not_exists
+            add_foreign_key_if_not_exists
+            add_reference_if_not_exists
+            remove_column_if_exists
+            remove_index_if_exists
+            remove_foreign_key_if_exists
+            remove_reference_if_exists
+          ].freeze
+
+          EXISTENCE_PREDICATES = %i[
+            column_exists?
+            table_exists?
+            index_exists?
+            foreign_key_exists?
+          ].freeze
+
+          MSG_IF_NOT_EXISTS =
+            '`%<method>s` hides schema drift. Use the non-conditional form and investigate ' \
+            'why states diverge. Suppress with a `rubocop:disable` comment only for documented ' \
+            'one-shot drift repairs.'.freeze
+
+          MSG_PREDICATE =
+            '`%<method>s` guard hides schema drift. Use unconditional schema operations and ' \
+            'investigate why states diverge. Suppress with a `rubocop:disable` comment only for ' \
+            'documented one-shot drift repairs.'.freeze
+
+          def on_send(node)
+            if IF_NOT_EXISTS_METHODS.include?(node.method_name)
+              add_offense(node.loc.selector,
+                          message: format(MSG_IF_NOT_EXISTS, method: node.method_name))
+            elsif EXISTENCE_PREDICATES.include?(node.method_name)
+              add_offense(node.loc.selector,
+                          message: format(MSG_PREDICATE, method: node.method_name))
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,27 +12,42 @@ module RuboCop
         #
         #   ❌
         #   t.json :metadata
+        #   add_column :users, :metadata, :json
         #
         #   ✔️
         #   t.jsonb :metadata
+        #   add_column :users, :metadata, :jsonb
         #
         # @example
         #   # bad
         #   t.json :metadata
+        #   add_column :users, :metadata, :json
         #
         #   # good
         #   t.jsonb :metadata
+        #   add_column :users, :metadata, :jsonb
         class AvoidJsonColumn < Base
           extend AutoCorrector
 
           MSG = 'Use `jsonb` instead of `json`. `jsonb` supports indexing and is faster to read.'.freeze
-          RESTRICT_ON_SEND = %i[json].freeze
+          RESTRICT_ON_SEND = %i[json add_column].freeze
 
           def on_send(node)
-            add_offense(node.loc.selector) do |corrector|
-              corrector.replace(node.loc.selector, 'jsonb')
+            if node.method_name == :add_column
+              check_add_column(node)
+            else
+              add_offense(node.loc.selector) { |c| c.replace(node.loc.selector, 'jsonb') }
             end
           end
+
+          private
+
+          def check_add_column(node)
+            type_arg = node.arguments[2]
+            return unless type_arg&.sym_type? && type_arg.value == :json
+
+            add_offense(type_arg) { |c| c.replace(type_arg, ':jsonb') }
+          end
         end
       end
     end

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

@@ -0,0 +1,121 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid `null: false` on regular columns.
+        #
+        # ## Rationale
+        # `null: false` on a regular column bakes a business rule (presence) into
+        # the schema. Presence belongs in the application layer (model
+        # validations), where it is easy to change.
+        #
+        # The test for whether `null: false` is justified is "what would NULL
+        # mean for this column?":
+        #
+        # - If NULL is — or could become — a meaningful business state, presence
+        #   is a business decision: keep it in the model. `email` NULL = a
+        #   phone-only user; `organization_id` NULL = an unowned template.
+        # - If NULL is never a meaningful state by the nature of the data, it is
+        #   a data-integrity concern and belongs in the schema (see Exception).
+        #
+        # The line is drawn for standardization and non-subjectivity. Whether a
+        # regular column is "required" is subjective and invites per-column
+        # debate (`email` looks required until phone signup makes it optional),
+        # so the schema should not bake in that debatable call.
+        #
+        #   ❌ Regular column
+        #   add_column :users, :profile_completion_rate, :float, null: false
+        #
+        #   ✔️ Regular column
+        #   add_column :users, :profile_completion_rate, :float
+        #
+        # ## Exception
+        # `null: false` IS the right choice where NULL is never a meaningful
+        # state:
+        #
+        # - **Required foreign keys** — NOT flagged: this cop never looks at
+        #   `belongs_to`, `references`, or `add_reference`. A required FK bundles
+        #   two things: `foreign_key: true` is pure referential integrity (never
+        #   a business decision), while `null: false` on the FK is a
+        #   *mandatory-ness* decision that can flip (a `document` may later be an
+        #   unowned template). Both are allowed in the schema pragmatically — the
+        #   referential-integrity guarantee carries the mandatory-ness with it.
+        # - **Enum columns** — NULL is outside the enum's domain (a type
+        #   violation), so `null: false` is required, and enforced from the model
+        #   side by `DevDoc/Rails/EnumColumnNotNull`. But an enum is a plain
+        #   `integer` column, statically indistinguishable from any other
+        #   integer, so THIS cop cannot detect it and WILL flag it. Disable it on
+        #   the line with a brief reason — `-- enum` — so the migration is
+        #   self-documenting: a reader sees at a glance that the column is an enum.
+        #
+        #   ✔️ Required foreign key (never flagged)
+        #   t.belongs_to :user, null: false, foreign_key: true
+        #
+        #   ✔️ Enum (flagged here — disable with a brief `-- enum` reason)
+        #   # rubocop:disable DevDoc/Migration/AvoidNonNull -- enum
+        #   add_column :orders, :status, :integer, null: false
+        #   # 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.
+        #
+        # @example
+        #   # bad
+        #   add_column :users, :name, :string, null: false
+        #
+        #   # bad (enum without a disable — the cop flags it; disable with `-- enum`)
+        #   t.integer :processing_status, null: false
+        #
+        #   # good
+        #   add_column :users, :name, :string
+        #
+        #   # good (required foreign key — never flagged)
+        #   t.belongs_to :user, null: false, foreign_key: true
+        class AvoidNonNull < Base
+          MSG = 'Avoid `null: false` on regular columns; enforce presence in the model layer. ' \
+                'If this is an enum column, disable this cop on the line with a brief reason, e.g. `-- enum`.'.freeze
+
+          # Column-definition helpers that take a `null:` option. Deliberately
+          # EXCLUDES `references` / `belongs_to` (and the separate `add_reference`
+          # method): a required foreign key SHOULD carry `null: false`, so those
+          # are never flagged.
+          COLUMN_METHODS = %i[
+            string integer float boolean datetime date text binary decimal
+            json jsonb bigint
+          ].freeze
+
+          RESTRICT_ON_SEND = (COLUMN_METHODS + %i[add_column]).freeze
+
+          def_node_matcher :null_false_pair, <<~PATTERN
+            (hash <$(pair (sym :null) (false)) ...>)
+          PATTERN
+
+          def on_send(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)
+          end
+
+          private
+
+          def column_method?(node)
+            node.method?(:add_column) || COLUMN_METHODS.include?(node.method_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid `create_join_table` — define an explicit join model instead.
+        #
+        # ## Rationale
+        # `create_join_table` produces a PK-less table tied to
+        # `has_and_belongs_to_many`, which has well-known limitations: no
+        # timestamps, no per-row callbacks, and no room for extra columns
+        # without migration gymnastics.
+        #
+        # The preferred Rails idiom is `has_many :through` with an explicit
+        # join model, which is just a normal table with a PK and timestamps.
+        #
+        #   ❌
+        #   create_join_table :products, :categories
+        #
+        #   ✔️ Define an explicit join model
+        #   create_table :product_categories do |t|
+        #     t.belongs_to :product, null: false, foreign_key: true
+        #     t.belongs_to :category, null: false, foreign_key: true
+        #     t.timestamps
+        #   end
+        #
+        #   # In models:
+        #   class Product < ApplicationRecord
+        #     has_many :product_categories
+        #     has_many :categories, through: :product_categories
+        #   end
+        #
+        # @example
+        #   # bad
+        #   create_join_table :products, :categories
+        #
+        #   # good
+        #   create_table :product_categories do |t|
+        #     t.belongs_to :product, null: false, foreign_key: true
+        #     t.belongs_to :category, null: false, foreign_key: true
+        #     t.timestamps
+        #   end
+        class NoCreateJoinTable < Base
+          MSG = 'Avoid `create_join_table` — define an explicit join model with `has_many :through` instead.'.freeze
+          RESTRICT_ON_SEND = %i[create_join_table].freeze
+
+          def on_send(node)
+            add_offense(node.loc.selector)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Every `create_table` migration must have a primary key.
+        #
+        # ## Rationale
+        # A table without a primary key is hard to reference, hard to debug,
+        # and hard to migrate later. `id: false` is rarely the right answer;
+        # `has_many :through` with an explicit join model is preferred for
+        # many-to-many relationships, and that join model has its own `id`.
+        #
+        #   ❌
+        #   create_table :products_categories, id: false do |t|
+        #     t.belongs_to :product
+        #     t.belongs_to :category
+        #   end
+        #
+        #   ✔️  Use an explicit join model with has_many :through instead
+        #   create_table :product_categories do |t|
+        #     t.belongs_to :product, null: false, foreign_key: true
+        #     t.belongs_to :category, null: false, foreign_key: true
+        #     t.timestamps
+        #   end
+        #
+        # @example
+        #   # bad
+        #   create_table :products_categories, id: false do |t|
+        #     t.belongs_to :product
+        #   end
+        #
+        #   # good
+        #   create_table :product_categories do |t|
+        #     t.belongs_to :product, null: false, foreign_key: true
+        #   end
+        class RequirePrimaryKey < Base
+          MSG = 'Every table must have a primary key. Avoid `id: false` — ' \
+                'use an explicit join model with `has_many :through` instead.'.freeze
+          RESTRICT_ON_SEND = %i[create_table].freeze
+
+          def_node_matcher :id_false_pair?, <<~PATTERN
+            (pair (sym :id) (false))
+          PATTERN
+
+          def on_send(node)
+            id_false = node.each_descendant(:pair).find { |pair| id_false_pair?(pair) }
+            return unless id_false
+
+            add_offense(id_false)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -10,6 +10,10 @@ module RuboCop
         # auditing, and ordering records, and adding them later is much more
         # painful than including them up front.
         #
+        # This rule applies to **every** `create_table` call, including those
+        # with `id: false`. If a genuinely timestamp-less table is needed, add
+        # an explicit `# rubocop:disable` with a rationale comment.
+        #
         #   ❌
         #   create_table :ai_api_failures do |t|
         #     t.belongs_to :ai_chat_message, null: false, foreign_key: true
@@ -24,9 +28,6 @@ module RuboCop
         #     t.timestamps
         #   end
         #
-        # NOTE: This cop skips tables declared with `id: false` (typically join
-        # tables), where omitting timestamps is a deliberate choice.
-        #
         # @example
         #   # bad
         #   create_table :users do |t|
@@ -54,13 +55,7 @@ module RuboCop
               ...)
           PATTERN
 
-          def_node_matcher :id_false_option?, <<~PATTERN
-            (pair (sym :id) (false))
-          PATTERN
-
           def on_send(node)
-            return if skip_table?(node)
-
             block = node.parent
             return unless block&.block_type?
             return if timestamps_present?(block.body)
@@ -72,10 +67,6 @@ module RuboCop
 
           private
 
-          def skip_table?(node)
-            node.each_descendant(:pair).any? { |pair| id_false_option?(pair) }
-          end
-
           def timestamps_present?(body)
             return false if body.nil?
 

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

@@ -0,0 +1,56 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Use `ApplicationRecord.transaction` instead of `SomeModel.transaction` outside model files.
+        #
+        # ## Rationale
+        # When using `transaction` outside of a model, `SomeModel.transaction`
+        # reads as if there is a meaningful link to that model when there isn't.
+        # `ApplicationRecord.transaction` is functionally identical and makes
+        # it clear that the transaction has no special relationship to any
+        # particular model.
+        #
+        #   ❌  (in a controller or service)
+        #   Post.transaction do
+        #     ...
+        #   end
+        #
+        #   ✔️
+        #   ApplicationRecord.transaction do
+        #     ...
+        #   end
+        #
+        # @example
+        #   # bad (in a controller or service)
+        #   Order.transaction do
+        #     order.save!
+        #   end
+        #
+        #   # good
+        #   ApplicationRecord.transaction do
+        #     order.save!
+        #   end
+        class ApplicationRecordTransaction < Base
+          extend AutoCorrector
+
+          ALLOWED_RECEIVERS = %w[ApplicationRecord ActiveRecord::Base].freeze
+
+          MSG = 'Use `ApplicationRecord.transaction` instead of `%<receiver>s.transaction` outside model files.'.freeze
+          RESTRICT_ON_SEND = %i[transaction].freeze
+
+          def on_send(node)
+            receiver = node.receiver
+            return if receiver.nil?
+            return unless receiver.const_type?
+            return if ALLOWED_RECEIVERS.include?(receiver.source)
+
+            add_offense(receiver, message: format(MSG, receiver: receiver.source)) do |corrector|
+              corrector.replace(receiver, 'ApplicationRecord')
+            end
+          end
+        end
+      end
+    end
+  end
+end