rubocop-dev_doc 0.2.0 → 0.3.0

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

@@ -0,0 +1,127 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Flag bare (return-value-discarded) `save`/`update`/`create` calls inside
+        # a `transaction` block.
+        #
+        # ## Rationale
+        # Inside a transaction a non-bang `save` / `update` / `create` whose return
+        # value is discarded is almost always a bug. The transaction does **not**
+        # roll back on a `false` return — execution continues as if the write
+        # succeeded, silently producing inconsistent data.
+        #
+        # Checking the return value (as a condition or assignment) is allowed,
+        # as is the bang form. Only the bare-statement form is flagged.
+        #
+        #   ❌ silent failure — transaction does not roll back
+        #   ApplicationRecord.transaction do
+        #     @order.save
+        #     create_child_records(...)
+        #   end
+        #
+        #   ✔️ return value gated — ok
+        #   ApplicationRecord.transaction do
+        #     if @order.save
+        #       create_child_records(...)
+        #     end
+        #   end
+        #
+        #   ✔️ bang method — raises on failure, rolls back
+        #   ApplicationRecord.transaction do
+        #     @order.save!
+        #     create_child_records(...)
+        #   end
+        #
+        # @example
+        #   # bad
+        #   ApplicationRecord.transaction do
+        #     @order.save
+        #     create_child_records(params)
+        #   end
+        #
+        #   # good
+        #   ApplicationRecord.transaction do
+        #     if @order.save
+        #       create_child_records(params)
+        #     end
+        #   end
+        #
+        #   # good
+        #   ApplicationRecord.transaction do
+        #     result = @order.save
+        #     create_child_records(params) if result
+        #   end
+        #
+        #   # good
+        #   ApplicationRecord.transaction do
+        #     @order.save!
+        #     create_child_records(params)
+        #   end
+        class BangSaveInTransaction < Base
+          extend AutoCorrector
+
+          MSG = 'Use `%<bang>s` inside a `transaction` block, or check its return value. ' \
+                'A non-bang call whose return value is discarded does not roll back the transaction on failure.'.freeze
+
+          FLAGGED_METHODS = %i[save update create].freeze
+
+          # Node types whose parent always means the return value is consumed.
+          CONSUMING_PARENT_TYPES = %i[
+            and or return
+            send csend
+            lvasgn ivasgn cvasgn gvasgn casgn masgn
+            array hash pair
+          ].freeze
+
+          def on_send(node)
+            return unless FLAGGED_METHODS.include?(node.method_name)
+            return unless inside_transaction?(node)
+            return if return_value_used?(node)
+
+            bang = :"#{node.method_name}!"
+            add_offense(node.loc.selector, message: format(MSG, bang: bang)) do |corrector|
+              corrector.replace(node.loc.selector, bang.to_s)
+            end
+          end
+
+          private
+
+          def inside_transaction?(node)
+            node.each_ancestor(:block).any? do |ancestor|
+              ancestor.method_name == :transaction
+            end
+          end
+
+          def return_value_used?(node)
+            parent = node.parent
+            return false if parent.nil?
+
+            return false if discarding_parent?(parent, node)
+            return true  if CONSUMING_PARENT_TYPES.include?(parent.type)
+            return parent.condition == node if conditional_parent?(parent)
+
+            false
+          end
+
+          def discarding_parent?(parent, node)
+            bare_sequence?(parent) || block_body?(parent, node)
+          end
+
+          def bare_sequence?(parent)
+            %i[begin kwbegin].include?(parent.type)
+          end
+
+          # A single-statement block body: the node IS the body of the block.
+          def block_body?(parent, node)
+            parent.block_type? && parent.body == node
+          end
+
+          def conditional_parent?(parent)
+            %i[if while until].include?(parent.type)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Enum columns must be backed by a `null: false` database column.
+        #
+        # ## Rationale
+        # `null: false` is reserved for cases where NULL has no meaningful
+        # interpretation — and an enum is the clearest such case. NULL is
+        # outside the enum's domain (a type violation, not one of the defined
+        # values), and if "unset" is meaningful it should be modeled as an
+        # explicit enum value, never as NULL.
+        #
+        # The line is drawn here for standardization and non-subjectivity.
+        # Whether a *regular* column should be present is a business decision
+        # open to debate (could `email` become optional once phone signup
+        # exists?), so it is left to model-layer judgment. An enum's
+        # non-null-ness is objective — it does not depend on any business
+        # decision — so it is enforced mechanically rather than argued
+        # column-by-column.
+        #
+        # This cop is the inverse of `DevDoc/Migration/AvoidNonNull`: that cop
+        # runs on the migration and strips `null: false` from regular columns;
+        # this cop runs on the model, reads `db/schema.rb`, and requires
+        # `null: false` on the column backing each `enum`.
+        #
+        # ## Interaction with AvoidNonNull
+        # An enum is a plain `integer` column, so `AvoidNonNull` cannot tell it
+        # apart from a regular integer and WILL flag the `null: false` you add
+        # to satisfy this cop. Disable it on that migration with a brief `-- enum`
+        # reason, so the migration is self-documenting:
+        #
+        #   # rubocop:disable DevDoc/Migration/AvoidNonNull -- enum
+        #   add_column :orders, :status, :integer, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #
+        # NOTE: This cop reads `db/schema.rb` and does nothing if it is absent
+        # (e.g. projects using `structure.sql`). It also relies on the schema
+        # being current, resolves the table name by Rails convention (STI,
+        # `self.table_name` overrides, or namespaced models may not resolve),
+        # recognizes only the positional `enum :name, …` form, and skips
+        # silently if the backing column cannot be found in the schema.
+        #
+        # @example
+        #   # bad - the `status` column is nullable in db/schema.rb
+        #   class Order < ApplicationRecord
+        #     enum :status, { active: 0, archived: 1 }
+        #   end
+        #
+        #   # good - the `status` column is `null: false` in db/schema.rb
+        #   class Order < ApplicationRecord
+        #     enum :status, { active: 0, archived: 1 }
+        #   end
+        class EnumColumnNotNull < Base
+          include ActiveRecordHelper
+
+          MSG = 'Enum column `%<name>s` should be `null: false` — NULL is outside an enum\'s domain. ' \
+                'Model "unset" as an explicit enum value.'.freeze
+
+          RESTRICT_ON_SEND = %i[enum].freeze
+
+          def_node_matcher :enum_call, <<~PATTERN
+            (send nil? :enum (sym $_) ...)
+          PATTERN
+
+          def on_send(node)
+            name = nullable_enum_name(node)
+            return unless name
+
+            add_offense(node, message: format(MSG, name: name))
+          end
+
+          private
+
+          # The enum's attribute name if it is backed by a nullable column, else nil.
+          def nullable_enum_name(node)
+            return unless schema
+
+            name = enum_call(node)
+            klass = name && class_node(node)
+            return unless klass
+
+            column = enum_column(klass, name)
+            name if column && !column.not_null
+          end
+
+          def enum_column(klass, name)
+            table = schema.table_by(name: table_name(klass))
+            table&.columns&.find { |c| c.name == name.to_s }
+          end
+
+          def class_node(node)
+            node.each_ancestor.find(&:class_type?)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -15,12 +15,12 @@ module RuboCop
         # See `best_practices/backend/en/01a_defensive_programming.md` item 7.
         #
         #   ❌
