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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57d67670bb1cf60960aa2bb8234a5894a611801b69a89957057bfffd07ace8cd
-  data.tar.gz: 9e0025cbe4bc367e1351ea867d630b9fdb3d706547d676b9cd2162e8fda0ef38
+  metadata.gz: 309f7b8f6587d121756b8c3ad5d1bf8d5ba7689935920a5cd7f8c791f4bf38c4
+  data.tar.gz: '08f91a0d7344b04df8db6d9bb74bdbfb4fd095deb8dba8a105e8211dbaaa2ce0'
 SHA512:
-  metadata.gz: 70cc7c2851d95956278d43c746190dd5173ddda62a9a931ae9538374cf75b72523cc7f9b3524a6df6b8b8d57c969fb5510c07fad56b36312130ae86c59e48a15
-  data.tar.gz: f3f961781373a05284ddc54072baaf13998d235528110bf482c221e5f27d6142ab261516d8237bd0689d1161887eef6b567e8ecb4688d400a20ec32d1ae33837
+  metadata.gz: 1abdb9efc00cf6c9be0d73094c59a1322e84ca51968cf2d66af76178693db5c2fd20e99c2e2a0ee149665b92dd69ac7a3ed886ecd8567d2389b9e447978f79ac
+  data.tar.gz: 241899334f89065dec935093bbf1277a07b81101855d78e4ab56511af8561814abd372506c2f9f6df762cc79f8b1971000bfc3b425c35db8f09d3faa4d70336c

data/.rubocop.yml

@@ -1,9 +1,13 @@
+# RuboCop cops are not loaded by default in this repo
+# Downstream consumers can enable them by adding:
+# require:
+#   - axn/rubocop
+
 AllCops:
   TargetRubyVersion: 3.2
   SuggestExtensions: false
   NewCops: enable
 
-
 Style/MultilineBlockChain:
   Enabled: false
 
@@ -43,28 +47,30 @@ Metrics/ModuleLength:
   Enabled: false
 
 Metrics/ClassLength:
-  Max: 110
+  Max: 150
 
 Metrics/MethodLength:
   Max: 70
 
 Metrics/PerceivedComplexity:
-  Max: 16
+  Max: 20
 
 Metrics/AbcSize:
   Max: 60
 
 Metrics/CyclomaticComplexity:
-  Max: 16
+  Max: 20
 
 Lint/EmptyBlock:
   Enabled: false
 
 Naming/MethodParameterName:
-  AllowedNames: e, on, id
+  AllowedNames: e, on, id, if
 
 Metrics/ParameterLists:
   Max: 9
 
 Layout/LineLength:
   Max: 160
+
+

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.0-alpha.2.8
+* [FEAT] Custom RuboCop cop `Axn/UncheckedResult` to enforce proper result handling in Actions with configurable nested/non-nested checking
+* [FEAT] Added `prefix:` keyword support to `error` method for customizing error message prefixes
+  * When no block or message is provided, falls back to `e.message` with the prefix
+* [BREAKING] `result.outcome` now returns a string inquirer instead of a symbol
+* [BREAKING] **Message ordering change**: Static success/error messages (without conditions) should now be defined **first** in your action class, before any conditional messages. This ensures proper fallback behavior and prevents conditional messages from being shadowed by static ones.
+* [CHANGE] `result.exception` will new return the internal Action::Failure, rather than nil, when user calls `fail!`
+* [BREAKING] `hoist_errors` has been replaced by `error from:`
+* [FEAT] Improved Axn::Factory.build support for newly-added messaging and callback descriptors
+
 ## 0.1.0-alpha.2.7.1
 * [FEAT] Implemented symbol method handler support for callbacks
 

data/Rakefile

@@ -5,8 +5,20 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+# RuboCop specs (separate from main specs to avoid loading RuboCop unnecessarily)
+RSpec::Core::RakeTask.new(:spec_rubocop) do |task|
+  task.pattern = "spec_rubocop/**/*_spec.rb"
+end
+
 require "rubocop/rake_task"
 
