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

data/lib/action/result.rb

@@ -30,70 +30,68 @@ module Action
               block.call
             rescue StandardError => e
               # Set the exception directly without triggering on_exception handlers
-              @__context.exception = e
+              @__context.__record_exception(e)
             end
+          else
+            fail! msg
           end
-          fail!
         end.call
       end
     end
 
-    # Poke some holes for necessary internal control methods
-    delegate :each_pair, to: :context
-
     # External interface
-    delegate :ok?, :exception, to: :context
+    delegate :ok?, :exception, :elapsed_time, to: :context
 
     def error
       return if ok?
 
-      [@context.error_prefix, determine_error_message].compact.join(" ").squeeze(" ")
+      _user_provided_error_message || _msg_resolver(:error, exception:).resolve_message
     end
 
     def success
       return unless ok?
 
-      determine_success_message
+      _user_provided_success_message || _msg_resolver(:success, exception: nil).resolve_message
     end
 
-    def ok = success
-
-    def message = error || success
+    def message = exception ? error : success
 
     # Outcome constants for action execution results
     OUTCOMES = [
-      OUTCOME_SUCCESS = :success,
-      OUTCOME_FAILURE = :failure,
-      OUTCOME_EXCEPTION = :exception,
+      OUTCOME_SUCCESS = "success",
+      OUTCOME_FAILURE = "failure",
+      OUTCOME_EXCEPTION = "exception",
     ].freeze
 
     def outcome
-      return OUTCOME_EXCEPTION if exception
-      return OUTCOME_FAILURE if @context.failed?
-
-      OUTCOME_SUCCESS
+      label = if exception.is_a?(Action::Failure)
+                OUTCOME_FAILURE
+              elsif exception
+                OUTCOME_EXCEPTION
+              else
+                OUTCOME_SUCCESS
+              end
+
+      ActiveSupport::StringInquirer.new(label)
     end
 
-    # Elapsed time in milliseconds
-    def elapsed_time
-      @context.elapsed_time
-    end
+    # Internal accessor for the action instance
+    # TODO: exposed for errors :from support, but should be private if possible
+    def __action__ = @action
 
     private
 
-    def context_data_source = @context.exposed_data
+    def _context_data_source = @context.exposed_data
 
-    def determine_error_message
-      return @context.error_from_user if @context.error_from_user.present?
+    # TODO: hook for adding early-return success at some point
+    def _user_provided_success_message = nil
 
-      exception = @context.exception || Action::Failure.new
-      msg = action.class._message_for(:error, action:, exception:)
-      msg.presence || "Something went wrong"
-    end
+    def _user_provided_error_message
+      return unless exception.is_a?(Action::Failure)
+      return if exception.default_message?
+      return if exception.cause # We raised this ourselves from nesting
 
-    def determine_success_message
-      msg = action.class._message_for(:success, action:, exception: nil)
-      msg.presence || "Action completed successfully"
+      exception.message.presence
     end
 
     def method_missing(method_name, ...) # rubocop:disable Style/MissingRespondToMissing (because we're not actually responding to anything additional)

data/lib/axn/factory.rb

@@ -72,17 +72,6 @@ module Axn
             expose(expose_return_as => retval) if expose_return_as.present?
           end
         end.tap do |axn|
-          apply_message = lambda do |kind, value|
-            return unless value.present?
-
-            if value.is_a?(Array) && value.size == 2
-              matcher, msg = value
-              axn.public_send(kind, msg, if: matcher)
-            else
-              axn.public_send(kind, value)
-            end
-          end
-
           expects.each do |field, opts|
             axn.expects(field, **opts)
           end
@@ -91,8 +80,9 @@ module Axn
             axn.exposes(field, **opts)
           end
 
