axn 0.1.0.pre.alpha.2.7.1 → 0.1.0.pre.alpha.2.8

data/lib/rubocop/cop/axn/unchecked_result.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Axn
+      # This cop enforces that when calling Actions from within other Actions,
+      # you must either use `call!` (with the bang) or check `result.ok?`.
+      #
+      # @example
+      #   # bad
+      #   class OuterAction
+      #     include Action
+      #     def call
+      #       InnerAction.call(param: "value")  # Missing result check
+      #     end
+      #   end
+      #
+      #   # good
+      #   class OuterAction
+      #     include Action
+      #     def call
+      #       result = InnerAction.call(param: "value")
+      #       return result unless result.ok?
+      #       # Process successful result...
+      #     end
+      #   end
+      #
+      #   # also good
+      #   class OuterAction
+      #     include Action
+      #     def call
+      #       InnerAction.call!(param: "value")  # Using call! ensures exceptions bubble up
+      #     end
+      #   end
+      #
+      # rubocop:disable Metrics/ClassLength
+      class UncheckedResult < RuboCop::Cop::Base
+        extend RuboCop::Cop::AutoCorrector
+
+        MSG = "Use `call!` or check `result.ok?` when calling Actions from within Actions"
+
+        # Configuration options
+        def check_nested?
+          cop_config["CheckNested"] != false
+        end
+
+        def check_non_nested?
+          cop_config["CheckNonNested"] != false
+        end
+
+        # Track whether we're inside an Action class and its call method
+        def_node_search :action_class?, <<~PATTERN
+          (class _ (const nil? :Action) ...)
+        PATTERN
+
+        def_node_search :includes_action?, <<~PATTERN
+          (send nil? :include (const nil? :Action))
+        PATTERN
+
+        def_node_search :call_method?, <<~PATTERN
+          (def :call ...)
+        PATTERN
+
+        def_node_search :action_call?, <<~PATTERN
+          (send (const _ _) :call ...)
+        PATTERN
+
+        def_node_search :bang_call?, <<~PATTERN
+          (send (const _ _) :call! ...)
+        PATTERN
+
+        def_node_search :result_assignment?, <<~PATTERN
+          (lvasgn _ (send (const _ _) :call ...))
+        PATTERN
+
+        def_node_search :result_ok_check?, <<~PATTERN
+          (send (send _ :result) :ok?)
+        PATTERN
+
+        def_node_search :result_failed_check?, <<~PATTERN
+          (send (send _ :result) :failed?)
+        PATTERN
+
+        def_node_search :result_error_check?, <<~PATTERN
+          (send (send _ :result) :error)
+        PATTERN
+
+        def_node_search :result_exception_check?, <<~PATTERN
+          (send (send _ :result) :exception)
+        PATTERN
+
+        def_node_search :return_with_result?, <<~PATTERN
+          (return (send _ :result))
+        PATTERN
+
+        def_node_search :expose_with_result?, <<~PATTERN
+          (send nil? :expose ...)
+        PATTERN
+
+        def_node_search :result_passed_to_method?, <<~PATTERN
+          (send nil? :result ...)
+        PATTERN
+
+        def on_send(node)
+          return unless action_call?(node)
+          return if bang_call?(node)
+          return unless inside_action_call_method?(node)
+
+          # Check if we should process this call based on configuration
+          is_inside_action = inside_action_context?(node)
+          return unless (is_inside_action && check_nested?) || (!is_inside_action && check_non_nested?)
+
+          return if result_properly_handled?(node)
+
+          add_offense(node, message: MSG)
+        end
+
+        private
+
+        def inside_action_call_method?(node)
+          # Check if we're inside a call method of an Action class
+          current_node = node
+          while current_node.parent
+            current_node = current_node.parent
+
+            # Check if we're inside a def :call
+            next unless call_method?(current_node) && current_node.method_name == :call
+
+            # Now check if this class includes Action
+            class_node = find_enclosing_class(current_node)
+            return includes_action?(class_node) if class_node
+          end
+          false
+        rescue StandardError => _e
+          # If there's any error in the analysis, assume we're not in an Action call method
+          # This prevents the cop from crashing on complex or malformed code
+          false
+        end
+
+        def inside_action_context?(node)
+          # Check if this Action call is inside an Action class's call method
+          current_node = node
+          while current_node.parent
+            current_node = current_node.parent
+
+            # Check if we're inside a def :call
+            next unless call_method?(current_node) && current_node.method_name == :call
+
+            # Now check if this class includes Action
+            class_node = find_enclosing_class(current_node)
+            return true if class_node && includes_action?(class_node)
+          end
+          false
+        rescue StandardError => _e
+          false
+        end
+
+        def find_enclosing_class(node)
+          current_node = node
+          while current_node.parent
+            current_node = current_node.parent
+            return current_node if current_node.type == :class
+          end
+          nil
+        rescue StandardError => _e
+          # If there's any error in the analysis, return nil
+          nil
+        end
+
+        def result_properly_handled?(node)
+          # Check if the result is assigned to a variable
+          parent = node.parent
+          return false unless parent&.type == :lvasgn
+
+          result_var = parent.children[0]
+
+          # Look for proper result handling in the method
+          method_body = find_enclosing_method_body(node)
+          return false unless method_body
+
+          # Check if result.ok? is checked
+          return true if result_ok_check_in_method?(method_body, result_var)
+
+          # Check if result.failed? is checked
+          return true if result_failed_check_in_method?(method_body, result_var)
+
+          # Check if result.error is accessed
+          return true if result_error_check_in_method?(method_body, result_var)
+
+          # Check if result.exception is accessed
+          return true if result_exception_check_in_method?(method_body, result_var)
+
+          # Check if result is returned
+          return true if result_returned_in_method?(method_body, result_var)
+
+          # Check if result is used in expose
+          return true if result_used_in_expose?(method_body, result_var)
+
+          # Check if result is passed to another method
+          return true if result_passed_to_method?(method_body, result_var)
+
+          false
+        rescue StandardError => _e
+          # If there's any error in the analysis, assume the result is not properly handled
+          # This prevents the cop from crashing on complex or malformed code
+          false
+        end
+
+        def find_enclosing_method_body(node)
+          current_node = node
+          while current_node.parent
+            current_node = current_node.parent
+            if current_node.type == :def && current_node.method_name == :call
+              return current_node.children[2] # The method body
+            end
+          end
+          nil
+        end
+
+        def result_ok_check_in_method?(method_body, result_var)
+          method_body.each_descendant(:send) do |send_node|
+            next unless send_node.method_name == :ok?
+
+            # Check if this is any_variable.ok?
+            receiver = send_node.children[0]
+            return true if receiver&.type == :lvar && receiver.children[0] == result_var
+          end
+          false
+        end
+
+        def result_failed_check_in_method?(method_body, result_var)
+          method_body.each_descendant(:send) do |send_node|
+            next unless send_node.method_name == :failed?
+
+            receiver = send_node.children[0]
+            return true if receiver&.type == :lvar && receiver.children[0] == result_var
+          end
+          false
+        end
+
+        def result_error_check_in_method?(method_body, result_var)
+          method_body.each_descendant(:send) do |send_node|
+            next unless send_node.method_name == :error
+
+            receiver = send_node.children[0]
+            return true if receiver&.type == :lvar && receiver.children[0] == result_var
+          end
+          false
+        end
+
+        def result_exception_check_in_method?(method_body, result_var)
+          method_body.each_descendant(:send) do |send_node|
+            next unless send_node.method_name == :exception
+
+            receiver = send_node.children[0]
+            return true if receiver&.type == :lvar && receiver.children[0] == result_var
+          end
+          false
+        end
+
+        def result_returned_in_method?(method_body, result_var)
+          # Check for explicit return statements
+          method_body.each_descendant(:return) do |return_node|
+            return_value = return_node.children[0]
+            return true if return_value&.type == :lvar && return_value.children[0] == result_var
+          end
+
+          # Check for implicit return (last statement in method)
+          last_statement = if method_body.type == :begin
+                             method_body.children.last
+                           else
+                             method_body
+                           end
+
+          return true if last_statement&.type == :lvar && last_statement.children[0] == result_var
+
+          false
+        end
+
+        def result_used_in_expose?(method_body, result_var)
+          method_body.each_descendant(:send) do |send_node|
+            next unless send_node.method_name == :expose
+
+            # Check if any argument references the result variable
+            # send_node.children[0] is the receiver (nil for self)
+            # send_node.children[1] is the method name (:expose)
+            # send_node.children[2..] are the actual arguments
+            send_node.children[2..].each do |arg|
+              # Handle hash arguments in expose calls
+              if arg.type == :hash
+                arg.children.each do |pair|
+                  next unless pair.type == :pair
+
+                  value = pair.children[1]
+                  return true if value&.type == :lvar && value.children[0] == result_var
+                end
+              elsif arg&.type == :lvar && arg.children[0] == result_var
+                return true
+              end
+            end
+          end
+          false
+        end
+
+        def result_passed_to_method?(method_body, result_var)
+          method_body.each_descendant(:send) do |send_node|
+            next if send_node.method_name == :result # Skip result method calls
+            next if send_node.method_name == :ok? # Skip result.ok? calls
+            next if send_node.method_name == :failed? # Skip result.failed? calls
+            next if send_node.method_name == :error # Skip result.error calls
+            next if send_node.method_name == :exception # Skip result.exception calls
+
+            # Check if result is passed as an argument
+            # send_node.children[0] is the receiver
+            # send_node.children[1] is the method name
+            # send_node.children[2..] are the actual arguments
+            send_node.children[2..].each do |arg|
+              return true if arg&.type == :lvar && arg.children[0] == result_var
+            end
+          end
+          false
+        end
+        # rubocop:enable Metrics/ClassLength
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2.7.1
+  version: 0.1.0.pre.alpha.2.8
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-15 00:00:00.000000000 Z
+date: 2025-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -61,6 +61,7 @@ files:
 - docs/intro/about.md
 - docs/intro/overview.md
 - docs/recipes/memoization.md