+# RuboCop with Axn custom cops (targeting examples/rubocop directory)
+task :rubocop_axn do
+  sh "bundle exec rubocop --require axn/rubocop examples/rubocop/ || true"
+end
+
+# Default RuboCop task (runs on all files)
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+task all_specs: %i[spec spec_rubocop]

data/docs/intro/about.md

@@ -38,8 +38,8 @@ The core library provides many benefits for individual action calls, but also ai
   * Each layer `expects` and `exposes` its own accessor set, but internally all the values are passed down the chain (i.e. actor C can accept something A exposed that B didn’t touch and knows nothing about).
   * The top-level action must `expose` it’s own layer (effectively documenting public vs private exposures, which drastically eases refactoring)
 * Ad hoc (called arbitrarily from within other actions)
-  * `hoist_errors` (usage: `hoist_errors { Nested::Action.call }`) ensures any failure from a nested service is bubbled up to the top level (by default, as if the failure had happened there directly).
-  * Allows configurable handling at call site (e.g. setting `prefix`, so identical failures from different nested calls are distinguishable)
+  * Use `call!` to ensure any failure from a nested service raises an exception, or manually check `result.ok?` and handle failures appropriately
+  * The `from` filter on error messages can be used to distinguish failures from different nested calls
 
 ::: danger ALPHA
 * TODO: add links to sections showing usage guides/examples for the more complex flows

data/docs/intro/overview.md

