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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e825e850ff02abfa953a14dac87254b9775affb063a64f7c0138d98eda4b99d
-  data.tar.gz: de54b6c1a8274de2ec8131e1c3d2c53c7ea9eb844b0ec0661682f212dc00cda7
+  metadata.gz: 8930af546a87917b02eb7c4af3fdc88670f6b323cbf9e7223553eca07ac6bf8c
+  data.tar.gz: 47a70ea981ae8c9a7405e02c844174996c0d1a3b9788cbf5c37d725d77f00d5c
 SHA512:
-  metadata.gz: b307adb81a4eac8b0cebca6778eeb060af5013a6b008f414085501e5cb7c8bb9fc32fbd4770ac8e458bf5a4f919d61b022bc5bc129199b3ae7b2f562f85f4b6a
-  data.tar.gz: 692efe5f507fd04dec768862eb9277e2a39af3b8eea182b2e8f1ca09e0f0910ab7080dd07f6d7f5605a673cab0feab7aa1194032b54ad2c550e42b794bc44965
+  metadata.gz: 83c3a6d065d240bf73ccca409b40e2a0560901617d98b5fe3f9aaefbf3ef87ab444bdd20220b01ce8481ccea55278240433a0641d9549c63a47329d13e3bb5ce
+  data.tar.gz: adfe79828b95caa34379fe0424b4aa2b9a3ee06247eeb29b10c2b7b9fded83dcf327993e13da84f913e5e2c05ad0b53a77562ffe3c1ad25d814265c526b49a78

data/.cursor/commands/pr.md

@@ -0,0 +1,36 @@
+Create a pull request for the current branch.
+
+## Pre-flight checks
+
+1. Run `git status` to check for uncommitted changes.
+    If there are uncommitted changes, stop and ask the user to commit or stash them first
+2. Run `git branch --show-current` to get the branch name
+    Verify not on main/master - if so, stop and ask the user to create a branch first
+3. Run the test suite (`bundle exec rake all_specs` and `bundle exec rubocop`)
+    If any test suite failures, stop and prompt user to resolve first
+
+## Gather context
+
+4. Run `git log origin/main..HEAD --oneline` to see all commits on this branch
+5. Run `git diff origin/main...HEAD --stat` to see changed files
+6. If needed, read the diff for key files to understand the changes
+
+## Generate PR content
+
+7. Generate a PR title: a single line that summarizes the changes (imperative mood, e.g., "Add batch enqueueing support")
+8. Generate a PR body with:
+   - **Summary**: a handful of bullet points describing the key changes
+   - **Details**: If sufficiently complex, include details of each notable change
+   - **Usage Example**: If applicable, a brief code example demonstrating the new or changed feature/API
+
+## Push and create PR
+
+9. Push the branch: `git push -u origin HEAD`
+10. Create the PR as a draft using gh:
+
+gh pr create --draft --title "THE TITLE" --body "$(cat <<'EOF'
+THE BODY HERE
+EOF
+)"
+
+11. Report the PR URL to the user as a link they can click

data/.cursor/rules/axn-framework-patterns.mdc

@@ -0,0 +1,43 @@
+# Axn Framework Usage Patterns
+
+## Basic Action Structure
+- Always include `Axn` module: `class MyAction; include Axn; end`
+- Declare interface with `expects` and `exposes` at class level
+- Implement `call` method for action logic
+- Use `expose` to return data (must be declared in `exposes` first)
+- Use `fail!` for expected failures, `done!` for early success completion
+
+## Execution Patterns
+- Use `call` for result objects (swallows exceptions, returns `Axn::Result`)
+- Use `call!` for exception-throwing behavior (re-raises exceptions)
+- Use `call_async` for background execution (requires async configuration)
+
+## Data Flow and Validation
+- `expects` declares required input parameters with validation options
+- `exposes` declares output data that must be provided via `expose`
+- Common validation options: `type:`, `optional:`, `allow_nil:`, `allow_blank:`, `default:`, `sensitive:`
+- Use `model: true` for auto-hydrating records from IDs
+- Use `on:` for nested field expectations and accessors
+
+## Composition Patterns
+- Use `step :name, expects: [:input], exposes: [:output]` for inline steps
+- Use `steps(Class1, Class2)` to compose existing action classes
+- Steps execute sequentially and share data through `expects`/`exposes`
+- Step failures are automatically prefixed with step name
+
+## Message and Error Handling
+- Use `success` and `error` declarations for custom messages
+- Support conditional messages with `if:`/`unless:` matchers
+- Use `from:` parameter for error message inheritance from child actions
+- Use `prefix:` for consistent error message formatting
+- Define static messages first, then conditional messages
+
+## Async and Background Processing
+- Configure with `async :sidekiq` or `async :active_job`
+- Use `call_async` for background execution
+- Supports all adapter-specific configuration options
+
+## Hooks and Callbacks
+- Hooks (`before`/`after`/`around`) execute as part of `call` - failures affect `result.ok?`
+- Callbacks (`on_success`/`on_error`/`on_failure`/`on_exception`) execute after `call` - failures don't affect `result.ok?`
+- Use `done!` for early completion (skips `after` hooks, allows `around` hooks to complete)