+- docs/recipes/rubocop-integration.md
 - docs/recipes/testing.md
 - docs/recipes/validating-user-input.md
 - docs/reference/action-result.md
@@ -70,6 +71,7 @@ files:
 - docs/strategies/index.md
 - docs/strategies/transaction.md
 - docs/usage/setup.md
+- docs/usage/steps.md
 - docs/usage/using.md
 - docs/usage/writing.md
 - lib/action/attachable.rb
@@ -90,16 +92,19 @@ files:
 - lib/action/core/flow/callbacks.rb
 - lib/action/core/flow/exception_execution.rb
 - lib/action/core/flow/handlers.rb
-- lib/action/core/flow/handlers/base_handler.rb
-- lib/action/core/flow/handlers/callback_handler.rb
+- lib/action/core/flow/handlers/base_descriptor.rb
+- lib/action/core/flow/handlers/descriptors/callback_descriptor.rb
+- lib/action/core/flow/handlers/descriptors/message_descriptor.rb
 - lib/action/core/flow/handlers/invoker.rb
 - lib/action/core/flow/handlers/matcher.rb
-- lib/action/core/flow/handlers/message_handler.rb
 - lib/action/core/flow/handlers/registry.rb
+- lib/action/core/flow/handlers/resolvers/base_resolver.rb
+- lib/action/core/flow/handlers/resolvers/callback_resolver.rb
+- lib/action/core/flow/handlers/resolvers/message_resolver.rb
 - lib/action/core/flow/messages.rb
