rubocop-dev_doc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 32fcdd022e9dde952826050d447d83e9fa7f9bf1cfaf7caaaddda3309e392a3b
+  data.tar.gz: e6775d4b37a1d763966c25eb3b2bf7926026b2ba2fdeae6d11fc05ae9d2ba46e
+SHA512:
+  metadata.gz: fb0572fc498d052e2f49d45490c37ddfcfa349d5a4e17b199159537b713cb5206ee828ffa96d5466c5e386e8da7713a22b5d3e51eca9daf228041be278fbe014
+  data.tar.gz: a96d7bcdb8c34f3b0ab557a8bee46ef6ce91028174728cf06efa7df2943dafe7b67a47b9dff813260f2c824c6d7b1094bb6bc69c15bcb63fbf1c2f0bfab62333

data/config/default.yml

@@ -0,0 +1,81 @@
+# Default configuration for rubocop-dev_doc cops.
+# Cops are enabled by default; disable them in your project's .rubocop.yml if needed.
+
+DevDoc/Migration/AvoidJsonColumn:
+  Description: 'Use `jsonb` instead of `json` for column types.'
+  Enabled: true
+  Include:
+    - 'db/migrate/*.rb'
+    - 'db/migrate/**/*.rb'
+
+DevDoc/Migration/RequireTimestamps:
+  Description: 'Always include `t.timestamps` in every `create_table` migration.'
+  Enabled: true
+  Include:
+    - 'db/migrate/*.rb'
+    - 'db/migrate/**/*.rb'
+
+DevDoc/Migration/PreferBelongsTo:
+  Description: 'Use `t.belongs_to` instead of `t.references` for foreign keys.'
+  Enabled: true
+  Include:
+    - 'db/migrate/*.rb'
+    - 'db/migrate/**/*.rb'
+
+DevDoc/Migration/AvoidColumnDefault:
+  Description: 'Avoid setting `default:` in migrations; keep business logic in the application layer.'
+  Enabled: true
+  Include:
+    - 'db/migrate/*.rb'
+    - 'db/migrate/**/*.rb'
+
+DevDoc/Migration/AvoidUpdateColumn:
+  Description: 'Avoid `update_column`/`update_all`/`update_columns`; they bypass validations and callbacks.'
+  Enabled: true
+  Include:
+    - 'db/migrate/*.rb'
+    - 'db/migrate/**/*.rb'
+
+DevDoc/Migration/DateColumnNaming:
+  Description: 'Date columns should end with `_on`; datetime columns should end with `_at`.'
+  Enabled: true
+  Include:
+    - 'db/migrate/*.rb'
+    - 'db/migrate/**/*.rb'
+
+DevDoc/Migration/AvoidVagueColumnNames:
+  Description: 'Avoid vague column names like `status` or `group`. Use more specific names.'
+  Enabled: true
+  VagueNames:
+    - status
+    - group
+  Include:
+    - 'db/migrate/*.rb'
+    - 'db/migrate/**/*.rb'
+
+DevDoc/Route/ResourcesRequireOnly:
+  Description: 'Always use `only:` or `except:` when defining `resources` or `resource` routes.'
+  Enabled: true
+  Include:
+    - 'config/routes.rb'
+    - 'config/routes/**/*.rb'
+
+DevDoc/Rails/NoDeliverLaterInTransaction:
+  Description: 'Avoid `deliver_later`/`perform_later` inside a `transaction` block; the job may use stale data.'
+  Enabled: true
+
+DevDoc/Rails/NoPerformLaterInModel:
+  Description: 'Avoid `perform_later` inside model files; use explicit methods called from the controller.'
+  Enabled: true
+  Include:
+    - 'app/models/**/*.rb'
+
+DevDoc/Style/AvoidSend:
+  Description: 'Avoid `send`/`public_send` with an explicit receiver; prefer direct calls or safer alternatives.'
+  Enabled: true
+
+DevDoc/Style/AvoidHeadResponse:
+  Description: 'Avoid `head()` responses; delegate error handling to Rails exceptions or model validations.'
+  Enabled: true
+  Include:
+    - 'app/controllers/**/*.rb'

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