data/.cursor/rules/general-coding-standards.mdc

@@ -0,0 +1,27 @@
+# General Coding Standards
+
+## Code Quality Principles
+- Always prioritize clean, elegant, and maintainable code following these principles:
+- Write code that is both functional and beautiful - elegance should be a primary concern
+- Follow existing patterns in the codebase
+- Use DRY principles and eliminate duplication
+- Create reusable/shared examples for similar test patterns
+- Consolidate similar functionality where appropriate
+- Match existing code style and structure
+- Consider maintainability and extensibility first
+- Look for refactoring opportunities
+- Use parameterized testing and shared examples in specs
+- Prefer simple, readable solutions over clever but complex ones
+- Write code that tells a story and is self-documenting
+
+## Method Organization
+- Place private method declarations under a private stanza rather than marking them private after the fact
+- Use single-line changelog edits
+- Use Ruby endless method definitions for short helper methods
+- Use a series of return-early if statements instead of long if/else chains for stylistic consistency
+
+## Communication Style
+- Be direct, neutral, and concise
+- Be sparing with praise, flattery, or enthusiasm
+- Do not say the user is right unless verified; confirm first
+- Prefer: "It appears/It seems/Based on X…" over absolute claims

data/.cursor/rules/spec/testing-patterns.mdc

@@ -0,0 +1,40 @@
+# RSpec Testing Patterns
+
+## Use build_axn Spec Helper
+- Always use the `build_axn` spec helper instead of manually creating Axn classes
+- Prefer `build_axn { ... }` over `Axn::Factory.build { ... }` in test files
+- Prefer `build_axn { ... }` over `Class.new.send(:include, Axn)` patterns
+- The `build_axn` helper is already included via `Axn::Testing::SpecHelpers` and provides a cleaner, more readable way to create test Axn classes
+
+## DRY Test Setup
+- When writing RSpec tests with repeated object creation patterns, prefer using `let`/`let!` to define base objects once and override specific attributes in contexts
+- Use shared examples (`shared_examples`/`include_examples`) for testing similar methods with different parameters
+- Avoid recreating the same object structure multiple times - use `let` to override only the values that change between contexts
+
+### Example Pattern:
+```ruby
+# Instead of recreating objects in each context:
+context "scenario 1" do
+  let!(:object) { create(:model, attr1: value1, attr2: value2) }
+end
+context "scenario 2" do
+  let!(:object) { create(:model, attr1: value3, attr2: value4) }
+end
+
+# Prefer this pattern:
+let!(:object) { create(:model, attr1: attr1_value, attr2: attr2_value) }
+context "scenario 1" do
+  let(:attr1_value) { value1 }
+  let(:attr2_value) { value2 }
+end
+context "scenario 2" do
+  let(:attr1_value) { value3 }
+  let(:attr2_value) { value4 }
+end
+```
+
+## Test Organization
+- Use `it { expect(...).to eq(...) }` shorthand for simple assertions. `it { is_expected.to ... }` even better.
+- Group related tests with shared examples when testing similar methods
+- Prefer descriptive context names over verbose test descriptions
+- Don't open rails console - debug via scripts or runner instead.

data/CHANGELOG.md

@@ -1,8 +1,65 @@
 # Changelog
 