-- lib/action/core/hoist_errors.rb
 - lib/action/core/hooks.rb
 - lib/action/core/logging.rb
+- lib/action/core/nesting_tracking.rb
 - lib/action/core/timing.rb
 - lib/action/core/tracing.rb
 - lib/action/core/use_strategy.rb
@@ -116,9 +121,12 @@ files:
 - lib/action/strategies/transaction.rb
 - lib/axn.rb
 - lib/axn/factory.rb
+- lib/axn/rubocop.rb
 - lib/axn/testing/spec_helpers.rb
 - lib/axn/util.rb
 - lib/axn/version.rb
+- lib/rubocop/cop/axn/README.md
+- lib/rubocop/cop/axn/unchecked_result.rb
 - package.json
 - yarn.lock
 homepage: https://github.com/teamshares/axn

data/lib/action/core/flow/handlers/callback_handler.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require "action/core/flow/handlers/base_handler"
-require "action/core/flow/handlers/invoker"
-
-module Action
-  module Core
-    module Flow
-      module Handlers
-        class CallbackHandler < BaseHandler
-          def apply(action:, exception:)
-            return false unless matches?(action:, exception:)
-
-            Invoker.call(action:, handler:, exception:, operation: "executing handler")
-            true
-          end
-        end
-      end
-    end
-  end
-end

