rubocop-dev_doc 0.2.0 → 0.3.1

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,287 @@
+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
+        #
+        # glib's `assert_current_user_present` raises when `current_user` is nil,
+        # so it guarantees non-nil just as well as the early return — and any
+        # `raise` guard works like the `return` form:
+        #
+        #   ✔️
+        #   def glib_load_resource
+        #     assert_current_user_present
+        #
+        #     @post = current_user.posts.find(params[:id])
+        #   end
+        #
+        #   ✔️
+        #   def glib_load_resource
+        #     raise UnauthorizedError unless current_user
+        #
+        #     @post = current_user.posts.find(params[:id])
+        #   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.
+        #
+        # `CurrentUserAssertionMethodNames` (default:
+        # `[assert_current_user_present]`) — calls that raise when `current_user`
+        # is nil. A call to one of these before the first `current_user` use
+        # satisfies the guard. Add project-specific assertion helpers here. NOTE:
+        # the cop trusts the named method to actually raise on nil — a configured
+        # name that doesn't will turn into a false negative.
+        #
+        # 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
+        #
+        #   # good — guarded with the glib assertion (raises when nil)
+        #   def glib_load_resource
+        #     assert_current_user_present
+        #
+        #     @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` (or `assert_current_user_present`) ' \
+                              'guard in `%<method>s`. ' \
+                              'This method runs before the policy, so `current_user` may be nil.'.freeze
+
+          # Predicates safe to call on a nil `current_user` — a `current_user.nil?`
+          # etc. is not itself an unguarded use that risks NoMethodError.
+          NIL_CHECK_METHODS = %i[nil? blank? present? empty?].freeze
+
+          # Predicates split by polarity, so a guard's exit branch can be matched
+          # to the path on which `current_user` is nil. `present?` is a PRESENCE
+          # check (reversed from `nil?`/`blank?`), so `unless current_user.present?`
+          # is a valid guard while `if current_user.present?` is not.
+          ABSENCE_CHECK_METHODS = %i[nil? blank? empty?].freeze
+          PRESENCE_CHECK_METHODS = %i[present?].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 current_user_assertion_method_names
+            Array(cop_config.fetch('CurrentUserAssertionMethodNames', ['assert_current_user_present'])).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? && bare_current_user?(node.receiver)
+          end
+
+          # `current_user.something` where `something` is not a nil check and no
+          # dominating guard protects the call — i.e. not inside an `if current_user`
+          # then-branch and not preceded by a guard statement in its enclosing `begin`.
+          def unguarded_current_user_call?(node)
+            return false unless node.send_type?
+            return false unless bare_current_user?(node.receiver)
+            return false if NIL_CHECK_METHODS.include?(node.method_name)
+
+            !(inside_current_user_branch?(node) || preceded_by_guard?(node))
+          end
+
+          # True if `node` is a bare `current_user` send (no receiver).
+          def bare_current_user?(node)
+            node&.send_type? && node.method_name == :current_user && node.receiver.nil?
+          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 bare_current_user?(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` guarantees `current_user` is non-nil for everything
+          # that follows it — either:
+          #
+          # 1. a bare call to a configured assertion helper (default
+          #    `assert_current_user_present`), which raises when nil; or
+          # 2. an early-exit guard whose branch returns OR raises:
+          #      return unless current_user      raise ... unless current_user
+          #      return if current_user.nil?     raise ... if current_user.blank?
+          def guard_statement?(stmt)
+            assertion_guard_call?(stmt) || exit_guard_statement?(stmt)
+          end
+
+          # A bare call (nil receiver) to a "raise when current_user is nil"
+          # helper, e.g. glib's `assert_current_user_present`.
+          def assertion_guard_call?(stmt)
+            stmt.send_type? && stmt.receiver.nil? &&
+              current_user_assertion_method_names.include?(stmt.method_name)
+          end
+
+          # A `return`/`raise` guard whose exit happens on the NIL path — the only
+          # polarity that actually protects later `current_user` use:
+          #   `... unless current_user`     exits via the else branch
+          #   `... if current_user.nil?`    exits via the if branch
+          # (Ruby models an `if`/`unless` modifier as an `if` node with an empty
+          # opposite branch, so we tie the required exit to the condition polarity.
+          # This rejects inverted guards like `return if current_user`.)
+          # A `return`/`raise` guard is valid only when the branch that runs while
+          # `current_user` is nil exits. `if_branch` is the written body regardless
+          # of `if`/`unless`, so combine the condition's polarity with the keyword to
+          # pick that branch. This rejects inverted guards (`return if current_user`).
+          def exit_guard_statement?(stmt)
+            return false unless stmt.if_type?
+
+            polarity = condition_polarity(stmt.condition)
+            return false unless polarity
+
+            body_runs_when_nil = polarity == (stmt.unless? ? :presence : :absence)
+            branch_exits?(body_runs_when_nil ? stmt.if_branch : stmt.else_branch)
+          end
+
+          # :presence — condition truthy when current_user is present (`current_user`,
+          #   `current_user.present?`); :absence — truthy when absent (`.nil?`/`.blank?`/
+          #   `.empty?`); nil — not a current_user condition.
+          def condition_polarity(condition)
+            return :presence if bare_current_user?(condition)
+            return unless condition&.send_type? && bare_current_user?(condition.receiver)
+            return :presence if PRESENCE_CHECK_METHODS.include?(condition.method_name)
+
+            :absence if ABSENCE_CHECK_METHODS.include?(condition.method_name)
+          end
+
+          # True if `branch` terminates on entry via an early `return` or a bare
+          # `raise`/`fail`. A multi-statement branch (a `begin`) counts when its
+          # LAST statement does.
+          def branch_exits?(branch)
+            return false unless branch
+
+            branch = branch.children.last if branch.begin_type?
+            branch&.return_type? ||
+              (branch&.send_type? && branch.receiver.nil? && %i[raise fail].include?(branch.method_name))
+          end
+        end
+      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