rubocop-dev_doc 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd15873d6ee53104760162aa0e5cced9dd69ef1297a70a014dd5643b9404703c
-  data.tar.gz: 25d0fa51436912d008625752269ff09ef93e78c14d6d1a941295c6afa47795b4
+  metadata.gz: 163ac4a232d22f5d731e680d4ae882172570cdcf3085a07be7d6c3195223e365
+  data.tar.gz: a3eae8c77dcb707ddc4875be90255bea2fa33bcaeba370c7aff06436cd045661
 SHA512:
-  metadata.gz: 516d5742aa468568e3884d779649164761f982391be0c5f7e5df474d64a933cf71148fe1fddb433c5cf1cd577debd7aadcb16bf22893963d721a3661a1f0fff0
-  data.tar.gz: 69a643cf2335d6c7bb365a4a2f8513e9a66d09a6cddb2bec5e44df861ebcb906de51d17fbbd1b591388c651c2f1cb662de5e5a887df7f11db3c9885e9d6ae597
+  metadata.gz: a605681c5f22058138abe3d8bdcd1e12eb94073f74e02fde30bc1f1df0baa538022b69fe33c4f83279cfaed995e60e5c9a4936de43cad7a89f07105c4b6e7a24
+  data.tar.gz: 0e845bcf2236245a8c4b0289a02d7731e12c9ac0023732f6135127f02f436c78f349012b98bd18127e89cdb4e70736597c2fc5313229ed3faaf572294e847168

data/config/default.yml

@@ -348,12 +348,17 @@ Rails/HasManyOrHasOneDependent:
   Enabled: true
 
 DevDoc/Auth/LoadResourceCurrentUserGuard:
-  Description: "Require a `return unless current_user` guard before using `current_user` inside `glib_load_resource`, and forbid `current_user&.`."
+  Description: "Require a `return unless current_user` (or `assert_current_user_present`) guard before using `current_user` inside `glib_load_resource`, and forbid `current_user&.`."
   Enabled: true
   # LoadResourceMethodNames: list of method names where the guard rule applies.
   # Extend if your project uses a different lifecycle hook name.
   LoadResourceMethodNames:
     - glib_load_resource
+  # CurrentUserAssertionMethodNames: calls that raise when current_user is nil
+  # (e.g. glib's assert_current_user_present). A call to one before the first
+  # current_user use satisfies the guard. Add custom assertion helpers here.
+  CurrentUserAssertionMethodNames:
+    - assert_current_user_present
 
 DevDoc/Auth/CurrentUserBranching:
   Description: "Avoid branching on `current_user` / `user_signed_in?` in page-specific code. Use shared layouts or an inline disable with a reason for genuinely dual-state pages."

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

@@ -36,6 +36,24 @@ module RuboCop
         #     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])
@@ -51,6 +69,13 @@ module RuboCop
         # 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 —
@@ -73,16 +98,32 @@ module RuboCop
         #
         #     @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` guard in `%<method>s`. ' \
+                              '`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
 
-          # Methods that test current_user for nil — not calls that risk NoMethodError.
+          # 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
@@ -94,6 +135,10 @@ module RuboCop
             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
@@ -122,42 +167,30 @@ module RuboCop
 
           # `current_user&.something` — always an offense regardless of guards.
           def safe_nav_on_current_user?(node)
-            node.csend_type? && current_user_receiver?(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.
+          # `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 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
+            return false unless bare_current_user?(node.receiver)
+            return false if NIL_CHECK_METHODS.include?(node.method_name)
 
-          def nil_check_method?(method_name)
-            NIL_CHECK_METHODS.include?(method_name)
+            !(inside_current_user_branch?(node) || preceded_by_guard?(node))
           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)
+          # 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 current_user_truthy_condition?(if_node.condition)
+              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))
@@ -186,42 +219,66 @@ module RuboCop
             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)
+          # True if `stmt` guarantees `current_user` is non-nil for everything
+          # that follows it — either:
           #
-          # 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.
+          # 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)
-            return false unless stmt.if_type?
-
-            condition = stmt.condition
-            return false unless current_user_truthy_condition?(condition) ||
-                                current_user_nil_condition?(condition)
+            assertion_guard_call?(stmt) || exit_guard_statement?(stmt)
+          end
 
-            return_node?(stmt.if_branch) || return_node?(stmt.else_branch)
+          # 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
 
-          # Condition is bare `current_user` (truthy check).
-          def current_user_truthy_condition?(condition)
-            condition&.send_type? &&
-              condition.method_name == :current_user &&
-              condition.receiver.nil?
+          # 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
 
-          # 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)
+          # :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)
 
-            recv = condition.receiver
-            recv&.send_type? && recv.method_name == :current_user && recv.receiver.nil?
+            :absence if ABSENCE_CHECK_METHODS.include?(condition.method_name)
           end
 
-          def return_node?(node)
-            node&.return_type?
+          # 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

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.3.0".freeze
+    VERSION = "0.3.1".freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - dev-doc contributors