data/lib/action/core/flow/handlers/message_handler.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require "action/core/flow/handlers/base_handler"
-require "action/core/flow/handlers/invoker"
-
-module Action
-  module Core
-    module Flow
-      module Handlers
-        class MessageHandler < BaseHandler
-          # Returns a string (truthy) when it applies and yields a non-blank message; otherwise nil
-          def apply(action:, exception:)
-            return nil unless matches?(action:, exception:)
-
-            value =
-              if handler.is_a?(Symbol) || handler.respond_to?(:call)
-                Invoker.call(action:, handler:, exception:, operation: "determining message callable")
-              else
-                handler
-              end
-            value.respond_to?(:presence) ? value.presence : value
-          end
-        end
-      end
-    end
-  end
-end

data/lib/action/core/hoist_errors.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Action
-  module Core
-    module HoistErrors
-      def self.included(base)
-        base.class_eval do
-          include InstanceMethods
-        end
-      end
-
-      module InstanceMethods
-        private
-
-        MinimalFailedResult = Data.define(:error, :exception) do
-          def ok? = false
-        end
-
-        # This method is used to ensure that the result of a block is successful before proceeding.
-        #
-        # Assumes success unless the block raises an exception or returns a failed result.
-        # (i.e. if you wrap logic that is NOT an action call, it'll be successful unless it raises an exception)
-        def hoist_errors(prefix: nil)
-          raise ArgumentError, "#hoist_errors must be given a block to execute" unless block_given?
-
-          result = begin
-            yield
-          rescue StandardError => e
-            log "hoist_errors block transforming a #{e.class.name} exception: #{e.message}"
-            MinimalFailedResult.new(error: nil, exception: e)
-          end
-
-          # This ensures the last line of hoist_errors was an Action call
-          #
-          # CAUTION: if there are multiple calls per block, only the last one will be checked!
-          #
-          unless result.respond_to?(:ok?)
-            raise ArgumentError,
-                  "#hoist_errors is expected to wrap an Action call, but it returned a #{result.class.name} instead"
-          end
-
-          return result if result.ok?
-
-          _handle_hoisted_errors(result, prefix:)
-        end
-
-        # Separate method to allow overriding in subclasses
-        def _handle_hoisted_errors(result, prefix: nil)
-          @__context.exception = result.exception if result.exception.present?
-          @__context.error_prefix = prefix if prefix.present?
-
-          error = result.exception.is_a?(Action::Failure) ? result.exception.message : result.error
-          fail! error
-        end
-      end
-    end
-  end
-end