axn 0.1.0.pre.alpha.2.8.1 → 0.1.0.pre.alpha.4

data/docs/recipes/memoization.md

@@ -1,46 +1,131 @@
-### Adding memoization
+# Memoization
 
-For a practical example of [the `additional_includes` configuration](/reference/configuration#additional-includes) in practice, consider adding new functionality to all Actions.
+Axn has built-in memoization support via the `memo` helper. This caches the result of method calls, ensuring they're only computed once per action execution.
 
-For instance, at Teamshares we automatically add memoization support (via [memo_wise](https://github.com/panorama-ed/memo_wise)) to all Actions.  But we didn't want to add another dependency to the core library, so we've implemented this by:
+## Basic Usage
 
+The `memo` helper works out of the box for methods without arguments:
 
 ```ruby
-  Action.configure do |c|
-    c.additional_includes = [TS::Memoization]
+class GenerateReport
+  include Axn
+
+  expects :company, model: Company
+  exposes :report
+
+  def call
+    expose report: {
+      total_revenue: total_revenue,
+      top_products: top_products.map(&:name),
+      # top_products is only queried once, even though it's called twice
+      product_count: top_products.count
+    }
+  end
+
+  private
+
+  memo def top_products
+    company.products.order(sales_count: :desc).limit(10)
+  end
+
+  memo def total_revenue
+    company.orders.sum(:total)
   end
+end
 ```
 
+## How It Works
+
+- `memo` wraps the method and caches its return value on first call
+- Subsequent calls return the cached value without re-executing the method
+- Memoization is scoped to the action instance, so each `call` starts fresh
+
+## Methods With Arguments
+
+For methods that accept arguments, Axn supports the `memo_wise` gem:
+
+```ruby
+# Gemfile
+gem "memo_wise"
+```
+
+With `memo_wise` available, you can automatically memoize methods with arguments:
+
 ```ruby
-module TS::Memoization
-  extend ActiveSupport::Concern
+class CalculatePricing
+  include Axn
 
-  included do
-    prepend MemoWise
+  expects :product
+  exposes :pricing
+
+  def call
+    expose pricing: {
+      retail: price_for(:retail),
+      wholesale: price_for(:wholesale),
+      # Each unique argument is cached separately
+      bulk: price_for(:bulk)
+    }
   end
 
-  class_methods do
-    def memo(...) = memo_wise(...)
+  private
+
+  memo def price_for(tier)
+    # Complex pricing calculation...
+    PricingEngine.calculate(product, tier:)
   end
 end
 ```
 
-And with those pieces in place `memo` is available in all Actions:
+If you try to use `memo` on a method with arguments without `memo_wise` installed, you'll get a helpful error:
+
+```
+ArgumentError: Memoization of methods with arguments requires the 'memo_wise' gem.
+Please add 'memo_wise' to your Gemfile or use a method without arguments.
+```
+
+## When to Use Memoization
+
+Memoization is particularly useful for:
+
+- **Database queries** called multiple times within an action
+- **API calls** or external service lookups
+- **Complex computations** that are expensive to repeat
 
 ```ruby
-class ContrivedExample
-  include Action
+class SyncUserData
+  include Axn
 
-  exposes :nums
+  expects :user, model: User
 
   def call
-    expose nums: Array.new(10) { random_number }
+    update_profile if needs_profile_update?
+    update_preferences if needs_preferences_update?
+    notify_if_changed
   end
 
   private
 
-  memo def random_number = rand(1..100) # [!code focus]
+  # Called multiple times - only fetches once
+  memo def external_data
+    ExternalApi.fetch_user_data(user.external_id)
+  end
+
+  def needs_profile_update?
+    external_data[:profile_version] > user.profile_version
+  end
+
+  def needs_preferences_update?
+    external_data[:preferences_hash] != user.preferences_hash
+  end
+
+  def notify_if_changed
+    # ...
+  end
 end
 ```
 
-Because of the `memo` usage, `ContrivedExample.call.nums` will be a ten-element array of _the same number_, rather than re-calling `rand` for each element.
+## Notes
+
+- Memoization persists only for the duration of a single action execution
+- When `memo_wise` is available, Axn automatically uses it (no configuration needed)
+- See the [memo_wise documentation](https://github.com/panorama-ed/memo_wise) for advanced features like cache resetting

data/docs/recipes/rubocop-integration.md

@@ -1,12 +1,16 @@
 # RuboCop Integration
 
-Axn provides custom RuboCop cops to help enforce best practices and maintain code quality in your Action-based codebase.
+Axn provides a custom RuboCop cop to help enforce proper result handling when calling Actions.
 
-## Overview
+## What It Does
 
-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.
+The `Axn/UncheckedResult` cop detects when you call another Action from within an Action but don't properly handle the result. This helps prevent silent failures and ensures consistent error handling patterns.
 
-## Installation
+> **⚠️ Warning**: This cop uses static analysis and cannot distinguish between actual Axn classes and other classes that happen to have a `call` method. If you're using legacy services or other service patterns alongside Axn, you may encounter false positives. Use RuboCop disable comments for intentional violations.
+>
+> **💡 Tip**: If you're using the Actions namespace (see [Rails Integration](/usage/setup#rails-integration-optional)), you can configure the cop to only check `Actions::*` classes, eliminating false positives from other service objects.
+
+## Setup
 
 ### 1. Add to Your .rubocop.yml
 
@@ -14,137 +18,37 @@ The `Axn/UncheckedResult` cop enforces proper result handling when calling Actio
 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
+  Severity: warning
 ```
 
 ### 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
+You should see `Axn/UncheckedResult` in the output.
 
-### Full Enforcement (Recommended for New Projects)
+## Basic Usage
 
-```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!
+### ✅ Good - Using call!
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     InnerAction.call!(param: "value")  # Exceptions bubble up
   end
 end
 ```
 
-### ✅ Checking result.ok?
+### ✅ Good - Checking the result
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
     result = InnerAction.call(param: "value")
     return result unless result.ok?
@@ -153,200 +57,50 @@ class OuterAction
 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
+### ❌ Bad - Ignoring the result
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
-    InnerAction.call(param: "value")  # Result ignored - will trigger offense
+    InnerAction.call(param: "value")  # Will trigger offense
     # This continues even if InnerAction fails
   end
 end
 ```
 
-### ❌ Assigning but not using
+## Configuration
 
-```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
-```
+The cop supports flexible configuration:
 
-### ❌ 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
+```yaml
+Axn/UncheckedResult:
+  Enabled: true
+  CheckNested: true      # Check nested Axn calls (default: true)
+  CheckNonNested: true   # Check non-nested Axn calls (default: true)
+  ActionsNamespace: "Actions"  # Only check Actions::* classes (optional)
+  Severity: warning      # or error
 ```
 
-## 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
+### ActionsNamespace Configuration
 
-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`
+When using the Actions namespace, you can configure the cop to only check calls on `Actions::*` classes:
 
-### Using RuboCop Disable Comments
+```yaml
+Axn/UncheckedResult:
+  ActionsNamespace: "Actions"
+```
 
-For intentional violations, you can disable the cop:
+This eliminates false positives from other service objects while still catching unchecked Axn action calls:
 
 ```ruby
 class OuterAction
-  include Action
+  include Axn
   def call
-    # rubocop:disable Axn/UncheckedResult
-    InnerAction.call(param: "value")  # Intentionally ignored
-    # rubocop:enable Axn/UncheckedResult
+    SomeService.call(param: "value")        # Won't trigger cop
+    Actions::InnerAction.call(param: "value")  # Will trigger cop
   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)
+For detailed configuration options, usage patterns, and troubleshooting, see the [technical documentation](https://github.com/teamshares/axn/blob/main/lib/rubocop/cop/axn/README.md).

data/docs/recipes/testing.md

@@ -8,23 +8,23 @@
 
 Say you're writing unit specs for PrimaryAction that calls Subaction, and you want to mock out the Subaction call.
 
-To generate a successful Action::Result:
+To generate a successful Axn::Result:
 
-* Base case: `Action::Result.ok`
-* [Optional] Custom message: `Action::Result.ok("It went awesome")`
-* [Optional] Custom exposures: `Action::Result.ok("It went awesome", some_var: 123)`
+* Base case: `Axn::Result.ok`
+* [Optional] Custom message: `Axn::Result.ok("It went awesome")`
+* [Optional] Custom exposures: `Axn::Result.ok("It went awesome", some_var: 123)`
 
-To generate a failed Action::Result:
+To generate a failed Axn::Result:
 
-* Base case: `Action::Result.error`
-* [Optional] Custom message: `Action::Result.error("It went poorly")`
-* [Optional] Custom exposures: `Action::Result.error("It went poorly", some_var: 123)`
-* [Optional] Custom exception: `Action::Result.error(some_var: 123) { raise FooBarException.new("bad thing") }`
+* Base case: `Axn::Result.error`
+* [Optional] Custom message: `Axn::Result.error("It went poorly")`
+* [Optional] Custom exposures: `Axn::Result.error("It went poorly", some_var: 123)`
+* [Optional] Custom exception: `Axn::Result.error(some_var: 123) { raise FooBarException.new("bad thing") }`
 
 Either way, using those to mock an actual call would look something like this in your rspec:
 
 ```ruby
-let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+let(:subaction_response) { Axn::Result.ok("custom message", foo: 1) }
 
 before do
   expect(Subaction).to receive(:call).and_return(subaction_response)
@@ -38,7 +38,7 @@ The semantics of call-bang are a little different -- if Subaction is called via
 ### Success
 
 ```ruby
-let(:subaction_response) { Action::Result.ok("custom message", foo: 1) }
+let(:subaction_response) { Axn::Result.ok("custom message", foo: 1) }
 
 before do
   expect(Subaction).to receive(:call!).and_return(subaction_response)
@@ -57,18 +57,18 @@ before do
 end
 ```
 
-NOTE: to mock subaction failing via explicit `fail!` call, you'd use an `Action::Failure` exception class.
+NOTE: to mock subaction failing via explicit `fail!` call, you'd use an `Axn::Failure` exception class.
 
 ## Mocking Axn arguments
 
-Be aware that in order to improve testing ergonomics, the `type` validation will return `true` for _any_ `RSpec::Mocks::` subclass _as long as `Action.config.env.test?` is `true`_.
+Be aware that in order to improve testing ergonomics, the `type` validation will return `true` for _any_ `RSpec::Mocks::` subclass _as long as `Axn.config.env.test?` is `true`_.
 
 This makes it much easier to test Axns, as you can pass in mocks without immediately failing the inbound validation.
 
 ```ruby
 subject(:result) { action.call!(sym:) }
 
-let(:action) { build_action { expects :sym, type: Symbol } }
+let(:action) { build_axn { expects :sym, type: Symbol } }
 
 context "with a symbol" do
   let(:sym) { :hello }

data/docs/recipes/validating-user-input.md

@@ -1,7 +1,7 @@
 # Validating _user_ input
 
 ::: danger ALPHA
-This has not yet been fully fleshed out.  For now, the general idea is that user-facing validation is a _separate layer_ from the declarative expectations about what inputs your Action takes (e.g. `expects :params` and pass to a form object, rather than accepting field-level params directly).
+This has not yet been fully fleshed out.  For now, the general idea is that user-facing validation is a _separate layer_ from the declarative expectations about what inputs your Axn takes (e.g. `expects :params` and pass to a form object, rather than accepting field-level params directly).
 :::