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

data/lib/axn/mountable/mounting_strategies/step.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    class MountingStrategies
+      module Step
+        include Base
+        extend self # rubocop:disable Style/ModuleFunction -- module_function breaks inheritance
+
+        def default_inherit_mode = :none
+
+        module DSL
+          def steps(*steps)
+            Array(steps).compact.each do |step_class|
+              next unless step_class.is_a?(Class)
+              raise ArgumentError, "Step #{step_class} must include Axn module" if !step_class.included_modules.include?(::Axn) && !step_class < ::Axn
+
+              num_steps = _mounted_axn_descriptors.count { |descriptor| descriptor.mount_strategy.key == :step }
+              step("Step #{num_steps + 1}", step_class)
+            end
+          end
+
+          def step(name, axn_klass = nil, error_prefix: nil, inherit: MountingStrategies::Step.default_inherit_mode, **, &)
+            # Steps default to :none - they are isolated units of work
+            Helpers::Mounter.mount_via_strategy(
+              target: self,
+              as: :step,
+              name:,
+              axn_klass:,
+              error_prefix:,
+              inherit:,
+              **,
+              &
+            )
+          end
+        end
+
+        def strategy_specific_kwargs = super + [:error_prefix]
+
+        def mount_to_target(descriptor:, target:)
+          error_prefix = descriptor.options[:error_prefix] || "#{descriptor.name}: "
+          axn_klass = descriptor.mounted_axn_for(target:)
+
+          target.error from: axn_klass do |e|
+            "#{error_prefix}#{e.message}"
+          end
+
+          # Only define #call method once
+          return if target.instance_variable_defined?(:@_axn_call_method_defined_for_steps)
+
+          target.define_method(:call) do
+            step_descriptors = self.class._mounted_axn_descriptors.select { |d| d.mount_strategy.key == :step }
+
+            step_descriptors.each do |step_descriptor|
+              axn = step_descriptor.mounted_axn_for(target:)
+              step_result = axn.call!(**@__context.__combined_data)
+
+              # Extract exposed fields from step result and update exposed_data
+              step_result.declared_fields.each do |field|
+                @__context.exposed_data[field] = step_result.public_send(field)
+              end
+            end
+          end
+          target.instance_variable_set(:@_axn_call_method_defined_for_steps, true)
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/mounting_strategies.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "axn/internal/registry"
+
+module Axn
+  module Mountable
+    class MountingTypeNotFound < Axn::Internal::Registry::NotFound; end
+    class DuplicateMountingTypeError < Axn::Internal::Registry::DuplicateError; end
+
+    class MountingStrategies < Axn::Internal::Registry
+      class << self
+        def registry_directory = __dir__
+
+        private
+
+        def item_type = "Mounting Type"
+        def not_found_error_class = MountingTypeNotFound
+        def duplicate_error_class = DuplicateMountingTypeError
+
+        def select_constants_to_load(constants)
+          # Select modules that are not the Base module
+          constants.select do |const|
+            const.is_a?(Module) && const != Base
+          end
+        end
+      end
+    end
+
+    # Trigger registry loading to ensure mounting strategies are available
+    MountingStrategies.all
+  end
+end