+## Unreleased
+* [FEAT] Action class constants are now created eagerly when child classes inherit from parents with mounted actions, allowing direct constant access (e.g., `TeamsharesAPI::Company::Axns::Get.call`)
+* [FEAT] Add ability to determine if currently running in background
+* [FEAT] Handle done! and fail! while executing user blocks
+* [BREAKING] `emit_metrics` hook now receives keyword arguments (`resource:`, `result:`) instead of positional arguments
+* [FEAT] Default `call` method automatically exposes declared exposures by calling methods with matching names - you can now omit `call` entirely when you only need to expose values from private methods
+* [BREAKING] Rename `auto_log` -> `log_calls`
+* [FEAT] Add `log_errors`
+* [FEAT] Add `raise_piping_errors_in_dev` config option to raise framework errors in dev only
+* [BREAKING] Convert profiling from `profile` method to `use :vernier` strategy - profiling now only captures hooks and user code (excludes framework overhead like tracing, logging, timing)
+* [FEAT] Add `set_logging_context` and `additional_logging_context` hook to inject additional context into exception logging
+* [FEAT] Added ActiveSupport::Notification emission for `axn.call_async` (separate from `axn.call`) - emits notification when async jobs are enqueued with payload including resource, action_class, kwargs, and adapter name
+* [INTERNAL] Refactored async adapters to use template method pattern - adapters now implement `_enqueue_async_job` hook instead of overriding `call_async`, eliminating duplication of notification and logging logic
+* [FEAT] Enhanced `error from:` to support arrays of child classes and `from: true` to match any child action - prefix is now optional when using `from:`
+* Improve handling of _async options to call_async (bugfix + serialization improvements)
+* [BREAKING] Replace `enqueue_all_via` block with new `enqueues_each` DSL (now in `Axn::Async`) - declarative batch enqueueing for background job processing
+
+## 0.1.0-alpha.3
+* [FEAT] Added Vernier profiling support with `profile if:` conditional interface and `Axn.config.profiling` configuration
+* [FEAT] Extended model validation to support custom finder methods with `expects :user, model: { klass: User, finder: :find }` syntax
+* [BREAKING] Removed `#try` method
+* [BREAKING] Removed `Axn()` method sugar (use `Axn::Factory.build` directly)
+* [BREAKING] Renamed `Action::Configuration` + `Action.config` -> `Axn::Configuration` + `Axn.config`
+* [BREAKING] Move `Axn::Util` to `Axn::Internal::Logging`
+* [BREAKING] !! Move all `Action` to `Axn` (notably `include Action` is now `include Axn`)
+* [FEAT] Continues to support plain ruby usage, but when used alongside Rails now includes a Rails Engine integrate automatically (e.g. providing generators).
+  * Added Rails generator `rails generate axn Some::Action::Name foo bar` to create action classes with expectations
+  * Autoload actions from `app/actions` (add config.rails.app_actions_autoload_namespace to allow setting custom namespace)
+* [INTERNAL] Clearer hooks for supporting additional background providers in the future
+* [BREAKING] spec_helpers: removed rarely used `build_axn`; renamed existing `build_action` -> `build_axn`
+* [FEAT] `Axn::Factory.build` can receive a callable OR a block
+* [FEAT] Added `#finalized?` method to `Axn::Result` to check if result has completed execution
+* [FEAT] Added `type: :params` validation option for `expects`/`exposes` that accepts Hash or ActionController::Parameters (Rails-compatible)
+* [FEAT] Allow validations to access instance methods (e.g. `inclusion: { in: :some_method }`)
+* [FEAT] Allow message `prefix` to invoke callables/method name symbols the same way e.g. `if` does
+* [BREAKING] `default`s for `expects` and `exposes` are only applied to explicitly `nil` values (previous applied if given value was blank, which caused bugs for boolean handling)
+* [FEAT] Support `sensitive: true` on subfields (with `on:`)
+* [FEAT] Support `preprocess` on subfields (with `on:`)
+* [FEAT] Support `default` on subfields (with `on:`)
+* [FEAT] Added `#done!` method for early completion with success result
+* [FEAT] Extended `#fail!` and `#done!` methods to accept keyword arguments for exposing data before halting execution
+* [INTERAL] Renamed `Axn::Enqueueable` to `Axn::Async`
+* [BREAKING] Replaced `.enqueue` (only supported sidekiq) with `.call_async` (via a configurable registry of backgrounding libraries)
+* [FEAT] attachable now creates a foo_async to call call_async
+* `type` validator is not still applied to the blank value when allow_blank is true (`type: Hash` will no longer accept `false` or `""`)
+* [FEAT] `expects`/`exposes` now prefers new `optional: true` over allow_blank for simplicity
+* [FEAT] `Axn::Result` now supports Ruby 3's pattern matching feature
+* [FEAT] Extended attachable functionality: added `mount_axn_method` for creating class methods that return values directly instead of wrapped in `Axn::Result`
+* [Internal] Replaced `Axn::Attachable` with `Axn::Mountable` - complete refactor of action mounting system
+  * [BREAKING] `#axn` → `#mount_axn` for method mounting
+  * [BREAKING] `#axn_method` → `#mount_axn_method` for direct method mounting
+  * [NEW] `enqueue_all_via` - Mount batch enqueueing functionality for background job processing
+* [FEAT] Enhanced async execution with job scheduling support
+  * [NEW] Support for scheduled async jobs via `_async` parameter with `wait_until:` and `wait:` options
+  * [NEW] `enqueue` shortcut methods for all mounted actions
+
 ## 0.1.0-alpha.2.8.1
 * [BUGFIX] Fixed symbol callback and message handlers not working in inherited classes due to private method visibility issues
 * [BUGFIX] `default_error` and `default_success` are now properly available for before hooks