@@ -134,3 +134,21 @@ For _known_ failure modes, you can call `fail!("Some user-facing explanation")`
 Any exceptions will be swallowed and the action failed (i.e. _not_ `ok?`). `result.error` will be set to a generic error message ("Something went wrong" by default, but [highly configurable](/reference/class#messages)).
 
 The swallowed exception will be available on `result.exception` for your introspection, but it'll also be passed to your `on_exception` handler so, [with a bit of configuration](/usage/setup), you can trust that any exceptions have been logged to your error tracking service automatically (one more thing the dev doesn't need to think about).
+
+::: tip Message Configuration Order
+When configuring custom error and success messages, remember to define your static fallback messages **first**, before any conditional messages. This ensures proper fallback behavior and prevents conditional messages from being shadowed.
+
+```ruby
+class MyAction
+  include Action
+
+  # Static fallback messages first
+  success "Default success message"
+  error "Default error message"
+
+  # Then conditional messages
+  success "Special success", if: :special_condition?
+  error "Special error", if: ArgumentError
+end
+```
+:::

data/docs/recipes/rubocop-integration.md

@@ -0,0 +1,352 @@
+# RuboCop Integration
+
+Axn provides custom RuboCop cops to help enforce best practices and maintain code quality in your Action-based codebase.
+
+## Overview
+
+The `Axn/UncheckedResult` cop enforces proper result handling when calling Actions. It can detect when Action results are ignored and help ensure consistent error handling patterns.
+
+## Installation
+
+### 1. Add to Your .rubocop.yml
+
+```yaml
+require:
+  - axn/rubocop
+
+# Enable Axn's custom cop
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true      # Check nested Action calls
+  CheckNonNested: true   # Check non-nested Action calls
+  Severity: warning      # or error
+```
+
+### 2. Verify Installation
+
+Run RuboCop to ensure the cop is loaded:
+
+```bash
+bundle exec rubocop --show-cops | grep Axn
+```
+
+You should see:
+```
+Axn/UncheckedResult
+```
+
+## Configuration Options
+
+### CheckNested
+
+Controls whether the cop checks Action calls that are inside other Action classes.
+
+```yaml
+Axn/UncheckedResult:
+  CheckNested: true   # Check nested calls (default)
+  CheckNested: false  # Skip nested calls
+```
+
+**When to use `CheckNested: false`:**
+- You're gradually adopting the rule and want to focus on top-level calls first
+- Your team has different standards for nested vs. non-nested calls
+- You're using a different pattern for nested Action handling
+
+### CheckNonNested
+
+Controls whether the cop checks Action calls that are outside Action classes.
+
+```yaml
+Axn/UncheckedResult:
+  CheckNonNested: true   # Check non-nested calls (default)
+  CheckNonNested: false  # Skip non-nested calls
+```
+
+**When to use `CheckNonNested: false`:**
+- You're only concerned about nested Action calls
+- Top-level Action calls are handled by other tools or processes
+- You want to focus on the most critical use case first
+
+### Severity
+
+Controls how violations are reported.
+
+```yaml
+Axn/UncheckedResult:
+  Severity: warning  # Show as warnings (default)
+  Severity: error    # Show as errors (fails CI)
+```
+
+## Common Configuration Patterns
+
+### Full Enforcement (Recommended for New Projects)
+
+```yaml
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true
+  CheckNonNested: true
+  Severity: error
+```
+
+### Gradual Adoption (Recommended for Existing Projects)
+
+```yaml
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true      # Start with nested calls
+  CheckNonNested: false  # Add this later
+  Severity: warning      # Start with warnings
+```
+
+### Nested-Only Focus
+
+```yaml
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true
+  CheckNonNested: false
+  Severity: warning
+```
+
+## 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
+
+## What the Cop Ignores
+
+The cop will NOT report offenses for:
+
+- Action calls outside of Action classes (if `CheckNonNested: false`)
+- Action calls in methods other than `call`
+- Action calls that use `call!` (bang method)
+- Action calls where the result is properly handled
+
+## Proper Result Handling Patterns
+
+### ✅ Using call!
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    InnerAction.call!(param: "value")  # Exceptions bubble up
+  end
+end
+```
+
+### ✅ 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
+```
+
+### ✅ 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
+```
+
+### ✅ 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
+```
+
+### ✅ 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
+```
+
+### ✅ 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
+```
+
+### ✅ 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
+```
+
+## Common Anti-Patterns
+
+### ❌ Ignoring the result
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    InnerAction.call(param: "value")  # Result ignored - will trigger offense
+    # This continues even if InnerAction fails
+  end
+end
+```
+
+### ❌ Assigning but not using
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    result = InnerAction.call(param: "value")  # Assigned but never used
+    # Will trigger offense unless result is properly handled
+  end
+end
+```
+
+### ❌ Using unrelated attributes
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    result = InnerAction.call(param: "value")
+    some_other_method(result.some_other_attribute)  # Not checking success/failure
+    # Will trigger offense - need to check result.ok? first
+  end
+end
+```
+
+## Migration Strategies
+
+### For New Projects
+
+1. Enable the cop with full enforcement from the start
+2. Use `Severity: error` to catch violations early
+3. Train your team on the proper patterns
+
+### For Existing Projects
+
+1. **Phase 1**: Enable with `CheckNested: true, CheckNonNested: false, Severity: warning`
+2. **Phase 2**: Fix all nested Action violations
+3. **Phase 3**: Enable `CheckNonNested: true`
+4. **Phase 4**: Fix all non-nested Action violations
+5. **Phase 5**: Set `Severity: error`
+
+### Using RuboCop Disable Comments
+
+For intentional violations, you can disable the cop:
+
+```ruby
+class OuterAction
+  include Action
+  def call
+    # rubocop:disable Axn/UncheckedResult
+    InnerAction.call(param: "value")  # Intentionally ignored
+    # rubocop:enable Axn/UncheckedResult
+  end
+end
+```
+
+## Troubleshooting
+
+### Cop Not Loading
+
+If you see "uninitialized constant" errors:
+
+1. Ensure the gem is properly installed: `bundle list | grep axn`
+2. Check your `.rubocop.yml` syntax
+3. Verify the require path: `require: - axn/rubocop`
+
+### False Positives
+
+If the cop reports violations for properly handled results:
+
+1. Check that you're using the exact patterns shown above
+2. Ensure the result variable name matches exactly
+3. Verify the result is being used in an acceptable way
+
+### Performance Issues
+
+The cop analyzes AST nodes, so it's generally fast. If you experience slowdowns:
+
+1. Ensure you're not running RuboCop on very large files
+2. Consider using RuboCop's `--parallel` option
+3. Use `.rubocop_todo.yml` for gradual adoption
+
+## Best Practices
+
+1. **Start Small**: Begin with warnings and nested calls only
+2. **Be Consistent**: Choose one pattern and stick with it
+3. **Train Your Team**: Make sure everyone understands the rules
+4. **Review Regularly**: Use the cop in your CI/CD pipeline
+5. **Document Exceptions**: Use disable comments sparingly and document why
+
+## Integration with CI/CD
+
+Add RuboCop to your CI pipeline to catch violations early:
+
+```yaml
+# .github/workflows/rubocop.yml
+name: RuboCop
+on: [push, pull_request]
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2
+      - run: bundle install
+      - run: bundle exec rubocop
+```
+
+## Related Resources
+
+- [Action Result Reference](/reference/action-result)
+- [Configuration Guide](/reference/configuration)
+- [Testing Recipes](/recipes/testing)
+- [Best Practices Guide](/advanced/conventions)

data/docs/reference/action-result.md

@@ -9,7 +9,7 @@ Every `call` invocation on an Action will return an `Action::Result` instance, w
 | `success` | User-facing success message (string), if `ok?` (else nil)
 | `message` | User-facing message (string), always defined (`ok? ? success : error`)
 | `exception` | If not `ok?` because an exception was swallowed, will be set to the swallowed exception (note: rarely used outside development; prefer to let the library automatically handle exception handling for you)
-| `outcome` | The execution outcome as a symbol (`:success`, `:failure`, or `:exception`)
+| `outcome` | The execution outcome as a string inquirer (`success?`, `failure?`, `exception?`)
 | `elapsed_time` | Execution time in milliseconds (Float)
 | any `expose`d values | guaranteed to be set if `ok?` (since they have outgoing presence validations by default; any missing would have failed the action)
 

data/docs/reference/class.md

@@ -124,6 +124,40 @@ def build_error_message(exception:)
 end
 ```
 
+::: warning Message Ordering
+**Important**: Static success/error messages (those without conditions) should be defined **first** in your action class. If you define conditional messages before static ones, the conditional messages will never be reached because the static message will always match first.
+
+**Correct order:**
+```ruby
+class MyAction
+  include Action
+
+  # Define static fallback first
+  success "Default success message"
+  error "Default error message"
+
+  # Then define conditional messages
+  success "Special success", if: :special_condition?
+  error "Special error", if: ArgumentError
+end
+```
+
+**Incorrect order (conditional messages will be shadowed):**
+```ruby
+class MyAction
+  include Action
+
+  # These conditional messages will never be reached!
+  success "Special success", if: :special_condition?
+  error "Special error", if: ArgumentError
+
+  # Static messages defined last will always match first
+  success "Default success message"
+  error "Default error message"
+end
+```
+:::
+
 ## Conditional messages
 
 While `.error` and `.success` set the default messages, you can register conditional messages using an optional `if:` or `unless:` matcher. The matcher can be:
@@ -145,6 +179,10 @@ error "Invalid params provided", if: ActiveRecord::InvalidRecord
 error(if: ArgumentError) { |e| "Argument error: #{e.message}" }
 error(if: -> { name == "bad" }) { "Bad input #{name}, result: #{result.status}" }
 
+# Custom message with prefix (falls back to exception message when no block/message provided)
+error(if: ArgumentError, prefix: "Foo: ") { "bar" }  # Results in "Foo: bar"
+error(if: StandardError, prefix: "Baz: ")            # Results in "Baz: [exception message]"
+
 # Custom message with symbol predicate (arity 0)
 error "Transient error, please retry", if: :transient_error?
 
@@ -182,6 +220,73 @@ end
 You cannot use both `if:` and `unless:` for the same message - this will raise an `ArgumentError`.
 :::
 
+## Error message inheritance with `from:`
+
+The `from:` parameter allows you to customize error messages when an action calls another action that fails. This is particularly useful for adding context or prefixing error messages from child actions.
+
+When using `from:`, the error handler receives the exception from the child action, and you can access the child's error message via `e.message` (which contains the `result.error` from the child action).
+
+```ruby
+class InnerAction
+  include Action
+
+  error "Something went wrong in the inner action"
+
+  def call
+    raise StandardError, "inner action failed"
+  end
+end
+
+class OuterAction
+  include Action
+
+  # Customize error messages from InnerAction
+  error from: InnerAction do |e|
+    "Outer action failed: #{e.message}"
+  end
+
+  def call
+    InnerAction.call!
+  end
+end
+```
+
+In this example:
+- When `InnerAction` fails, `OuterAction` will catch the exception
+- The `e.message` contains the error message from `InnerAction`'s result
+- The final error message will be "Outer action failed: Something went wrong in the inner action"
+
+This pattern is especially useful for:
+- Adding context to error messages from sub-actions
+- Implementing consistent error message formatting across action hierarchies
+- Providing user-friendly error messages that include details from underlying failures
+
+### Combining `from:` with `prefix:`
+
+You can also combine the `from:` parameter with the `prefix:` keyword to create consistent error message formatting:
+
+```ruby
+class OuterAction
+  include Action
+
+  # Add prefix to error messages from InnerAction
+  error from: InnerAction, prefix: "API Error: " do |e|
+    "Request failed: #{e.message}"
+  end
+
+  # Or use prefix only (falls back to exception message)
+  error from: InnerAction, prefix: "API Error: "
+
+  def call
+    InnerAction.call!
+  end
+end
+```
+
+This results in:
+- With custom message: "API Error: Request failed: Something went wrong in the inner action"
+- With prefix only: "API Error: Something went wrong in the inner action"
+
 ### Message ordering and inheritance
 
 Messages are evaluated in **last-defined-first** order, meaning the most recently defined message that matches its conditions will be used. This applies to both success and error messages:
@@ -216,8 +321,11 @@ class MyAction
 end
 ```
 
-When using conditional messages, the system evaluates handlers in the order defined above until it finds one that matches and doesn't raise an exception. If a handler raises an exception, it falls back to the next matching handler, then to static messages, and finally to the default message.
-```
+::: tip Message Evaluation Order
+The system evaluates handlers in the order they were defined until it finds one that matches and doesn't raise an exception. If a handler raises an exception, it falls back to the next matching handler, then to static messages, and finally to the default message.
+
+**Key point**: Static messages (without conditions) are evaluated **first** in the order they were defined. This means you should define your static fallback messages at the top of your class, before any conditional messages, to ensure proper fallback behavior.
+:::
 
 ## Callbacks
 

data/docs/reference/configuration.md

@@ -74,7 +74,7 @@ For example, to wire up Datadog:
     end
 
     c.emit_metrics = proc do |resource, result|
-      TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome, resource: })
+      TS::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome.to_s, resource: })
       TS::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
     end
   end
@@ -83,7 +83,7 @@ For example, to wire up Datadog:
 A couple notes:
 
   * `Datadog::Tracing` is provided by [the datadog gem](https://rubygems.org/gems/datadog)
-  * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that the result object provides access to the outcome (`success`, `failure`, `exception`) and elapsed time of the action.
+  * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that the result object provides access to the outcome (`result.outcome.success?`, `result.outcome.failure?`, `result.outcome.exception?`) and elapsed time of the action.
   * The `wrap_with_trace` hook is an around hook - you must call the provided block to execute the action
   * The `emit_metrics` hook is called after execution with the result - do not call any blocks
 
@@ -91,6 +91,8 @@ A couple notes:
 
 Defaults to `Rails.logger`, if present, otherwise falls back to `Logger.new($stdout)`.  But can be set to a custom logger as necessary.
 
+
+
 ## `additional_includes`
 
 This is much less critical than the preceding options, but on the off chance you want to add additional customization to _all_ your actions you can set additional modules to be included alongside `include Action`.
@@ -172,7 +174,7 @@ Action.configure do |c|
   end
 
   c.emit_metrics = proc do |resource, result|
-    Datadog::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome })
+    Datadog::Metrics.increment("action.#{resource.underscore}", tags: { outcome: result.outcome.to_s })
     Datadog::Metrics.histogram("action.duration", result.elapsed_time, tags: { resource: })
   end