@@ -0,0 +1,101 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid setting a `default:` value in migrations.
+        #
+        # ## Rationale
+        # Avoid adding business logic to the database. Keep it centralized in the
+        # application layer (controller or model) for easier maintenance and
+        # flexibility. A `default:` in a migration embeds a business-logic
+        # assumption into the database schema, which is harder to change later
+        # than code.
+        #
+        # Instead of relying on a database default, set the value explicitly in
+        # the application — and for existing rows, backfill via a reversible
+        # migration that goes through model validations:
+        #
+        #   ❌
+        #   class AddProfileCompletionRateToUsers < ActiveRecord::Migration[6.1]
+        #     def change
+        #       add_column :users, :profile_completion_rate, :float, default: 0.0
+        #     end
+        #   end
+        #
+        #   ✔
+        #   class AddProfileCompletionRateToUsers < ActiveRecord::Migration[6.1]
+        #     def change
+        #       add_column :users, :profile_completion_rate, :float
+        #
+        #       reversible do |dir|
+        #         dir.up do
+        #           # Make sure Rails picks up the new column.
+        #           User.reset_column_information
+        #
+        #           User.where(profile_completion_rate: nil).find_each do |user|
+        #             user.profile_completion_rate = 0.0
+        #             # This may fail if existing records are invalid (e.g. nil required fields).
+        #             # In that case, fix those records first rather than bypassing validation.
+        #             user.save!
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # ## Exception
+        # 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:
+        #
+        #   ✔
+        #   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
+        #
+        #   # bad
+        #   t.string :status, default: 'active'
+        #
+        #   # good
+        #   add_column :users, :score, :integer
+        #
+        #   # good (temporary default immediately removed)
+        #   add_column :users, :score, :integer, default: 0
+        #   change_column_default :users, :score, from: 0, to: nil
+        class AvoidColumnDefault < Base
+          MSG = 'Avoid setting `default:` in migrations. Keep business logic defaults in the application layer.'.freeze
+
+          COLUMN_METHODS = %i[
+            string integer float boolean datetime date text binary decimal
+            json jsonb bigint primary_key references belongs_to
+          ].freeze
+
+          def_node_matcher :has_default_option?, <<~PATTERN
+            (hash <(pair (sym :default) _) ...>)
+          PATTERN
+
+          def on_send(node)
+            return unless node.method?(:add_column) || COLUMN_METHODS.include?(node.method_name)
+
+            check_options(node.arguments.find(&:hash_type?))
+          end
+
+          private
+
+          def check_options(options)
+            return unless options && has_default_option?(options)
+
+            default_pair = options.pairs.find { |p| p.key.sym_type? && p.key.value == :default }
+            add_offense(default_pair)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Prefer `jsonb` over `json` for column types.
+        #
+        # ## Rationale
+        # `jsonb` stores data in a binary format that supports indexing,
+        # querying with operators (`->`, `->>`, `@>`), and is generally faster to
+        # read. Use `json` only if you need to preserve key order or exact
+        # formatting of the original JSON string — which is rare in practice.
+        #
+        #   ❌
+        #   t.json :metadata
+        #
+        #   ✔️
+        #   t.jsonb :metadata
+        #
+        # @example
+        #   # bad
+        #   t.json :metadata
+        #
+        #   # good
+        #   t.jsonb :metadata
+        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
+
+          def on_send(node)
+            add_offense(node.loc.selector) do |corrector|
+              corrector.replace(node.loc.selector, 'jsonb')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid `update_column`, `update_columns`, and `update_all` in migrations.
+        #
+        # ## Rationale
+        # Avoid bypassing validation unless absolutely necessary. These methods
+        # skip validations and callbacks, which hides data integrity issues
+        # rather than surfacing them.
+        #
+        # Even in migrations, check the code to see if there is any blatant
+        # reason why existing records may be invalid. If there is, fix those
+        # records first rather than bypassing validation.
+        #
+        #   ❌ Bypasses validation — hides data integrity issues
+        #   Faq.where(purpose: nil).update_all(purpose: :intro)
+        #
+        #   ✔️ Runs validation — surfaces problems early
+        #   Faq.where(purpose: nil).find_each do |faq|
+        #     faq.purpose = :intro
+        #     faq.save!
+        #   end
+        #
+        # NOTE: The broader principle ("avoid bypassing validation") also covers
+        # things this cop does not catch, e.g. `save(validate: false)`,
+        # `insert_all`, `upsert_all`, `delete_all`. Apply the same judgement to
+        # those patterns.
+        #
+        # @example
+        #   # bad
+        #   Faq.where(purpose: nil).update_all(purpose: :intro)
+        #
+        #   # bad
+        #   user.update_column(:status, 'active')
+        #
+        #   # good
+        #   Faq.where(purpose: nil).find_each do |faq|
+        #     faq.purpose = :intro
+        #     faq.save!
+        #   end
+        class AvoidUpdateColumn < Base
+          MSG = 'Avoid `%<method>s` in migrations; it bypasses validations. Use `save!` instead.'.freeze
+          RESTRICT_ON_SEND = %i[update_column update_columns update_all].freeze
+
+          def on_send(node)
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid vague column names like `status` or `group`.
+        #
+        # ## Rationale
+        # Use more specific names that describe the domain context. A column
+        # named `status` reveals nothing about *what* status it tracks; a column
+        # named `processing_status` makes the intent obvious at the call site.
+        #
+        #   ❌
+        #   t.string :status
+        #   add_column :orders, :group, :integer
+        #
+        #   ✔️
+        #   t.string :processing_status
+        #   add_column :orders, :user_group, :integer
+        #
+        # ## Note about `type`
+        # `type` is reserved by Rails for Single Table Inheritance (STI). Even
+        # if STI is not in use, naming a column `type` is misleading and should
+        # be avoided. This cop does not flag `type` by default — that is left
+        # to the user's discretion via the `VagueNames` config.
+        #
+        # Configure the list of vague names via `VagueNames` in .rubocop.yml.
+        #
+        # @example
+        #   # bad
+        #   t.string :status
+        #   add_column :orders, :group, :integer
+        #
+        #   # good
+        #   t.string :processing_status
+        #   add_column :orders, :user_group, :integer
+        class AvoidVagueColumnNames < Base
+          MSG = 'Avoid vague column name `%<name>s`. Use a more specific name that includes context.'.freeze
+
+          COLUMN_METHODS = %i[
+            string integer float boolean datetime date text binary decimal
+            json jsonb bigint primary_key
+          ].freeze
+
+          def on_send(node)
+            col_name_node = if node.method?(:add_column)
+                              node.arguments[1]
+                            elsif COLUMN_METHODS.include?(node.method_name)
+                              node.first_argument
+                            end
+
+            return unless col_name_node&.sym_type?
+            return unless vague_names.include?(col_name_node.value.to_s)
+
+            add_offense(col_name_node, message: format(MSG, name: col_name_node.value))
+          end
+
+          private
+
+          def vague_names
+            cop_config.fetch('VagueNames', %w[status group])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Date columns should end with `_on`; datetime columns should end with `_at`.
+        #
+        # ## Rationale
+        # Use the suffix `_on` for `date` columns and `_at` for `datetime`
+        # columns. This convention makes the column type immediately clear from
+        # the name, without having to look at the schema. For example:
+        #
+        #   service_subscription.expiring_on    # date
+        #   service_subscription.expired_at     # datetime
+        #
+        # @example
+        #   # bad
+        #   t.date :expiry
+        #   t.datetime :created
+        #   add_column :users, :birth, :date
+        #
+        #   # good
+        #   t.date :expiring_on
+        #   t.datetime :created_at
+        #   add_column :users, :born_on, :date
+        class DateColumnNaming < Base
+          DATE_MSG = 'Date column `%<name>s` should end with `_on` (e.g. `%<name>s_on`).'.freeze
+          DATETIME_MSG = 'Datetime column `%<name>s` should end with `_at` (e.g. `%<name>s_at`).'.freeze
+
+          def on_send(node)
+            if node.method?(:add_column)
+              check_add_column(node)
+            elsif %i[date datetime timestamptz].include?(node.method_name)
+              check_column_definition(node)
+            end
+          end
+
+          private
+
+          def check_add_column(node)
+            col_name_node = node.arguments[1]
+            type_node = node.arguments[2]
+            return unless col_name_node&.sym_type? && type_node&.sym_type?
+
+            check_name(col_name_node, type_node.value)
+          end
+
+          def check_column_definition(node)
+            col_name_node = node.first_argument
+            return unless col_name_node&.sym_type?
+
+            check_name(col_name_node, node.method_name)
+          end
+
+          def check_name(col_name_node, col_type)
+            name = col_name_node.value.to_s
+            case col_type.to_sym
+            when :date
+              return if name.end_with?('_on')
+
+              add_offense(col_name_node, message: format(DATE_MSG, name: name))
+            when :datetime, :timestamptz
+              return if name.end_with?('_at')
+
+              add_offense(col_name_node, message: format(DATETIME_MSG, name: name))
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Prefer `t.belongs_to` over `t.references` for foreign keys.
+        #
+        # ## Rationale
+        # `t.belongs_to` and `t.references` are aliases and functionally
+        # identical. Prefer `belongs_to` because it matches the model's
+        # association declaration (`belongs_to :user`), which makes the
+        # migration easier to map to the model and improves readability.
+        #
+        #   ❌
+        #   t.references :user, foreign_key: true, null: false
+        #
+        #   ✔️
+        #   t.belongs_to :user, foreign_key: true, null: false
+        #
+        # @example
+        #   # bad
+        #   t.references :user, foreign_key: true, null: false
+        #
+        #   # good
+        #   t.belongs_to :user, foreign_key: true, null: false
+        class PreferBelongsTo < Base
+          extend AutoCorrector
+
+          MSG = 'Use `t.belongs_to` instead of `t.references` ' \
+                '(aliases, but `belongs_to` matches the model association).'.freeze
+          RESTRICT_ON_SEND = %i[references].freeze
+
+          def on_send(node)
+            add_offense(node.loc.selector) do |corrector|
+              corrector.replace(node.loc.selector, 'belongs_to')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Every `create_table` migration must include `t.timestamps`.
+        #
+        # ## Rationale
+        # Every table should have `created_at` and `updated_at` columns —
+        # there is no reason to omit them. They are essential for debugging,
+        # auditing, and ordering records, and adding them later is much more
+        # painful than including them up front.
+        #
+        #   ❌
+        #   create_table :ai_api_failures do |t|
+        #     t.belongs_to :ai_chat_message, null: false, foreign_key: true
+        #     t.string :error_type
+        #     t.datetime :created_at
+        #   end
+        #
+        #   ✔️
+        #   create_table :ai_api_failures do |t|
+        #     t.belongs_to :ai_chat_message, null: false, foreign_key: true
+        #     t.string :error_type
+        #     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|
+        #     t.string :name
+        #   end
+        #
+        #   # good
+        #   create_table :users do |t|
+        #     t.string :name
+        #     t.timestamps
+        #   end
+        class RequireTimestamps < Base
+          extend AutoCorrector
+
+          MSG = 'Add `t.timestamps` to this `create_table` migration.'.freeze
+          RESTRICT_ON_SEND = %i[create_table].freeze
+
+          def_node_search :timestamps_included?, <<~PATTERN
+            (send _ :timestamps ...)
+          PATTERN
+
+          def_node_search :manual_timestamp_column?, <<~PATTERN
+            (send _ {:datetime :timestamptz}
+              {(sym {:created_at :updated_at}) (str {"created_at" "updated_at"})}
+              ...)
+          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)
+
+            add_offense(node.loc.selector) do |corrector|
+              autocorrect(corrector, block)
+            end
+          end
+
+          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?
+
+            timestamps_included?(body) || manual_timestamp_column?(body)
+          end
+
+          def autocorrect(corrector, block)
+            return unless block.multiline?
+
+            table_var = block.arguments.first&.source || 't'
+            end_range = block.loc.end
+            indent = ' ' * (end_range.column + 2)
+            line_start_pos = end_range.begin_pos - end_range.column
+            insert_range = end_range.with(begin_pos: line_start_pos, end_pos: line_start_pos)
+            corrector.insert_before(insert_range, "#{indent}#{table_var}.timestamps\n")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Avoid `deliver_later` and `perform_later` inside a `transaction` block.
+        #
+        # ## Rationale
+        # Do not use `perform_later` or `deliver_later` inside a transaction
+        # block because there is a possibility that the job will use stale data,
+        # as the transaction has not yet completed (not yet committed changes
+        # to the database).
+        #
+        #   ❌
+        #   organization.transaction do
+        #     if organization.save
+        #       # This mailer may receive the organization with stale data
+        #       # (data before `save()`)
+        #       OrganizationMailer.with(organization: organization).deliver_later
+        #     end
+        #   end
+        #
+        #   ✔️
+        #   organization.transaction do
+        #     save_succeeded = organization.save
+        #   end
+        #   if save_succeeded
+        #     OrganizationMailer.with(organization: organization).deliver_later
+        #   end
+        #
+        # ## Watch out for indirect calls
+        # Some libraries call `perform_later` / `deliver_later` behind the
+        # scenes — e.g. `@user.send_verification_email!` from the Devise gem.
+        # This cop cannot detect those wrappers; reviewers should still flag
+        # them when they appear inside a `transaction` block.
+        #
+        # @example
+        #   # bad
+        #   organization.transaction do
+        #     organization.save!
+        #     OrganizationMailer.with(organization: organization).deliver_later
+        #   end
+        #
+        #   # good
+        #   organization.transaction do
+        #     organization.save!
+        #   end
+        #   OrganizationMailer.with(organization: organization).deliver_later
+        class NoDeliverLaterInTransaction < Base
+          MSG = '`%<method>s` inside a `transaction` block may use stale data. Move it outside the transaction.'.freeze
+          RESTRICT_ON_SEND = %i[deliver_later perform_later].freeze
+
+          def on_send(node)
+            return unless inside_transaction?(node)
+
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+
+          private
+
+          def inside_transaction?(node)
+            node.each_ancestor(:block).any? do |ancestor|
+              ancestor.method_name == :transaction
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Avoid `perform_later` calls inside model files.
+        #
+        # ## Rationale
+        # Avoid using ActiveJob inside Models, because:
+        #
+        # - It is prone to conflicts between `transaction` and `perform_later`
+        #   (the job may run before the transaction commits and read stale data
+        #   — see `DevDoc/Rails/NoDeliverLaterInTransaction`).
+        # - Execution flow control should be done in the Controller, not in the
+        #   Model.
+        # - If it really must be done in the Model, name the method explicitly
+        #   so the side effect is obvious at the call site.
+        #
+        #   ❌  (in app/models/order.rb)
+        #   def finalize
+        #     save!
+        #     OrderJob.perform_later(self)
+        #   end
+        #
+        #   ✔️ Explicit method name signals the side effect; reviewers
+        #     immediately see that this should not be called inside a
+        #     `transaction` block.
+        #   def save_with_email_sending
+        #     save!
+        #     OrderJob.perform_later(self)
+        #   end
+        #
+        # NOTE: This cop flags *any* `perform_later` in `app/models/**/*.rb`,
+        # including the legitimate "explicitly named method" case above. The
+        # cop is intentionally conservative — disable per-line with a rubocop
+        # comment when you have deliberately followed the naming convention.
+        #
+        # @example
+        #   # bad (in app/models/order.rb)
+        #   def finalize
+        #     save!
+        #     OrderJob.perform_later(self)
+        #   end
+        #
+        #   # good — explicit method communicates the side effect
+        #   def finalize_with_job
+        #     save!
+        #     OrderJob.perform_later(self)
+        #   end
+        class NoPerformLaterInModel < Base
+          MSG = 'Avoid `perform_later` in model files. Call it from the controller, ' \
+                'or use an explicit method name to signal the side effect.'.freeze
+          RESTRICT_ON_SEND = %i[perform_later].freeze
+
+          def on_send(node)
+            add_offense(node.loc.selector)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/route/resources_require_only.rb