+* [FEAT] Support scheduling async jobs (via new `_async` key)
 
 ## 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

data/Rakefile

@@ -6,14 +6,22 @@ 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"
+task :spec_rubocop do
+  files = Dir.glob("spec_rubocop/**/*_spec.rb")
+  sh "bundle exec rspec #{files.join(' ')}"
+end
+
+# Rails specs (separate from main specs to avoid loading Rails unnecessarily)
+task :spec_rails do
+  Dir.chdir("spec_rails/dummy_app") do
+    sh "BUNDLE_GEMFILE=Gemfile bundle exec rspec spec/"
+  end
 end
 
 require "rubocop/rake_task"
 
 # RuboCop with Axn custom cops (targeting examples/rubocop directory)
-task :rubocop_axn do
+task :rubocop_examples do
   sh "bundle exec rubocop --require axn/rubocop examples/rubocop/ || true"
 end
 
@@ -21,4 +29,106 @@ end
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
-task all_specs: %i[spec spec_rubocop]
+task rails_specs: %i[spec_rails]
+task rubocop_specs: %i[spec_rubocop]
+task all_specs: %i[spec spec_rubocop spec_rails]
+task specs: %i[all_specs]
+
+# Benchmark tasks
+namespace :benchmark do
+  desc "Run benchmarks and save results for current gem version (runs automatically after rake release)"
+  task :release do
+    require_relative "benchmark/support/benchmark_runner"
+    require_relative "benchmark/support/storage"
+    require_relative "lib/axn/version"
+    require_relative "benchmark/support/colors"
+
+    puts Colors.bold(Colors.info("🔬 Running benchmarks for release..."))
+    puts Colors.dim("=" * 80)
+    puts ""
+
+    version = Axn::VERSION
+    puts Colors.info("Version: #{version}")
+    puts ""
+
+    # Check if benchmark already exists for this version
+    filename = Benchmark::Storage.benchmark_filename(version)
+    if File.exist?(filename)
+      puts Colors.error("❌ Benchmark file already exists for version #{version}")
+      puts Colors.info("   File: #{filename}")
+      puts Colors.info("   Delete the file if you want to regenerate benchmarks for this version.")
+      abort
+    end
+
+    # Run benchmarks with verbose output
+    data = Benchmark::BenchmarkRunner.run_all_scenarios(verbose: true)
+
+    # Save benchmark data (filename already determined above)
+    saved_filename = Benchmark::Storage.save_benchmark(data, version)
+    puts ""
+    puts Colors.success("✅ Benchmark data saved to: #{saved_filename}")
+
+    # Update last release version
+    Benchmark::Storage.set_last_release_version(version)
+    puts Colors.success("✅ Last release version updated to: #{version}")
+    puts ""
+    puts Colors.dim("=" * 80)
+  end
+
+  desc "Compare current code performance against last release"
+  task :compare do
+    require_relative "benchmark/support/benchmark_runner"
+    require_relative "benchmark/support/storage"
+    require_relative "benchmark/support/comparison"
+    require_relative "lib/axn/version"
+    require_relative "benchmark/support/colors"
+
+    puts Colors.bold(Colors.info("🔬 Comparing performance against last release..."))
+    puts Colors.dim("=" * 80)
+    puts ""
+
+    # Get last release version
+    last_release_version = Benchmark::Storage.get_last_release_version
+
+    if last_release_version.nil?
+      puts Colors.error("❌ No last release version found.")
+      puts Colors.info("   Run 'rake benchmark:release' after a gem release to create a baseline.")
+      exit 1
+    end
+
+    puts Colors.info("Last release version: #{last_release_version}")
+    puts ""
+
+    # Load baseline benchmark
+    baseline_data = Benchmark::Storage.load_benchmark(last_release_version)
+
+    if baseline_data.nil?
+      puts Colors.error("❌ Benchmark data not found for version: #{last_release_version}")
+      puts Colors.info("   Run 'rake benchmark:release' to create a baseline.")
+      exit 1
+    end
+
+    puts Colors.info("Running benchmarks on current code...")
+    puts ""
+
+    # Run current benchmarks (quiet mode for cleaner output)
+    current_data = Benchmark::BenchmarkRunner.run_all_scenarios(verbose: false)
+
+    puts ""
+    puts Colors.info("Comparing results...")
+    puts ""
+
+    # Compare and display
+    comparison = Benchmark::Comparison.compare(baseline_data, current_data)
+    puts Benchmark::Comparison.format_comparison(comparison)
+  end
+end
+
+# Automatically run benchmark:release after rake release
+Rake::Task["release"].enhance do
+  require_relative "benchmark/support/colors"
+  puts ""
+  puts Colors.bold(Colors.info("🔬 Running benchmarks for released version..."))
+  Rake::Task["benchmark:release"].reenable
+  Rake::Task["benchmark:release"].invoke
+end

