rubocop-dev_doc 0.1.0 → 0.3.0

data/lib/rubocop/cop/dev_doc/auth/current_user_branching.rb

@@ -0,0 +1,203 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Auth
+        # Forbid branching on authentication state in page-specific code.
+        #
+        # ## Rationale
+        # In a Rails app using Pundit + Devise, `current_user` is guaranteed
+        # non-nil inside any controller action or view that requires auth —
+        # the policy has already denied anonymous visitors. Branching on
+        # `if current_user` or `if user_signed_in?` inside that code is
+        # therefore either dead code (the branch for nil can never fire) or
+        # a signal that the developer was unsure whether the page requires auth.
+        #
+        # If the page genuinely serves both anonymous and signed-in visitors,
+        # the branching should be explicit and kept in shared/layout code, not
+        # sprinkled through action bodies and page views.
+        #
+        #   ❌ Authenticated page branching on auth state (branch is dead code)
+        #   # app/views/posts/show.json.jbuilder
+        #   if current_user
+        #     json.actions [:edit, :delete]
+        #   end
+        #
+        #   ✔️ Shared layout — branching here is the right place
+        #   # app/views/layouts/_nav_bar.html.erb
+        #   <% if user_signed_in? %>
+        #     <%= render 'profile_menu' %>
+        #   <% else %>
+        #     <%= link_to 'Log in', new_user_session_path %>
+        #   <% end %>
+        #
+        #   ✔️ Genuinely dual-state page — suppress the cop with a reason comment
+        #   def new
+        #     # rubocop:disable DevDoc/Auth/CurrentUserBranching
+        #     # Reason: contact form is intentionally dual-state; pre-fills for signed-in users.
+        #     if current_user
+        #       @form.name = current_user.full_name
+        #     end
+        #     # rubocop:enable DevDoc/Auth/CurrentUserBranching
+        #   end
+        #
+        # ## Patterns flagged
+        # - `if current_user` / `unless current_user` (block or modifier) where
+        #   the body is non-empty and is not a bare `return` (bare returns are
+        #   the nil-guard pattern covered by LoadResourceCurrentUserGuard).
+        # - `if user_signed_in?` / `unless user_signed_in?` (any form).
+        # - `if current_user&.foo` and other safe-nav uses of `current_user`
+        #   as a condition. The `&.` is itself a confession that the dev
+        #   expects `current_user` to be nil sometimes — i.e., it's the same
+        #   anti-pattern as `if current_user`, just in disguise: when
+        #   `current_user` is nil the csend returns nil → branch is dead for
+        #   anonymous visitors, exactly what the cop prevents.
+        # - Ternaries: `current_user ? a : b`, `user_signed_in? ? a : b`.
+        # - Hash/argument values: `authenticated: user_signed_in?`.
+        #
+        # ## Allowed paths (Exclude:)
+        # By default the cop is silent in:
+        #   app/policies/**/*.rb
+        #   app/helpers/**/*.rb
+        #   app/controllers/concerns/**/*.rb
+        #   app/views/layouts/**/*
+        #   app/controllers/application_controller.rb
+        #
+        # Override via `Exclude:` in your `.rubocop.yml`.
+        #
+        # NOTE: The cop does not autocorrect — there is no mechanical fix. The
+        # right response depends on developer intent: drop the branch (if auth
+        # is required), restructure into a shared layout (if dual-state), or
+        # add an inline disable with a reason.
+        #
+        # @example
+        #   # bad — inside an authenticated action
+        #   def show
+        #     if current_user
+        #       @data = current_user.private_data
+        #     end
+        #   end
+        #
+        #   # bad — safe-nav predicate, same anti-pattern in disguise
+        #   def show
+        #     if current_user&.admin?
+        #       admin_thing
+        #     end
+        #   end
+        #
+        #   # bad — inside a page view
+        #   # user_signed_in? ? render_private : render_public
+        #
+        #   # good — bare nil-guard return (LoadResourceCurrentUserGuard rule)
+        #   return unless current_user
+        #
+        #   # good — inside a shared layout file (excluded by default)
+        #   # app/views/layouts/_nav.html.erb
+        #   if user_signed_in?
+        #     ...
+        #   end
+        class CurrentUserBranching < Base
+          MSG = 'Avoid branching on auth state in page code. ' \
+                'If this page serves both anonymous and signed-in users, ' \
+                'add an inline disable with a reason.'.freeze
+
+          AUTH_METHODS = %i[current_user user_signed_in?].freeze
+
+          def on_if(node)
+            return unless auth_branch?(node)
+            return if bare_return_guard?(node)
+
+            add_offense(if_offense_location(node))
+          end
+
+          # `value: user_signed_in?` — condition passed as a value.
+          def on_send(node)
+            return unless auth_method_call?(node)
+            return unless used_as_value?(node)
+
+            add_offense(node.loc.selector)
+          end
+
+          private
+
+          def auth_branch?(node)
+            node.if_type? && auth_condition?(node.condition)
+          end
+
+          def auth_condition?(condition)
+            return false unless condition
+
+            if condition.send_type?
+              AUTH_METHODS.include?(condition.method_name) && condition.receiver.nil?
+            elsif condition.csend_type?
+              # `current_user&.foo` — the safe-nav is itself the auth check;
+              # `bare_current_user_condition?` won't match (it requires send),
+              # so guard-return forms like `return unless current_user&.admin?`
+              # correctly stay flagged.
+              receiver = condition.receiver
+              receiver&.send_type? &&
+                receiver.method_name == :current_user &&
+                receiver.receiver.nil?
+            else
+              false
+            end
+          end
+
+          # `return unless current_user` (and similar bare guards) should not
+          # be flagged — they are the correct pattern handled by
+          # LoadResourceCurrentUserGuard. Detect: an if whose condition is bare
+          # `current_user` and one branch is a bare `return` (no arguments).
+          def bare_return_guard?(node)
+            condition = node.condition
+            return false unless bare_current_user_condition?(condition)
+
+            bare_return_branch?(node.else_branch) || bare_return_branch?(node.if_branch)
+          end
+
+          def bare_current_user_condition?(condition)
+            condition&.send_type? &&
+              condition.method_name == :current_user &&
+              condition.receiver.nil?
+          end
+
+          def bare_return_branch?(branch)
+            branch&.return_type? && branch.children.empty?
+          end
+
+          # `if`/`unless` keyword forms have `loc.keyword`; ternary `?:` nodes
+          # have `loc.question` instead. Fall back to the condition source range.
+          def if_offense_location(node)
+            loc = node.loc
+            if loc.respond_to?(:keyword) && loc.keyword
+              loc.keyword
+            elsif loc.respond_to?(:question) && loc.question
+              loc.question
+            else
+              node.condition.source_range
+            end
+          end
+
+          # Is this send node an auth method call (`current_user`, `user_signed_in?`)
+          # on no receiver?
+          def auth_method_call?(node)
+            AUTH_METHODS.include?(node.method_name) && node.receiver.nil?
+          end
+
+          # Is the send node used as a value (argument to another send, pair
+          # value in a hash, etc.) rather than already caught as a branch condition?
+          def used_as_value?(node)
+            parent = node.parent
+            return false unless parent
+
+            # Pair value: `key: user_signed_in?`
+            return true if parent.pair_type? && parent.value.equal?(node)
+
+            # Passed as argument (not the condition of an `if`)
+            return false if parent.if_type? && parent.condition.equal?(node)
+
+            parent.send_type? && parent.arguments.include?(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb

@@ -0,0 +1,230 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Auth
+        # Require an early-return nil-guard before using `current_user` inside
+        # the load-resource lifecycle method, and forbid safe-navigation (`&.`).
+        #
+        # ## Rationale
+        # `glib_load_resource` (or a similarly named hook) runs *before* the
+        # Pundit policy. At that point `current_user` may still be nil — an
+        # anonymous visitor hasn't been denied yet. Code that calls
+        # `current_user.foo` without guarding first crashes for anonymous
+        # visitors; code that uses `current_user&.foo` hides the problem with
+        # soft nil-handling instead of making it explicit.
+        #
+        # The correct pattern is an early-return guard at the top of any branch
+        # that needs `current_user`:
+        #
+        #   ✔️
+        #   def glib_load_resource
+        #     return unless current_user
+        #
+        #     @post = current_user.posts.find(params[:id])
+        #   end
+        #
+        # Guarded branches within a case/if are also fine:
+        #
+        #   ✔️
+        #   def glib_load_resource
+        #     case action_name.to_sym
+        #     when :new, :create
+        #       return unless current_user
+        #       @post = current_user.posts.new
+        #     when :index
+        #       # Nothing to do
+        #     end
+        #   end
+        #
+        #   ❌ Safe navigation — hides the pre-auth nil risk
+        #   def glib_load_resource
+        #     @post = current_user&.posts&.find(params[:id])
+        #   end
+        #
+        #   ❌ Unguarded — crashes for anonymous visitors
+        #   def glib_load_resource
+        #     @post = current_user.posts.find(params[:id])
+        #   end
+        #
+        # ## Configuration
+        # `LoadResourceMethodNames` (default: `[glib_load_resource]`) — list of
+        # method names where the guard rule applies. Projects standardising on a
+        # different lifecycle method can add it here.
+        #
+        # NOTE: The cop performs structural analysis of the method body and does
+        # not track aliasing. If you assign `current_user` to a local variable
+        # and then call methods on that variable, the cop will not flag it —
+        # reviewers must catch that pattern manually.
+        #
+        # @example
+        #   # bad — safe navigation inside load hook
+        #   def glib_load_resource
+        #     @post = current_user&.posts&.find(params[:id])
+        #   end
+        #
+        #   # bad — unguarded call inside load hook
+        #   def glib_load_resource
+        #     @post = current_user.posts.find(params[:id])
+        #   end
+        #
+        #   # good — guarded with early return
+        #   def glib_load_resource
+        #     return unless current_user
+        #
+        #     @post = current_user.posts.find(params[:id])
+        #   end
+        class LoadResourceCurrentUserGuard < Base
+          MSG_SAFE_NAV = 'Avoid `current_user&.` inside `%<method>s` — use ' \
+                         '`return unless current_user` then `current_user.` instead.'.freeze
+          MSG_MISSING_GUARD = '`current_user` is used without a prior ' \
+                              '`return unless current_user` guard in `%<method>s`. ' \
+                              'This method runs before the policy, so `current_user` may be nil.'.freeze
+
+          # Methods that test current_user for nil — not calls that risk NoMethodError.
+          NIL_CHECK_METHODS = %i[nil? blank? present? empty?].freeze
+
+          def on_def(node)
+            check_load_resource_method(node)
+          end
+          alias on_defs on_def
+
+          private
+
+          def load_resource_method_names
+            Array(cop_config.fetch('LoadResourceMethodNames', ['glib_load_resource'])).map(&:to_sym)
+          end
+
+          def load_resource_method?(method_name)
+            load_resource_method_names.include?(method_name.to_sym)
+          end
+
+          def check_load_resource_method(def_node)
+            method_name = def_node.method_name
+            return unless load_resource_method?(method_name)
+
+            body = def_node.body
+            return unless body
+
+            check_body(body, method_name)
+          end
+
+          def check_body(body, method_name)
+            body.each_descendant do |node|
+              if safe_nav_on_current_user?(node)
+                add_offense(node.loc.dot,
+                            message: format(MSG_SAFE_NAV, method: method_name))
+              elsif unguarded_current_user_call?(node)
+                add_offense(node.receiver.loc.selector,
+                            message: format(MSG_MISSING_GUARD, method: method_name))
+              end
+            end
+          end
+
+          # `current_user&.something` — always an offense regardless of guards.
+          def safe_nav_on_current_user?(node)
+            node.csend_type? && current_user_receiver?(node)
+          end
+
+          # `current_user.something` where `something` is not a nil check and
+          # no dominating guard protects the call.
+          def unguarded_current_user_call?(node)
+            return false unless node.send_type?
+            return false unless current_user_receiver?(node)
+            return false if nil_check_method?(node.method_name)
+
+            !dominated_by_guard?(node)
+          end
+
+          # Does the direct receiver of `node` resolve to bare `current_user`?
+          def current_user_receiver?(node)
+            recv = node.receiver
+            recv&.send_type? && recv.method_name == :current_user && recv.receiver.nil?
+          end
+
+          def nil_check_method?(method_name)
+            NIL_CHECK_METHODS.include?(method_name)
+          end
+
+          # Returns true if `node` is protected by a `current_user` nil-guard via:
+          # 1. Being inside an `if current_user` then-branch, OR
+          # 2. Having a preceding guard-return statement in its nearest enclosing
+          #    `begin` sequence (handles flat sequences AND nested `when` branches).
+          def dominated_by_guard?(node)
+            inside_current_user_branch?(node) || preceded_by_guard?(node)
+          end
+
+          # Walk ancestor `if` nodes and return true when `node` is inside the
+          # then-branch of an `if current_user` (not the else-branch).
+          def inside_current_user_branch?(node)
+            node.each_ancestor(:if) do |if_node|
+              next unless current_user_truthy_condition?(if_node.condition)
+
+              if_br = if_node.if_branch
+              return true if if_br && (if_br.equal?(node) || descendant_by_identity?(if_br, node))
+            end
+            false
+          end
+
+          # Walk up through all ancestor `begin` nodes. For each, check whether
+          # a guard-return statement appears before the statement that contains
+          # `node`. This handles both flat method bodies and nested `when` branches.
+          def preceded_by_guard?(node)
+            node.each_ancestor do |ancestor|
+              next unless ancestor.begin_type?
+
+              stmts = ancestor.children
+              container_idx = stmts.index { |s| s.equal?(node) || descendant_by_identity?(s, node) }
+              next unless container_idx
+
+              return true if stmts[0...container_idx].any? { |s| guard_statement?(s) }
+            end
+            false
+          end
+
+          # True if `descendant` is found within `root` by object identity.
+          def descendant_by_identity?(root, descendant)
+            root.each_descendant.any? { |d| d.equal?(descendant) }
+          end
+
+          # True if `stmt` is a guard-return on `current_user`:
+          #   return unless current_user      — condition: current_user, one branch: (return)
+          #   return if current_user.nil?     — condition: current_user.nil?, one branch: (return)
+          #   return if current_user.blank?   — condition: current_user.blank?, one branch: (return)
+          #
+          # The parser gem swaps `if_branch`/`else_branch` for `unless`-modifier
+          # forms, so we check BOTH branches for a bare `return` rather than
+          # assuming which side it falls on.
+          def guard_statement?(stmt)
+            return false unless stmt.if_type?
+
+            condition = stmt.condition
+            return false unless current_user_truthy_condition?(condition) ||
+                                current_user_nil_condition?(condition)
+
+            return_node?(stmt.if_branch) || return_node?(stmt.else_branch)
+          end
+
+          # Condition is bare `current_user` (truthy check).
+          def current_user_truthy_condition?(condition)
+            condition&.send_type? &&
+              condition.method_name == :current_user &&
+              condition.receiver.nil?
+          end
+
+          # Condition is `current_user.nil?` or `current_user.blank?`.
+          def current_user_nil_condition?(condition)
+            return false unless condition&.send_type?
+            return false unless NIL_CHECK_METHODS.include?(condition.method_name)
+
+            recv = condition.receiver
+            recv&.send_type? && recv.method_name == :current_user && recv.receiver.nil?
+          end
+
+          def return_node?(node)
+            node&.return_type?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Monetary columns must be stored as integer cents with an `_in_cents` suffix.
+        #
+        # ## Rationale
+        # Storing monetary values as floats or decimals introduces floating-point
+        # precision issues. The safe approach is to store values as integer cents
+        # and convert to dollars only in user-facing forms and displays.
+        #
+        # This cop is heuristic: it matches column names whose last segment is a
+        # known monetary word (configurable via `MonetaryNames`). Extend the list
+        # in your `.rubocop.yml` if your domain uses different names.
+        #
+        #   ❌
+        #   t.float :amount
+        #   t.decimal :price
+        #   add_column :orders, :total, :decimal
+        #
+        #   ✔️
+        #   t.integer :amount_in_cents
+        #   t.integer :price_in_cents
+        #   add_column :orders, :total_in_cents, :integer
+        #
+        # To extend the monetary names list:
+        #
+        #   DevDoc/Migration/AmountColumnInCents:
+        #     Enabled: true
+        #     MonetaryNames:
+        #       - amount
+        #       - price
+        #       - balance
+        #       - cost
+        #       - fee
+        #       - total
+        #       - subtotal
+        #       - discount
+        #       - tax
+        #       - revenue   # custom addition
+        #
+        # @example
+        #   # bad
+        #   t.float :amount
+        #   t.decimal :price
+        #   add_column :orders, :total, :decimal
+        #
+        #   # good
+        #   t.integer :amount_in_cents
+        #   t.integer :price_in_cents
+        #   add_column :orders, :total_in_cents, :integer
+        class AmountColumnInCents < Base
+          DEFAULT_MONETARY_NAMES = %w[amount price balance cost fee total subtotal discount tax].freeze
+
+          MSG = 'Store monetary values as integer cents — ' \
+                'rename `%<name>s` to `%<name>s_in_cents` and use `t.integer`.'.freeze
+
+          COLUMN_METHODS = %i[float decimal integer].freeze
+
+          def on_send(node)
+            col_name_node = column_name_node(node)
+            return unless col_name_node&.sym_type?
+
+            col_name = col_name_node.value.to_s
+            return if col_name.end_with?('_in_cents')
+            return unless monetary_suffix?(col_name)
+
+            add_offense(col_name_node, message: format(MSG, name: col_name))
+          end
+
+          private
+
+          def column_name_node(node)
+            if node.method?(:add_column)
+              node.arguments[1]
+            elsif COLUMN_METHODS.include?(node.method_name)
+              node.first_argument
+            end
+          end
+
+          def monetary_suffix?(name)
+            monetary_names.include?(name.split('_').last)
+          end
+
+          def monetary_names
+            cop_config.fetch('MonetaryNames', DEFAULT_MONETARY_NAMES)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid methods that bypass validations and callbacks.
+        #
+        # ## Rationale
+        # Avoid bypassing validation unless absolutely necessary. Methods like
+        # `update_column`, `update_all`, `insert_all`, `upsert_all`, `delete_all`,
+        # and `save(validate: false)` 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
+        #
+        # @example
+        #   # bad
+        #   Faq.where(purpose: nil).update_all(purpose: :intro)
+        #
+        #   # bad
+        #   user.update_column(:status, 'active')
+        #
+        #   # bad
+        #   user.save(validate: false)
+        #
+        #   # bad
+        #   User.insert_all(rows)
+        #
+        #   # good
+        #   Faq.where(purpose: nil).find_each do |faq|
+        #     faq.purpose = :intro
+        #     faq.save!
+        #   end
+        class AvoidBypassingValidation < Base
+          MESSAGES = {
+            update_column: 'Avoid `update_column`; it bypasses validations. Use `save!` instead.',
+            update_columns: 'Avoid `update_columns`; it bypasses validations. Use `save!` instead.',
+            update_all: 'Avoid `update_all`; it bypasses validations. Use `save!` in a loop instead.',
+            insert_all: 'Avoid `insert_all`; it bypasses validations. Use `create!` in a loop, ' \
+                        'or `# rubocop:disable` with a reason if bulk-insert is intentional.',
+            upsert_all: 'Avoid `upsert_all`; it bypasses validations. Use `create!`/`update!` in a loop, ' \
+                        'or `# rubocop:disable` with a reason if bulk-upsert is intentional.',
+            delete_all: 'Avoid `delete_all`; it bypasses callbacks. Use `destroy_all` to run callbacks, ' \
+                        'or `# rubocop:disable` with a reason if bulk-delete is intentional.'
+          }.freeze
+
+          SAVE_MSG = 'Avoid `save(validate: false)`; it bypasses validations. Use `save!` instead.'.freeze
+
+          RESTRICT_ON_SEND = %i[update_column update_columns update_all insert_all upsert_all delete_all save].freeze
+
+          def on_send(node)
+            if node.method?(:save)
+              return unless save_with_validate_false?(node)
+
+              add_offense(node.loc.selector, message: SAVE_MSG)
+            else
+              add_offense(node.loc.selector, message: MESSAGES[node.method_name])
+            end
+          end
+
+          private
+
+          def save_with_validate_false?(node)
+            node.arguments.any? do |arg|
+              next unless arg.hash_type?
+
+              arg.pairs.any? do |pair|
+                pair.key.sym_type? && pair.key.value == :validate && pair.value.false_type?
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end