-        #   class Reimbursement < ApplicationRecord
+        #   class Order < ApplicationRecord
         #     enum :payment_status, { draft: 0, pending: 1, finalized: 2 }
         #   end
         #
         #   ✔
-        #   class Reimbursement < ApplicationRecord
+        #   class Order < ApplicationRecord
         #     enum :payment_status, { draft: 0, pending: 1, finalized: 2 }
         #
         #     enum_symbolize :payment_status

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

@@ -0,0 +1,236 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Avoid block-form predicates on ActiveRecord relations.
+        #
+        # ## Rationale
+        # `.count { }`, `.reject { }`, `.select { }`, `.any? { }`, and
+        # `.find { }` accept a block, which silently converts the relation to
+        # an Array — every row is loaded into Ruby memory and filtered there,
+        # defeating database indexes and pagination.
+        #
+        # Push the predicate into SQL with `.where(...)` or a model scope so
+        # the database does the filtering.
+        #
+        #   ❌ Loads every pending record into memory before counting
+        #   pending_subscriptions.count { |s| !s.expired_for_context? }
+        #
+        #   ✔️ Becomes a SQL COUNT via a scope
+        #   class Subscription < ApplicationRecord
+        #     scope :not_expired_for_context, ->(context) { ... }
+        #   end
+        #
+        #   pending_subscriptions.not_expired_for_context(context).count
+        #
+        # ## Exception
+        # Some predicates genuinely can't be expressed in SQL (decrypted
+        # attributes, non-trivial Ruby logic). For those, add a
+        # `# rubocop:disable` with a brief reason.
+        #
+        # ## Excluded receivers
+        # To keep false positives low, the cop skips receivers that clearly
+        # aren't AR relations: array literals (`[...]`), hash literals
+        # (`{...}`), screaming-case constants (e.g. `PRICING_PLANS`), and
+        # send-chains ending in a method known to return a non-Relation:
+        # * Array-returning — `pluck`, `to_a`, `map`, `flatten`, `compact`,
+        #   `uniq`, `sort`, `sort_by`, `reduce`, `inject`, `each_with_object`,
+        #   `zip`, `take`, `drop`, `group_by`, `partition`, `tally`,
+        #   `chunk_while`, `slice_when`, etc.
+        # * Hash-returning — `slice`, `except`, `merge`, `transform_values`,
+        #   `transform_keys`, `to_h`, `compact_blank`,
+        #   `with_indifferent_access`.
+        # * Enumerator-returning — `each_with_index`, `each_slice`,
+        #   `each_cons`, `lazy`, `with_index`, `with_object`. Calling these
+        #   on a Relation forces eager loading; the next `.select`/etc. then
+        #   operates on an in-memory Enumerator, so pushing into SQL is no
+        #   longer possible.
+        #
+        # Parenthesised receivers (`(expr).select { ... }`) are looked through
+        # to `expr` so the rules above still apply.
+        #
+        # ## Excluded block shapes
+        # Even when the receiver is opaque (a local/instance variable, method
+        # parameter, etc.), the block itself sometimes proves the element
+        # can't be an AR record:
+        # * **2+ block arguments** — `|k, v|`, `|item, _index|`, etc. AR
+        #   relations only yield single records; multi-arg destructuring
+        #   means the iterator is Hash#each, zip, or similar.
+        # * **Symbol-key indexing on the block arg** — `arg[:foo]` proves
+        #   the element is a Hash (AR's `[]` is rarely called with literal
+        #   symbol keys).
+        # * **Single-char string indexing on the block arg** — `c[0] == '+'`
+        #   proves the element is a String.
+        #
+        # ## Configuration
+        # `AdditionalNonRelationMethods` (default `[]`): per-project list of
+        # method names that return non-Relation collections. Useful when a
+        # codebase has its own helper methods returning plain Arrays / Hashes
+        # (e.g. a presenter factory) — adding them here lets the cop skip
+        # send-chains ending in those methods. Example:
+        #
+        #   DevDoc/Rails/NoBlockPredicateOnRelation:
+        #     AdditionalNonRelationMethods:
+        #       - all_items
+        #       - for_account
+        #       - gst_registration_ranges
+        #
+        # NOTE: The cop cannot determine whether a local variable, instance
+        # variable, or method parameter is an AR relation or a plain
+        # collection. When the receiver is in fact a plain Array/Hash, add
+        # `# rubocop:disable DevDoc/Rails/NoBlockPredicateOnRelation` with a
+        # brief reason — the friction is intentional and ensures the choice
+        # is reviewed.
+        #
+        # @example
+        #   # bad
+        #   pending_memberships.count { |m| !m.expired? }
+        #
+        #   # bad
+        #   user.posts.reject { |post| post.archived? }
+        #
+        #   # bad
+        #   Model.where(active: true).any? { |r| r.flagged? }
+        #
+        #   # good
+        #   pending_memberships.not_expired.count
+        #
+        #   # good (receiver returns Array — excluded)
+        #   user.posts.pluck(:title).reject(&:blank?)
+        #
+        #   # good (Hash#values — excluded)
+        #   PRICING_PLANS.reject { |_k, v| v.archived? }
+        class NoBlockPredicateOnRelation < Base
+          MSG = '`%<method>s` with a block loads every row into Ruby. ' \
+                'Push the predicate into SQL with `.where(...)` or a model scope.'.freeze
+
+          RESTRICT_ON_SEND = %i[count reject select find any?].freeze
+
+          # Methods whose return value is known to be a non-Relation collection
+          # (Array, Hash, or Enumerator). When a `.select`/`.reject`/etc. with a
+          # block is chained onto a call to one of these, the block runs over
+          # the materialised collection — pushing into SQL isn't possible.
+          NON_RELATION_RETURNING_METHODS = %i[
+            pluck pluck_to_hash
+            to_a to_ary
+            values keys
+            map flat_map collect collect_concat filter_map
+            flatten compact uniq sort sort_by reverse
+            reduce inject each_with_object
+            split lines chars bytes
+            zip take drop drop_while take_while
+            group_by partition tally tally_by chunk_while slice_when
+
+            slice except merge transform_values transform_keys to_h
+            compact_blank with_indifferent_access index_by index_with
+
+            each_with_index each_slice each_cons each_entry each_key each_value each_pair
+            chunk slice_before slice_after lazy with_index with_object
+          ].freeze
+
+          def on_send(node)
+            return unless node.block_literal?
+            return if node.receiver.nil?
+            return if excluded_receiver?(node.receiver)
+            return if excluded_block?(node)
+
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+
+          private
+
+          def excluded_receiver?(receiver)
+            return true if receiver.array_type? || receiver.hash_type?
+            return true if receiver.const_type? && screaming_case_const?(receiver)
+            return excluded_receiver?(receiver.children.first) if receiver.begin_type?
+            return true if receiver.send_type? && non_relation_method?(receiver.method_name)
+
+            false
+          end
+
+          # Merge built-in known-safe methods with project-specific ones from
+          # `AdditionalNonRelationMethods` in .rubocop.yml. The config knob
+          # lets each project opt-in their own domain methods (e.g. a
+          # `CashBookEntry.for_account` that returns an Array of plain Ruby
+          # presenters) without modifying this cop.
+          def non_relation_method?(method_name)
+            return true if NON_RELATION_RETURNING_METHODS.include?(method_name)
+
+            additional = cop_config['AdditionalNonRelationMethods'] || []
+            additional.map(&:to_sym).include?(method_name)
+          end
+
+          def screaming_case_const?(const_node)
+            const_node.short_name.to_s.match?(/\A[A-Z][A-Z0-9_]*\z/)
+          end
+
+          # Look at the block parameters and body for evidence that the
+          # iterated element can't be an ActiveRecord record.
+          def excluded_block?(send_node)
+            block_node = send_node.block_node
+            return false unless block_node
+
+            args = block_node.arguments
+            return false unless args
+
+            # 2+ arg destructuring means the iterator yields a pair/tuple
+            # (Hash#each, zip, etc.). AR relations only yield single records.
+            return true if args.children.length >= 2
+
+            # Single-arg block: inspect how the arg is used inside the body.
+            return false unless args.children.length == 1
+
+            arg_node = args.children.first
+            arg_name = block_arg_name(arg_node)
+            return false unless arg_name
+
+            body = block_node.body
+            return false unless body
+
+            block_arg_indicates_non_record?(body, arg_name)
+          end
+
+          # Extract the simple name of a block argument, regardless of whether
+          # it's a regular arg, optional arg, or splat. Skips destructured
+          # `(a, b)` (handled by the 2+ arg check at a structural level).
+          def block_arg_name(arg_node)
+            return nil unless arg_node.respond_to?(:children)
+
+            arg_node.children.first if %i[arg optarg restarg].include?(arg_node.type)
+          end
+
+          # Return true if the block body uses `arg` in a way that's only
+          # legal for non-AR elements:
+          #   * Symbol-key indexing — `arg[:foo]` — implies Hash
+          #   * Single-character string-literal indexing — `arg[0] == '+'` —
+          #     implies String
+          def block_arg_indicates_non_record?(body, arg_name)
+            body.each_descendant(:send) do |send|
+              next unless send.method_name == :[]
+              next unless send.receiver&.lvar_type?
+              next unless send.receiver.children.first == arg_name
+              next unless send.arguments.length == 1
+
+              key = send.first_argument
+              return true if key.sym_type?
+              return true if key.int_type? && compared_to_single_char_string?(send)
+            end
+
+            false
+          end
+
+          # `arg[0] == '+'` — the [] send is one side of a `==` or `!=`
+          # whose other side is a single-char string literal.
+          def compared_to_single_char_string?(index_send)
+            parent = index_send.parent
+            return false unless parent&.send_type?
+            return false unless %i[== !=].include?(parent.method_name)
+
+            other = parent.receiver.equal?(index_send) ? parent.first_argument : parent.receiver
+            other&.str_type? && other.value.length == 1
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Flag `params.require(:foo).permit(...)` and the reverse form
+        # `params.permit(foo: ...).require(:foo)` — use `params.expect(foo: [...])`
+        # instead.
+        #
+        # ## Rationale
+        # The upstream `Rails/StrongParametersExpect` autocorrects two distinct
+        # patterns: the hash-form rewrite (`require.permit` → `expect`) and the
+        # scalar form (`params[:id]` inside find-method chains). The scalar form
+        # fires false positives on optional query params (e.g.
+        # `params[:status]&.to_sym || :draft`) and forces scattered per-line
+        # disables — the typical workaround is to disable the upstream cop
+        # entirely, losing the hash-form benefit too.
+        #
+        # This cop targets **only** the hash-form rewrite, so projects can keep
+        # `Rails/StrongParametersExpect: Enabled: false` and still enforce the
+        # safe `params.expect` pattern.
+        #
+        # `params.expect` raises `ActionController::ParameterMissing` for scalar
+        # values where `permit` would silently return `nil`, and it makes the
+        # permitted-attribute shape explicit in one call.
+        #
+        # ## Patterns detected
+        #
+        #   ❌ require → permit chain
+        #   params.require(:user).permit(:name, :email)
+        #
+        #   ❌ permit → require chain (less common)
+        #   params.permit(user: %i[name email]).require(:user)
+        #
+        #   ✔️
+        #   params.expect(user: [:name, :email])
+        #
+        # ## Not flagged
+        # Scalar `params[:foo]` in any context — leave that to per-project
+        # decision or the upstream cop.
+        #
+        # @example
+        #   # bad
+        #   params.require(:user).permit(:name, :email)
+        #
+        #   # bad
+        #   params.require(:user).permit(:name, profile_attributes: [:bio])
+        #
+        #   # bad
+        #   params.permit(user: %i[name email]).require(:user)
+        #
+        #   # good
+        #   params.expect(user: [:name, :email])
+        #
+        #   # good
+        #   params.expect(user: [:name, { profile_attributes: [:bio] }])
+        class StrongParametersExpect < Base
+          extend AutoCorrector
+
+          MSG_REQUIRE_PERMIT = 'Use `params.expect(%<key>s: [...])` instead of ' \
+                               '`params.require(:%<key>s).permit(...)`.'
+          MSG_PERMIT_REQUIRE = 'Use `params.expect(%<key>s: ...)` instead of ' \
+                               '`params.permit(%<key>s: ...).require(:%<key>s)`.'
+
+          RESTRICT_ON_SEND = %i[permit require].freeze
+
+          def on_send(node)
+            check_require_permit(node) if node.method_name == :permit
+            check_permit_require(node) if node.method_name == :require
+          end
+
+          private
+
+          # Match: params.require(:foo).permit(...)
+          def check_require_permit(permit_node)
+            require_node = permit_node.receiver
+            return unless require_node&.send_type? && require_node.method_name == :require
+            return unless params_receiver?(require_node.receiver)
+            return unless require_node.arguments.one? && require_node.first_argument.sym_type?
+
+            key = require_node.first_argument.value
+            add_offense(permit_node, message: format(MSG_REQUIRE_PERMIT, key: key)) do |corrector|
+              replacement = build_require_permit_replacement(
+                require_node.receiver, key, permit_node.arguments
+              )
+              corrector.replace(permit_node, replacement)
+            end
+          end
+
+          # Match: params.permit(foo: ...).require(:foo)
+          def check_permit_require(require_node)
+            permit_node = require_node.receiver
+            return unless permit_node&.send_type? && permit_node.method_name == :permit
+            return unless params_receiver?(permit_node.receiver)
+            return unless require_node.arguments.one? && require_node.first_argument.sym_type?
+
+            key = require_node.first_argument.value
+            pair = permit_hash_pair_for_key(permit_node, key)
+            return unless pair
+
+            add_offense(require_node, message: format(MSG_PERMIT_REQUIRE, key: key)) do |corrector|
+              params_src = permit_node.receiver.source
+              corrector.replace(require_node, "#{params_src}.expect(#{key}: #{pair.value.source})")
+            end
+          end
+
+          def params_receiver?(node)
+            node&.send_type? && node.method_name == :params && node.receiver.nil?
+          end
+
+          # Find the first hash pair whose key matches `key` in permit's arguments.
+          def permit_hash_pair_for_key(permit_node, key)
+            permit_node.arguments.each do |arg|
+              next unless arg.hash_type?
+
+              arg.pairs.each do |pair|
+                return pair if pair.key.sym_type? && pair.key.value == key
+              end
+            end
+            nil
+          end
+
+          # Build the replacement for `params.require(:key).permit(*args)`.
+          # Symbol args stay as-is; hash args are wrapped in `{ }` since they
+          # need explicit braces when placed inside an array literal.
+          def build_require_permit_replacement(params_node, key, permit_args)
+            inner = permit_args.map { |arg| permit_arg_source(arg) }.join(', ')
+            "#{params_node.source}.expect(#{key}: [#{inner}])"
+          end
+
+          def permit_arg_source(arg)
+            arg.hash_type? ? "{ #{arg.source} }" : arg.source
+          end
+        end
+      end
+    end
+  end
+end