rubocop-dev_doc 0.2.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/avoid_conditional_schema_changes.rb

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

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

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

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

@@ -12,7 +12,7 @@ module RuboCop
         # particular model.
         #
         #   ❌  (in a controller or service)
-        #   Checklist.transaction do
+        #   Post.transaction do
         #     ...
         #   end
         #