data/lib/axn/mountable.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "axn/mountable/inherit_profiles"
+require "axn/mountable/mounting_strategies"
+require "axn/mountable/descriptor"
+require "axn/mountable/helpers/validator"
+require "axn/mountable/helpers/class_builder"
+require "axn/mountable/helpers/namespace_manager"
+require "axn/mountable/helpers/mounter"
+
+module Axn
+  # Mountable provides functionality for mounting actions to classes
+  #
+  # ## Inheritance Behavior
+  #
+  # Mounted actions inherit features from their target class in different ways depending on the
+  # mounting strategy. Each strategy has sensible defaults, but you can customize inheritance
+  # behavior using the `inherit` parameter.
+  #
+  # ### Default Inheritance Modes
+  #
+  # - `mount_axn` and `mount_axn_method`: `:lifecycle` - Inherits hooks, callbacks, messages, and async config (but not fields)
+  # - `step`: `:none` - Completely independent to avoid conflicts
+  #
+  # ### Inheritance Profiles
+  #
+  # - `:lifecycle` - Inherits everything except fields (hooks, callbacks, messages, async config)
+  # - `:async_only` - Only inherits async configuration
+  # - `:none` - Completely standalone with no inheritance
+  #
+  # You can also use a hash for granular control:
+  #   `inherit: { fields: false, hooks: true, callbacks: false, messages: true, async: true }`
+  #
+  # Available hash keys: `:fields`, `:hooks`, `:callbacks`, `:messages`, `:async`
+  #
+  # @example Default inheritance behavior
+  #   class MyClass
+  #     include Axn
+  #
+  #     before :log_start
+  #     on_success :track_success
+  #     async :sidekiq
+  #   end
+  #
+  #   # mount_axn uses :lifecycle (inherits hooks, callbacks, messages, async)
+  #   MyClass.mount_axn :my_action do
+  #     # Will run log_start before and track_success after
+  #   end
+  #
+  #   # step uses :none (completely independent)
+  #   MyClass.step :my_step do
+  #     # Will NOT run log_start or track_success
+  #   end
+  #
+  # @example Custom inheritance control
+  #   # Override step default to inherit lifecycle
+  #   MyClass.step :my_step, inherit: :lifecycle do
+  #     # Will now run hooks and callbacks
+  #   end
+  #
+  #   # Use granular control
+  #   MyClass.mount_axn :my_action, inherit: { hooks: true, callbacks: false } do
+  #     # Will run hooks but not callbacks
+  #   end
+  module Mountable
+    extend ActiveSupport::Concern
+
+    def self.included(base)
+      base.class_eval do
+        class_attribute :_mounted_axn_descriptors, default: []
+
+        # Eagerly create action class constants for inherited descriptors
+        # (e.g. allow TeamsharesAPI::Company::Axns::Get.call to work *without* having to
+        # call TeamsharesAPI::Company.get! first)
+        def self.inherited(subclass)
+          super
+
+          # Only process if we have inherited descriptors from parent
+          return unless _mounted_axn_descriptors.any?
+
+          # Skip if subclass doesn't respond to _mounted_axn_descriptors
+          # This prevents recursion when creating action classes that inherit from target
+          return unless subclass.respond_to?(:_mounted_axn_descriptors)
+
+          # Skip if we're currently creating an action class (prevent infinite recursion)
+          # This is necessary because Axn::Factory.build creates classes that inherit from
+          # Axn (which includes Axn::Mountable), triggering inherited callbacks during
+          # action class creation.
+          superclass = subclass.superclass
+          creating_for = superclass&.instance_variable_get(:@_axn_creating_action_class_for)
+          return if creating_for
+
+          # Skip if this is an action class being created (they're in the Axns namespace)
+          # Action classes have names like "ParentClass::Axns::ActionName"
+          subclass_name = subclass.name
+          return if subclass_name&.include?("::Axns::")
+
+          # Eagerly create constants for all inherited descriptors
+          # mounted_axn_for will ensure namespace exists and create the constant
+          # If a child overrides, the new descriptor will replace the constant
+          _mounted_axn_descriptors.each do |descriptor|
+            # This will create the constant if it doesn't exist
+            descriptor.mounted_axn_for(target: subclass)
+            # Also define namespace methods on the child's namespace
+            # This ensures TeamsharesAPI::Company::Axns.get works even though
+            # the descriptor was originally mounted on TeamsharesAPI::Base
+            # We use define_namespace_methods instead of mount_to_namespace to
+            # avoid re-registering the constant (which is already created above)
+            descriptor.mount_strategy.define_namespace_methods(descriptor:, target: subclass)
+          end
+        end
+      end
+
+      MountingStrategies.all.each do |(_name, klass)|
+        base.extend klass::DSL if klass.const_defined?(:DSL)
+      end
+    end
+  end
+end