-          apply_message.call(:success, success)
-          apply_message.call(:error, error)
+          # Apply success and error handlers
+          _apply_handlers(axn, :success, success, Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
+          _apply_handlers(axn, :error, error, Action::Core::Flow::Handlers::Descriptors::MessageDescriptor)
 
           # Hooks
           axn.before(before) if before.present?
@@ -100,10 +90,10 @@ module Axn
           axn.around(around) if around.present?
 
           # Callbacks
-          axn.on_success(&on_success) if on_success.present?
-          axn.on_failure(&on_failure) if on_failure.present?
-          axn.on_error(&on_error) if on_error.present?
-          axn.on_exception(&on_exception) if on_exception.present?
+          _apply_handlers(axn, :on_success, on_success, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_failure, on_failure, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_error, on_error, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
+          _apply_handlers(axn, :on_exception, on_exception, Action::Core::Flow::Handlers::Descriptors::CallbackDescriptor)
 
           # Strategies
           Array(use).each do |strategy|
@@ -130,12 +120,6 @@ module Axn
 
       def _hash_with_default_array = Hash.new { |h, k| h[k] = [] }
 
-      def _array_to_hash(given)
-        return given if given.is_a?(Hash)
-
-        [given].to_h
-      end
-
       def _hydrate_hash(given)
         return given if given.is_a?(Hash)
 
@@ -149,6 +133,21 @@ module Axn
           end
         end
       end
+
+      def _apply_handlers(axn, method_name, value, _descriptor_class)
+        return unless value.present?
+
+        # Check if the value itself is a hash (this catches the case where someone passes a hash literal)
+        raise Action::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if value.is_a?(Hash)
+
+        # Wrap in Array() to handle both single values and arrays
+        Array(value).each do |handler|
+          raise Action::UnsupportedArgument, "Cannot pass hash directly to #{method_name} - use descriptor objects for kwargs" if handler.is_a?(Hash)
+
+          # Both descriptor objects and simple cases (string/proc) can be used directly
+          axn.public_send(method_name, handler)
+        end
+      end
     end
   end
 end

data/lib/axn/rubocop.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Axn RuboCop Integration
+# This file makes Axn's custom RuboCop cops available to downstream consumers
+#
+# Usage in .rubocop.yml:
+# require:
+#   - axn/rubocop
+
+require_relative "../rubocop/cop/axn/unchecked_result"

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.2.7.1"
+  VERSION = "0.1.0-alpha.2.8"
 end

data/lib/rubocop/cop/axn/README.md

@@ -0,0 +1,237 @@
+# Axn RuboCop Cops
+
+This directory contains custom RuboCop cops specifically designed for the Axn library.
+
+## Axn/UncheckedResult
+
+This cop enforces proper result handling when calling Actions. It can be configured to check nested calls, non-nested calls, or both.
+
+### Why This Rule Exists
+
+When Actions are nested, proper error handling becomes crucial. Without proper result checking, failures in nested Actions can be silently ignored, leading to:
+
+- Silent failures that are hard to debug
+- Inconsistent error handling patterns
+- Potential data corruption or unexpected behavior
+
+### Configuration Options
+
+The cop supports flexible configuration to match your team's needs:
+
+```yaml
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true      # Check nested Action calls (default: true)
+  CheckNonNested: true   # Check non-nested Action calls (default: true)
+  Severity: warning      # or error, if you want to enforce it strictly
+```
+
+#### Configuration Modes
+
+1. **Full Enforcement** (default):
+   ```yaml
+   CheckNested: true
+   CheckNonNested: true
+   ```
+   Checks all Action calls regardless of nesting.
+
+2. **Nested Only**:
+   ```yaml
+   CheckNested: true
+   CheckNonNested: false
+   ```
+   Only checks Action calls from within other Actions.
+
+3. **Non-Nested Only**:
+   ```yaml
+   CheckNested: false
+   CheckNonNested: true
+   ```
+   Only checks top-level Action calls.
+
+4. **Disabled**:
+   ```yaml
+   CheckNested: false
+   CheckNonNested: false
+   ```
+   Effectively disables the cop.
+
+### Usage Examples
+
+#### ❌ Bad - Missing Result Check
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    InnerAction.call(param: "value")  # Missing result check
+    # This will always continue even if InnerAction fails
+  end
+end
+```
+
+#### ✅ Good - Using call!
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    InnerAction.call!(param: "value")  # Using call! ensures exceptions bubble up
+  end
+end
+```
+
+#### ✅ Good - Checking result.ok?
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    result = InnerAction.call(param: "value")
+    return result unless result.ok?
+    # Process successful result...
+  end
+end
+```
+
+#### ✅ Good - Checking result.failed?
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    result = InnerAction.call(param: "value")
+    if result.failed?
+      return result
+    end
+    # Process successful result...
+  end
+end
+```
+
+#### ✅ Good - Accessing result.error
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    result = InnerAction.call(param: "value")
+    if result.error
+      return result
+    end
+    # Process successful result...
+  end
+end
+```
+
+#### ✅ Good - Returning the result
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    result = InnerAction.call(param: "value")
+    result  # Result is returned, so it's properly handled
+  end
+end
+```
+
+#### ✅ Good - Using result in expose
+
+```ruby
+class OuterAction
+  include Action
+  exposes :nested_result
+  def call
+    result = InnerAction.call(param: "value")
+    expose nested_result: result  # Result is used, so it's properly handled
+  end
+end
+```
+
+#### ✅ Good - Passing result to another method
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    result = InnerAction.call(param: "value")
+    process_result(result)  # Result is used, so it's properly handled
+  end
+end
+```
+
+### What the Cop Checks
+
+The cop analyzes your code to determine if you're:
+
+1. **Inside an Action class** - Classes that `include Action`
+2. **Inside the `call` method** - Only the main execution method
+3. **Calling another Action** - Using `.call` on Action classes
+4. **Properly handling the result** - One of the acceptable patterns above
+
+### What the Cop Ignores
+
+The cop will NOT report offenses for:
+
+- Action calls outside of Action classes
+- Action calls in methods other than `call`
+- Action calls that use `call!` (bang method)
+- Action calls where the result is properly handled
+
+### Configuration
+
+Enable the cop in your `.rubocop.yml`:
+
+```yaml
+require:
+  - ./lib/rubocop/cop/axn/unchecked_result
+
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true      # Check nested Action calls
+  CheckNonNested: true   # Check non-nested Action calls
+  Severity: warning      # or error, if you want to enforce it strictly
+```
+
+### Best Practices
+
+1. **Prefer `call!` for simple cases** where you want exceptions to bubble up
+2. **Use result checking for complex logic** where you need to handle different failure modes
+3. **Always handle results explicitly** - don't let them be silently ignored
+4. **Return results early** when they indicate failure
+5. **Use meaningful variable names** for results to make your code more readable
+
+### Common Patterns
+
+#### Early Return Pattern
+```ruby
+def call
+  result = InnerAction.call(param: "value")
+  return result unless result.ok?
+
+  # Continue with successful result...
+end
+```
+
+#### Conditional Processing Pattern
+```ruby
+def call
+  result = InnerAction.call(param: "value")
+
+  if result.ok?
+    process_success(result)
+  else
+    handle_failure(result)
+  end
+end
+```
+
+#### Pass-Through Pattern
+```ruby
+def call
+  result = InnerAction.call(param: "value")
+  # Pass the result through to the caller
+  result
+end
+```