@@ -0,0 +1,59 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Route
+        # Always use `only:` (or `except:`) for `resources` / `resource` in routes.rb.
+        #
+        # ## Rationale
+        # When defining routes in routes.rb, it is important to explicitly
+        # specify the desired actions using the `only` option. This helps
+        # prevent accidentally exposing actions that should not be accessible
+        # — leaving the default opens the full RESTful set, which often
+        # exposes routes the application has no controller action for, or
+        # routes that probably should be locked down.
+        #
+        #   ✔️
+        #   resources :job_applications, only: [:index, :new, :create]
+        #
+        # In this example, only three actions are exposed for
+        # `job_applications`: index, new, and create. This is safer because
+        # only the needed actions are declared and accessible.
+        #
+        # `except:` is also acceptable, but `only:` is preferred because it
+        # is more explicit about what is being exposed.
+        #
+        # @example
+        #   # bad
+        #   resources :users
+        #   resource :profile
+        #
+        #   # good
+        #   resources :users, only: %i[index show]
+        #   resource :profile, only: %i[show edit update]
+        #   resources :users, except: [:destroy]
+        class ResourcesRequireOnly < Base
+          MSG = 'Specify `only:` or `except:` for `%<method>s :%<name>s` to avoid exposing unintended actions.'.freeze
+          RESTRICT_ON_SEND = %i[resources resource].freeze
+
+          def on_send(node)
+            return if only_or_except?(node)
+
+            name = node.first_argument&.value || '?'
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name, name: name))
+          end
+
+          private
+
+          def only_or_except?(node)
+            options = node.arguments.find(&:hash_type?)
+            return false unless options
+
+            options.pairs.any? do |pair|
+              pair.key.sym_type? && %i[only except].include?(pair.key.value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Avoid `head()` responses in controllers.
+        #
+        # ## Rationale
+        # `head()` returns an empty body with no useful information for the
+        # client. Its presence is usually a sign that error handling should be
+        # delegated to Rails exceptions (e.g. `ActiveRecord::RecordNotFound`)
+        # or model validations instead.
+        #
+        # If you find yourself reaching for `head()`, consider whether a
+        # well-known Rails exception or a model validation can handle the
+        # case more cleanly:
+        #
+        #   ❌ Manually returns 404 with no body
+        #   def show
+        #     @user = User.find_by(id: params[:id])
+        #     head(:not_found) unless @user
+        #   end
+        #
+        #   ✔️ Let Rails raise RecordNotFound — it renders the standard 404
+        #   def show
+        #     @user = User.find(params[:id])
+        #   end
+        #
+        # NOTE: The cop flags every bare `head(...)` call. Some legitimate uses
+        # (e.g. `head :no_content` for a successful DELETE, or simple webhook
+        # acknowledgements) still get flagged — disable per-line in those cases.
+        #
+        # @example
+        #   # bad
+        #   def glib_load_resource
+        #     @user = User.find_by(id: params[:id])
+        #     head(:not_found) unless @user
+        #   end
+        #
+        #   # good
+        #   def glib_load_resource
+        #     @user = User.find(params[:id])
+        #   end
+        class AvoidHeadResponse < Base
+          MSG = 'Avoid `head()`. Delegate error handling to Rails exceptions ' \
+                '(e.g. use `find` instead of `find_by` + `head(:not_found)`) or model validations.'.freeze
+          RESTRICT_ON_SEND = %i[head].freeze
+
+          def on_send(node)
+            return unless node.receiver.nil?
+
+            add_offense(node.loc.selector)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Avoid `send` and `public_send` with an explicit receiver.
+        #
+        # ## Rationale
+        # `send()` can call *any* method, including destructive ones like
+        # `destroy`. When the method name is dynamic, this is a real risk — a
+        # crafted parameter can invoke methods the developer never intended to
+        # expose. If `send()` is unavoidable, add safeguards to restrict which
+        # methods can be called.
+        #
+        # ## Safer alternatives
+        #
+        # **a) For model attributes — use bracket notation instead.**
+        # `@model[column_name]` only accesses database columns, so it cannot
+        # accidentally invoke methods like `destroy`.
+        #
+        #   ❌ Dangerous — method_name could be :destroy or any other method
+        #   @user.send(method_name)
+        #
+        #   ✔️ Safe — only accesses database columns
+        #   @user[method_name]
+        #
+        # **b) For non-model objects — use a prefix to restrict callable methods.**
+        # By interpolating the dynamic part into a fixed prefix, only methods
+        # with that prefix (e.g. `export_csv`, `export_pdf`) can be invoked,
+        # preventing accidental calls to unintended methods.
+        #
+        #   ❌ Unrestricted — any method can be called
+        #   obj.send(method_name)
+        #
+        #   ✔️ Restricted — only methods with the prefix can be called
+        #   obj.send("export_#{method_name}")
+        #
+        # **c) For known methods — call directly instead of via `send`.**
+        #
+        # @example
+        #   # bad
+        #   @user.send(method_name)
+        #   obj.public_send(action)
+        #
+        #   # good
+        #   @user[attribute_name]
+        #   obj.send("export_#{method_name}")
+        class AvoidSend < Base
+          MSG = 'Avoid `%<method>s` with an explicit receiver. ' \
+                'Use bracket notation for model attributes, or restrict callable methods with a prefix.'.freeze
+          RESTRICT_ON_SEND = %i[send public_send].freeze
+
+          def on_send(node)
+            return if node.receiver.nil?
+
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/plugin.rb

@@ -0,0 +1,26 @@
+module RuboCop
+  module DevDoc
+    class Plugin < LintRoller::Plugin
+      def about
+        LintRoller::About.new(
+          name: "rubocop-dev_doc",
+          version: VERSION,
+          homepage: "https://github.com/hgani/dev-doc",
+          description: "RuboCop cops enforcing dev-doc best practices"
+        )
+      end
+
+      def supported?(context)
+        context.engine == :rubocop
+      end
+
+      def rules(_context)
+        LintRoller::Rules.new(
+          type: :path,
+          config_format: :rubocop,
+          value: RuboCop::DevDoc::CONFIG_DEFAULT
+        )
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -0,0 +1,5 @@
+module RuboCop
+  module DevDoc
+    VERSION = "0.1.0".freeze
+  end
+end

data/lib/rubocop/dev_doc.rb

@@ -0,0 +1,13 @@
+require_relative "dev_doc/version"
+require_relative "dev_doc/plugin"
+
+module RuboCop
+  module DevDoc
+    PROJECT_ROOT = Pathname.new(__dir__).parent.parent.expand_path.freeze
+    CONFIG_DEFAULT = PROJECT_ROOT.join("config", "default.yml").freeze
+  end
+end
+
+RuboCop::ConfigLoader.ignore_parent_exclusion = true
+
+Dir[File.join(__dir__, "cop", "dev_doc", "**", "*.rb")].each { |f| require f }

data/lib/rubocop-dev_doc.rb

@@ -0,0 +1,3 @@
+require "rubocop"
+require "lint_roller"
+require_relative "rubocop/dev_doc"

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-dev_doc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dev-doc contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- config/default.yml
+- lib/rubocop-dev_doc.rb
+- lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb
+- lib/rubocop/cop/dev_doc/migration/avoid_json_column.rb
+- lib/rubocop/cop/dev_doc/migration/avoid_update_column.rb
+- lib/rubocop/cop/dev_doc/migration/avoid_vague_column_names.rb
+- lib/rubocop/cop/dev_doc/migration/date_column_naming.rb
+- lib/rubocop/cop/dev_doc/migration/prefer_belongs_to.rb
+- lib/rubocop/cop/dev_doc/migration/require_timestamps.rb
+- lib/rubocop/cop/dev_doc/rails/no_deliver_later_in_transaction.rb
+- lib/rubocop/cop/dev_doc/rails/no_perform_later_in_model.rb
+- lib/rubocop/cop/dev_doc/route/resources_require_only.rb
+- lib/rubocop/cop/dev_doc/style/avoid_head_response.rb
+- lib/rubocop/cop/dev_doc/style/avoid_send.rb
+- lib/rubocop/dev_doc.rb
+- lib/rubocop/dev_doc/plugin.rb
+- lib/rubocop/dev_doc/version.rb
+licenses: []
+metadata:
+  default_lint_roller_plugin: RuboCop::DevDoc::Plugin
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: RuboCop cops enforcing dev-doc best practices
+test_files: []