data/lib/axn/rails/engine.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Only define the Engine if Rails is available
+if defined?(Rails) && Rails.const_defined?(:Engine)
+  module Axn
+    module RailsIntegration
+      class Engine < Rails::Engine
+        # Set a custom engine name that's more concise than the module path
+        engine_name "axn_rails"
+
+        # This engine is automatically loaded when AXN is used in a Rails context
+        # It ensures proper initialization and integration with Rails
+
+        # The engine is intentionally minimal - AXN is designed to work
+        # as a standalone library that can be used in any Ruby context
+
+        # However, when used alongside Rails, we ensure that the app/actions
+        # directory is automatically added to the autoloader so that Rails can
+        # automatically load the actions.
+        initializer "axn.add_app_actions_to_autoload", after: :load_config_initializers do |app|
+          actions_path = app.root.join("app/actions")
+
+          # Only add if the directory exists
+          next unless File.directory?(actions_path)
+
+          # Use modern Rails autoloader API (Rails 7.2+)
+          # Namespace is configurable via Axn.config.rails.app_actions_autoload_namespace
+          autoload_namespace = Axn.config.rails.app_actions_autoload_namespace
+
+          if autoload_namespace
+            # Create the namespace module if it doesn't exist
+            namespace = Object.const_get(autoload_namespace) if Object.const_defined?(autoload_namespace)
+            unless namespace
+              namespace = Module.new
+              Object.const_set(autoload_namespace, namespace)
+            end
+            Rails.autoloaders.main.push_dir(actions_path, namespace:)
+          else
+            # No namespace - load directly
+            Rails.autoloaders.main.push_dir(actions_path)
+          end
+        end
+
+        # Register the generator
+        generators do
+          require_relative "generators/axn_generator"
+        end
+      end
+    end
+  end
+end