data/docs/.vitepress/config.mjs

@@ -28,6 +28,7 @@ export default defineConfig({
           { text: 'Getting Started', link: '/usage/setup' },
           { text: 'Writing Actions', link: '/usage/writing' },
           { text: 'Using Actions', link: '/usage/using' },
+          { text: 'Steps', link: '/usage/steps' },
         ]
       },
       {
@@ -36,29 +37,37 @@ export default defineConfig({
           { text: 'Configuration', link: '/reference/configuration' },
           { text: 'Class Interface', link: '/reference/class' },
           { text: 'Instance Interface', link: '/reference/instance' },
-          { text: 'Result Interface', link: '/reference/action-result' },
+          { text: 'Result Interface', link: '/reference/axn-result' },
+          { text: 'Async', link: '/reference/async' },
+          { text: 'FormObject', link: '/reference/form-object' },
         ]
       },
       {
-        text: 'Recipes',
+        text: 'Strategies',
         items: [
-          { text: 'Memoization', link: '/recipes/memoization' },
-          { text: 'Validating User Input', link: '/recipes/validating-user-input' },
-          { text: 'Testing Actions', link: '/recipes/testing' },
+          { text: 'Overview', link: '/strategies/index' },
+          { text: 'Transaction', link: '/strategies/transaction' },
+          { text: 'Form', link: '/strategies/form' },
+          { text: 'Client', link: '/strategies/client' },
         ]
       },
       {
-        text: 'Strategies',
+        text: 'Recipes',
         items: [
-          { text: 'Overview', link: '/strategies/index' },
-          { text: 'Transaction', link: '/strategies/transaction' },
+          { text: 'Memoization', link: '/recipes/memoization' },
+          { text: 'Validating User Input', link: '/recipes/validating-user-input' },
+          { text: 'Testing Actions', link: '/recipes/testing' },
+          { text: 'RuboCop Integration', link: '/recipes/rubocop-integration' },
+          { text: 'Formatting Context for Error Tracking', link: '/recipes/formatting-context-for-error-tracking' },
         ]
       },
       {
-        text: 'Additional Notes',
+        text: 'Advanced',
         items: [
-          { text: 'ROUGH NOTES', link: '/advanced/rough' },
+          { text: 'Profiling', link: '/advanced/profiling' },
           { text: 'Conventions', link: '/advanced/conventions' },
+          { text: 'Mountable', link: '/advanced/mountable' },
+          { text: 'Internal Notes', link: '/advanced/rough' },
         ]
       },
     ],

data/docs/advanced/conventions.md

@@ -12,7 +12,7 @@ These conventions are still in flux as the library is solidified and we gain mor
 
 ## Organizing Actions (Rails)
 
-You _can_ `include Action` into _any_ Ruby class, but to keep track of things we've found it helpful to:
+You _can_ `include Axn` into _any_ Ruby class, but to keep track of things we've found it helpful to:
 
   * Create a new `app/actions` folder for our actions
   * Name them `Actions::[DOMAIN]::[VERB]` where `[DOMAIN]` is a (possibly nested) identifier and `[VERB]` is the action to be taken.
@@ -26,13 +26,13 @@ For us, we've found the maintenance benefits of knowing roughly how the class wi
 ## Naming conventions
 
 ### The responsible user
-When tracking _who_ is responsible for the action being taken, one option is to inject it globally via `Current.user` (see: [Current Attributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html)), but that only works if you're _sure_ you're never going to want to enqueue the job on a background processor.
+When tracking _who_ is responsible for the action being taken, one option is to inject it globally via `Current.user` (see: [Current Attributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html)), but that only works if you're _sure_ you're never going to want to execute the action asynchronously on a background processor.
 
 More generally, we've adopted the convention of passing in the responsible user as `actor`:
 
   ```ruby
   class Foo
-    include Action
+    include Axn
     expects :actor, type: User # [!code focus]
   end
   ```