data/lib/axn/rails/generators/axn_generator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Axn
+  module RailsIntegration
+    module Generators
+      class AxnGenerator < Rails::Generators::NamedBase
+        namespace "axn"
+        source_root File.expand_path("templates", __dir__)
+
+        argument :expectations, type: :array, default: [], banner: "expectation1 expectation2 ..."
+
+        def create_action_file
+          template "action.rb.erb", "app/actions/#{file_path}.rb"
+        end
+
+        def create_spec_file
+          return unless spec_generation_enabled?
+
+          template "action_spec.rb.erb", "spec/actions/#{file_path}_spec.rb"
+        end
+
+        private
+
+        def class_name
+          @class_name ||= name.camelize
+        end
+
+        def file_path
+          @file_path ||= begin
+            path = name.underscore
+            # Strip the configured autoload namespace prefix if present
+            # e.g., if namespace is "Actions" and name is "Actions::Slack",
+            # strip "Actions::" to get "slack" instead of "actions/slack"
+            autoload_namespace = configured_autoload_namespace
+            if autoload_namespace && path.start_with?("#{autoload_namespace.underscore}/")
+              path.sub(%r{\A#{Regexp.escape(autoload_namespace.underscore)}/}, "")
+            else
+              path
+            end
+          end
+        end
+
+        def configured_autoload_namespace
+          return nil unless defined?(Axn) && Axn.config.rails.app_actions_autoload_namespace
+
+          namespace = Axn.config.rails.app_actions_autoload_namespace
+          namespace&.to_s
+        end
+
+        def expectations_with_types
+          expectations.map { |exp| { name: exp, type: "String" } }
+        end
+
+        def spec_generation_enabled?
+          return false unless rspec_available?
+          return false if spec_generation_skipped?
+
+          true
+        end
+
+        def rspec_available?
+          defined?(RSpec)
+        end
+
+        def spec_generation_skipped?
+          return false unless defined?(Rails) && Rails.application&.config&.generators
+
+          generators_config = Rails.application.config.generators
+
+          # Check individual boolean flags (modern style)
+          return true if generators_config.respond_to?(:test_framework) &&
+                         generators_config.test_framework == false
+
+          # Check for specific spec-related flags
+          spec_flags = %w[specs axn_specs]
+          spec_flags.each do |flag|
+            return true if generators_config.respond_to?(flag) &&
+                           generators_config.public_send(flag) == false
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/axn/rails/generators/templates/action.rb.erb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class <%= class_name %>
+  include Axn
+<% if expectations.any? -%>
+
+<% expectations.each do |expectation| -%>
+  expects :<%= expectation %>
+<% end -%>
+
+<% else -%>
+
+<% end -%>
+  def call
+    # TODO: Implement logic
+  end
+end

data/lib/axn/rails/generators/templates/action_spec.rb.erb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe <%= class_name %> do
+<% if expectations.any? -%>
+<% expectations.each do |expectation| -%>
+  let(:<%= expectation %>) { "<%= expectation %>" }
+<% end -%>
+
+<% end -%>
+  describe ".call" do
+    subject(:result) { described_class.call(<%= expectations.any? ? expectations.map { |exp| "#{exp}:" }.join(", ") : "" %>) }
+
+    it "executes successfully" do
+      expect(result).to be_ok
+    end
+<% if expectations.any? -%>
+
+    it "TODO: replace with a meaningful failure case" do
+      result = described_class.call
+      expect(result).not_to be_ok
+      expect(result.error).to eq("Something went wrong")
+    end
+<% end -%>
+  end
+end

data/lib/{action → axn}/result.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
-require "action/core/context/facade"
-require "action/core/context/facade_inspector"
+require "axn/core/context/facade"
+require "axn/core/context/facade_inspector"
 
-module Action
+module Axn
   # Outbound / External ContextFacade
   class Result < ContextFacade
     # For ease of mocking return results in tests
     class << self
       def ok(msg = nil, **exposures)
-        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+        exposes = exposures.keys.to_h { |key| [key, { optional: true }] }
 
-        Axn::Factory.build(exposes:, success: msg) do
+        Axn::Factory.build(exposes:, success: msg, log_calls: false, log_errors: false) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -19,9 +19,9 @@ module Action
       end
 
       def error(msg = nil, **exposures, &block)
-        exposes = exposures.keys.to_h { |key| [key, { allow_blank: true }] }
+        exposes = exposures.keys.to_h { |key| [key, { optional: true }] }
 
-        Axn::Factory.build(exposes:, error: msg) do
+        Axn::Factory.build(exposes:, error: msg, log_calls: false, log_errors: false) do
           exposures.each do |key, value|
             expose(key, value)
           end
@@ -40,7 +40,7 @@ module Action
     end
 
     # External interface
-    delegate :ok?, :exception, :elapsed_time, to: :context
+    delegate :ok?, :exception, :elapsed_time, :finalized?, to: :context
 
     def error
       return if ok?
@@ -64,7 +64,7 @@ module Action
     ].freeze
 
     def outcome
-      label = if exception.is_a?(Action::Failure)
+      label = if exception.is_a?(Axn::Failure)
                 OUTCOME_FAILURE
               elsif exception
                 OUTCOME_EXCEPTION
@@ -79,15 +79,34 @@ module Action
     # TODO: exposed for errors :from support, but should be private if possible
     def __action__ = @action
 
+    # Enable pattern matching support for Ruby 3+
+    def deconstruct_keys(keys)
+      attrs = {
+        ok: ok?,
+        success:,
+        error:,
+        message:,
+        outcome: outcome.to_sym,
+        finalized: finalized?,
+      }
+
+      # Add all exposed data
+      attrs.merge!(@context.exposed_data)
+
+      # Return filtered attributes if keys specified
+      keys ? attrs.slice(*keys) : attrs
+    end
+
     private
 
     def _context_data_source = @context.exposed_data
 
-    # TODO: hook for adding early-return success at some point
-    def _user_provided_success_message = nil
+    def _user_provided_success_message
+      @context.__early_completion_message.presence
+    end
 
     def _user_provided_error_message
-      return unless exception.is_a?(Action::Failure)
+      return unless exception.is_a?(Axn::Failure)
       return if exception.default_message?
       return if exception.cause # We raised this ourselves from nesting
 
@@ -103,7 +122,7 @@ module Action
             exposes :#{method_name}
         MSG
 
-        raise Action::ContractViolation::MethodNotAllowed, msg
+        raise Axn::ContractViolation::MethodNotAllowed, msg
       end
 
       super

data/lib/axn/strategies/form.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Axn
+  class Strategies
+    module Form
+      # @param expect [Symbol] the attribute name to expect in the context (e.g. :params)
+      # @param expose [Symbol] the attribute name to expose in the context (e.g. :form)
+      # @param type [Class, String] the form class to use, or a string constant path
+      # @param inject [Array<Symbol>] optional additional attributes to include in the form (e.g. [:user, :company])
+      # @yield block to define the form class when type is a string and the constant doesn't exist
+      def self.configure(expect: :params, expose: :form, type: nil, inject: nil, &block)
+        expect ||= :"#{expose.to_s.delete_suffix('_form')}_params"
+
+        # Aliasing to avoid shadowing/any confusion
+        expect_attr = expect
+        expose_attr = expose
+
+        Module.new do
+          extend ActiveSupport::Concern
+
+          included do
+            raise ArgumentError, "form strategy: must pass explicit :type parameter to `use :form` when applying to anonymous classes" if type.nil? && name.nil?
+
+            resolved_type = Axn::Strategies::Form.resolve_type(type, expose_attr, name, &block)
+
+            raise ArgumentError, "form strategy: #{resolved_type} must implement `valid?`" unless resolved_type.method_defined?(:valid?)
+
+            expects expect_attr, type: :params
+            exposes(expose_attr, type: resolved_type)
+
+            define_method expose_attr do
+              attrs_for_form = public_send(expect_attr)&.dup || {}
+
+              Array(inject).each do |ctx|
+                attrs_for_form[ctx] = public_send(ctx)
+              end
+
+              resolved_type.new(attrs_for_form)
+            end
+            memo expose_attr
+
+            before do
+              expose expose_attr => public_send(expose_attr)
+              fail! unless public_send(expose_attr).valid?
+            end
+          end
+        end
+      end
+
+      # Resolve the form type from the given parameters
+      # @param type [Class, String, nil] the form class, constant path, or nil for auto-detection
+      # @param expose_attr [Symbol] the attribute name to expose (used for auto-detection)
+      # @param action_name [String, nil] the name of the action class (used for auto-detection)
+      # @yield block to define the form class when type is a string and the constant doesn't exist
+      # @return [Class] the resolved form class
+      def self.resolve_type(type, expose_attr, action_name, &)
+        type ||= "#{action_name}::#{expose_attr.to_s.classify}"
+
+        if type.is_a?(Class)
+          raise ArgumentError, "form strategy: cannot provide block when type is a Class" if block_given?
+
+          return type
+        end
+
+        type.constantize.tap do
+          raise ArgumentError, "form strategy: cannot provide block when type constant #{type} already exists" if block_given?
+        end
+      rescue NameError
+        # Constant doesn't exist
+        raise ArgumentError, "form strategy: type constant #{type} does not exist and no block provided to define it" unless block_given?
+
+        # Create the class using the block, inheriting from Axn::FormObject
+        Class.new(Axn::FormObject).tap do |klass|
+          klass.class_eval(&)
+          assign_constant(type, klass)
+        end
+      end
+
+      # Helper method to assign a class to a constant path
+      # @param constant_path [String] the full constant path (e.g., "CreateUser::Form")
+      # @param klass [Class] the class to assign
+      def self.assign_constant(constant_path, klass)
+        parts = constant_path.split("::")
+        constant_name = parts.pop
+        parent_path = parts.join("::")
+
+        if parent_path.empty?
+          # Top-level constant
+          Object.const_set(constant_name, klass)
+        else
+          # Nested constant - ensure parent namespace exists
+          parent = parent_path.constantize
+          parent.const_set(constant_name, klass)
+        end
+      end
+    end
+  end
+end

data/lib/axn/strategies/transaction.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Axn
+  class Strategies
+    module Transaction
+      extend ActiveSupport::Concern
+
+      included do
+        raise NotImplementedError, "Transaction strategy requires ActiveRecord" unless defined?(ActiveRecord)
+
+        around do |hooked|
+          early_completion = nil
+          ActiveRecord::Base.transaction do
+            hooked.call
+          rescue Axn::Internal::EarlyCompletion => e
+            # EarlyCompletion is not an error - it's a control flow mechanism
+            # Store it to re-raise after transaction commits
+            early_completion = e
+          end
+          # Re-raise EarlyCompletion after transaction commits successfully
+          raise early_completion if early_completion
+        end
+      end
+    end
+  end
+end

data/lib/axn/strategies.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "axn/internal/registry"
+
+module Axn
+  class StrategyNotFound < Axn::Internal::Registry::NotFound; end
+  class DuplicateStrategyError < Axn::Internal::Registry::DuplicateError; end
+
+  class Strategies < Axn::Internal::Registry
+    class << self
+      def registry_directory = __dir__
+
+      private
+
+      def item_type = "Strategy"
+      def not_found_error_class = StrategyNotFound
+      def duplicate_error_class = DuplicateStrategyError
+    end
+  end
+end

data/lib/axn/testing/spec_helpers.rb

@@ -3,19 +3,17 @@
 module Axn
   module Testing
     module SpecHelpers
-      def build_action(&block)
-        action = Class.new.send(:include, Action)
+      def build_axn(&block)
+        action = Class.new.send(:include, Axn)
         action.class_eval(&block) if block
         action
       end
-
-      def build_axn(**, &)
-        Axn::Factory.build(**, &)
-      end
     end
   end
 end
 
-RSpec.configure do |config|
-  config.include Axn::Testing::SpecHelpers
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include Axn::Testing::SpecHelpers
+  end
 end