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

data/lib/axn/mountable/helpers/class_builder.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "axn/mountable/inherit_profiles"
+require "axn/exceptions"
+
+module Axn
+  module Mountable
+    module Helpers
+      # Handles building and configuring Axn action classes for mounting
+      class ClassBuilder
+        def initialize(descriptor)
+          @descriptor = descriptor
+        end
+
+        def mount(target, name)
+          namespace = Helpers::NamespaceManager.get_or_create_namespace(target)
+          return unless should_register_constant?(namespace)
+
+          build_and_configure_action_class(target, name, namespace)
+        end
+
+        def generate_constant_name(name)
+          name.to_s.parameterize(separator: "_").classify
+        end
+
+        def build_and_configure_action_class(target, name, namespace)
+          # Mark target as having an action class being created to prevent recursion
+          # This is necessary because create_superclass_for_inherit_mode may create
+          # classes that inherit from target, triggering the inherited callback
+          target.instance_variable_set(:@_axn_creating_action_class_for, target)
+          begin
+            # Pass target through to Factory.build so it can mark the superclass
+            # The superclass flag is checked by the inherited callback in mountable.rb
+            mounted_axn = build_action_class(target, _creating_action_class_for: target)
+            configure_class_name_and_constant(mounted_axn, name, namespace, target)
+            configure_axn_mounted_to(mounted_axn, target)
+            mounted_axn
+          ensure
+            target.instance_variable_set(:@_axn_creating_action_class_for, nil)
+          end
+        end
+
+        private
+
+        def build_action_class(target, _creating_action_class_for: nil) # rubocop:disable Lint/UnderscorePrefixedVariableName
+          existing_axn_klass = @descriptor.instance_variable_get(:@existing_axn_klass)
+          return existing_axn_klass if existing_axn_klass
+
+          kwargs = @descriptor.instance_variable_get(:@kwargs)
+          block = @descriptor.instance_variable_get(:@block)
+
+          # Remove axn_klass from kwargs as it's not a valid parameter for Factory.build
+          factory_kwargs = kwargs.except(:axn_klass)
+
+          unless factory_kwargs.key?(:superclass)
+            # Get inherit configuration
+            inherit_config = @descriptor.options[:inherit]
+
+            # Determine superclass based on inherit configuration
+            factory_kwargs[:superclass] = create_superclass_for_inherit_mode(target, inherit_config)
+          end
+
+          # Pass the target class through to Factory.build so it can mark the superclass
+          factory_kwargs[:_creating_action_class_for] = _creating_action_class_for
+
+          Axn::Factory.build(**factory_kwargs, &block)
+        end
+
+        def configure_class_name_and_constant(axn_klass, name, axn_namespace, target)
+          configure_class_name(axn_klass, name, axn_namespace) if name.present?
+          register_constant(axn_klass, name, axn_namespace, target) if should_register_constant?(axn_namespace)
+        end
+
+        def configure_axn_mounted_to(axn_klass, target)
+          axn_klass.define_singleton_method(:__axn_mounted_to__) { target }
+          axn_klass.define_method(:__axn_mounted_to__) { target }
+        end
+
+        def should_register_constant?(axn_namespace)
+          axn_namespace&.name&.end_with?("::Axns")
+        end
+
+        def create_superclass_for_inherit_mode(target, inherit_config)
+          # Handle module targets - convert to a base class first, then apply inherit mode
+          target = create_module_base_class(target) if target.is_a?(Module) && !target.is_a?(Class)
+
+          # Resolve inherit configuration to a hash
+          resolved_config = InheritProfiles.resolve(inherit_config)
+
+          # If nothing should be inherited, return Object
+          return Object if resolved_config.values.none?
+
+          # If everything should be inherited, return target as-is
+          return target if resolved_config.values.all?
+
+          # Otherwise, create a class with selective inheritance
+          create_class_with_selective_inheritance(target, resolved_config)
+        end
+
+        def create_module_base_class(target_module)
+          # Create a base class that includes the target module
+          # This allows the action class to inherit from a class while still having access to module methods
+          Class.new do
+            include target_module
+          end
+        end
+
+        def create_class_with_selective_inheritance(target, inherit_config)
+          # Create a class that inherits from target but selectively clears features
+          Class.new(target) do
+            # Only clear Axn-specific attributes if target includes Axn
+            if respond_to?(:internal_field_configs=)
+              # Clear fields if not inherited
+              unless inherit_config[:fields]
+                self.internal_field_configs = []
+                self.external_field_configs = []
+              end
+
+              # Clear hooks if not inherited
+              unless inherit_config[:hooks]
+                self.around_hooks = []
+                self.before_hooks = []
+                self.after_hooks = []
+              end
+
+              # Clear callbacks if not inherited
+              self._callbacks_registry = Axn::Core::Flow::Handlers::Registry.empty unless inherit_config[:callbacks]
+
+              # Clear messages if not inherited
+              self._messages_registry = Axn::Core::Flow::Handlers::Registry.empty unless inherit_config[:messages]
+
+              # Clear async config if not inherited (nil = use Axn.config defaults)
+              unless inherit_config[:async]
+                self._async_adapter = nil
+                self._async_config = nil
+                self._async_config_block = nil
+              end
+            end
+
+            # NOTE: Strategies are always inherited as they're mixed in via `include` and become
+            # part of the ancestry chain. This cannot be controlled via the inherit configuration.
+          end
+        end
+
+        def configure_class_name(axn_klass, name, axn_namespace)
+          class_name = name.to_s.classify
+
+          axn_klass.define_singleton_method(:name) do
+            # Evaluate namespace name dynamically when the method is called
+            current_namespace_name = axn_namespace&.name
+
+            if current_namespace_name&.end_with?("::Axns")
+              # We're already in a namespace, just add the method name
+              "#{current_namespace_name}::#{class_name}"
+            elsif current_namespace_name
+              # Create the Axns namespace
+              "#{current_namespace_name}::Axns::#{class_name}"
+            else
+              # Fallback for anonymous classes
+              "AnonymousAxn::#{class_name}"
+            end
+          end
+        end
+
+        def register_constant(axn_klass, name, axn_namespace, target)
+          constant_name = generate_constant_name(name)
+
+          # Check if constant already exists - if so, only allow overwriting in inheritance scenarios
+          if axn_namespace.const_defined?(constant_name, false)
+            # Only allow overwriting if this is an inheritance scenario (child overriding parent)
+            # Check if the target's parent has the same method mounted (inheritance override)
+            parent = target.superclass
+            is_inheritance_override = parent.respond_to?(:_mounted_axn_descriptors) &&
+                                      parent._mounted_axn_descriptors.any? { |d| d.name.to_s == name.to_s }
+
+            # If it's not an inheritance override, this is a same-class collision
+            # Raise an error here for clarity, rather than silently skipping and failing later
+            # Use the same error message format as mount_method for consistency
+            unless is_inheritance_override
+              method_name = "#{name}!"
+              strategy_name = @descriptor.mount_strategy.name.split("::").last
+              raise Axn::Mountable::MountingError,
+                    "#{strategy_name} unable to attach -- method '#{method_name}' is already taken"
+            end
+          end
+
+          # Set the constant (either it doesn't exist, or it's an inheritance override)
+          axn_namespace.const_set(constant_name, axn_klass)
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/helpers/mounter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "axn/mountable/descriptor"
+
+module Axn
+  module Mountable
+    module Helpers
+      # Helper class for mounting actions via strategies
+      class Mounter
+        # Mount an action using the specified strategy
+        #
+        # @param target [Class] The target class to mount the action to
+        # @param as [Symbol] The strategy to use (:axn, :method, :step, :enqueue_all)
+        # @param name [Symbol] The name of the action
+        # @param axn_klass [Class, nil] Optional existing action class
+        # @param kwargs [Hash] Additional strategy-specific options
+        # @param block [Proc] The action block
+        def self.mount_via_strategy(
+          target:,
+          as: :axn,
+          name: nil,
+          axn_klass: nil,
+          **kwargs,
+          &block
+        )
+          descriptor = Descriptor.new(name:, axn_klass:, as:, block:, kwargs:)
+          target._mounted_axn_descriptors += [descriptor]
+          descriptor.mount(target:)
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/helpers/namespace_manager.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    module Helpers
+      # Handles namespace management for mounting
+      module NamespaceManager
+        extend self
+
+        def get_or_create_namespace(target)
+          # Check if :Axns is defined directly on this class (not inherited)
+          if target.const_defined?(:Axns, false)
+            axn_class = target.const_get(:Axns)
+            return axn_class if axn_class.is_a?(Class)
+          end
+
+          # Create a fresh namespace class for this target
+          create_namespace_class(target).tap do |namespace_class|
+            target.const_set(:Axns, namespace_class) unless target.const_defined?(:Axns, false)
+          end
+        end
+
+        private
+
+        def create_namespace_class(client_class)
+          Class.new do
+            define_singleton_method(:__axn_mounted_to__) { client_class }
+
+            define_singleton_method(:name) do
+              client_name = client_class.name.presence || "AnonymousClient_#{client_class.object_id}"
+              "#{client_name}::Axns"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/helpers/validator.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    module Helpers
+      # Handles validation logic for Descriptor
+      class Validator
+        def initialize(descriptor)
+          @descriptor = descriptor
+        end
+
+        def validate!
+          validate_name!
+          validate_axn_class_or_block!
+          validate_method_name!(@descriptor.name.to_s)
+          validate_superclass_and_inherit_conflict!
+
+          if @descriptor.existing_axn_klass
+            validate_existing_axn_class!
+          elsif @descriptor.block.present?
+            validate_callable!(@descriptor.block)
+          end
+        end
+
+        private
+
+        def validate_name!
+          name = @descriptor.name
+          invalid!("name must be a string or symbol") unless name.is_a?(String) || name.is_a?(Symbol)
+        end
+
+        def validate_axn_class_or_block!
+          existing_axn_klass = @descriptor.existing_axn_klass
+          block = @descriptor.block
+
+          invalid!("must provide either an axn class or a block") if existing_axn_klass.nil? && block.nil?
+
+          return unless existing_axn_klass.present? && block.present?
+
+          invalid!("cannot provide both an axn class and a block")
+        end
+
+        def validate_method_name!(method_name)
+          # Check for empty names
+          invalid!("method name cannot be empty") if method_name.nil? || method_name == ""
+
+          # Check for whitespace-only names
+          invalid!("method name '#{method_name}' must be convertible to a valid constant name") if method_name.strip.empty?
+
+          # Check for names that don't start with a letter (only reject numbers)
+          invalid!("method name '#{method_name}' must be convertible to a valid constant name") if method_name.match?(/\A[0-9]/)
+
+          # Check for method suffixes that would conflict with generated methods
+          return unless method_name.match?(/[!?=]/)
+
+          invalid!("method name '#{method_name}' cannot contain method suffixes")
+        end
+
+        def validate_callable!(callable)
+          return if callable.respond_to?(:call)
+
+          invalid!("block must be callable (respond to :call)")
+        end
+
+        def validate_superclass_and_inherit_conflict!
+          # Check if user explicitly provided superclass in kwargs
+          return unless @descriptor.kwargs.key?(:superclass)
+
+          # Get the inherit option value
+          inherit_option = @descriptor.options[:inherit]
+
+          # Get the default inherit value for this strategy
+          default_inherit = mount_strategy.default_inherit_mode
+
+          # If inherit was explicitly provided and differs from default, raise error
+          return if inherit_option == default_inherit
+
+          invalid!("cannot specify both 'superclass:' and 'inherit:' options - use one or the other")
+        end
+
+        def validate_existing_axn_class!
+          existing_axn_klass = @descriptor.existing_axn_klass
+
+          invalid!("axn class must be a Class") unless existing_axn_klass.is_a?(Class)
+
+          invalid!("axn class must include Axn module") unless existing_axn_klass.included_modules.include?(::Axn) || existing_axn_klass < ::Axn
+
+          # Check raw_kwargs (before preprocessing) to see if user provided any factory kwargs
+          # Exclude axn_klass and all strategy-specific kwargs
+          user_provided_kwargs = @descriptor.raw_kwargs.except(:axn_klass, *mount_strategy.strategy_specific_kwargs)
+
+          return unless user_provided_kwargs.present? && mount_strategy != MountingStrategies::Step
+
+          invalid!("was given an existing axn class and also keyword arguments - only one is allowed")
+        end
+
+        def mount_strategy
+          @descriptor.mount_strategy
+        end
+
+        def mounting_type_name
+          mount_strategy = @descriptor.mount_strategy
+          mount_strategy.name.split("::").last.underscore.to_s.humanize
+        end
+
+        def invalid!(msg)
+          raise MountingError, "#{mounting_type_name} #{msg}"
+        end
+      end
+    end
+  end
+end

data/lib/axn/mountable/inherit_profiles.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    module InheritProfiles
+      # Predefined inheritance profiles for mounting strategies
+      PROFILES = {
+        # Inherits parent's lifecycle (hooks, callbacks, messages, async) but not fields
+        # Use this when the mounted action should participate in the parent's execution lifecycle
+        # but have its own independent contract
+        # NOTE: Strategies cannot be controlled - they're mixed in via `include` and become part of the ancestry
+        lifecycle: {
+          fields: false,
+          messages: true,
+          hooks: true,
+          callbacks: true,
+          async: true,
+        }.freeze,
+
+        # Only inherits async config - for utility methods like enqueue_all
+        # Use this when you need async capability but nothing else from the parent
+        async_only: {
+          fields: false,
+          messages: false,
+          hooks: false,
+          callbacks: false,
+          async: true,
+        }.freeze,
+
+        # Inherits nothing - completely standalone
+        # Use this when the mounted action should be completely independent from the parent
+        none: {
+          fields: false,
+          messages: false,
+          hooks: false,
+          callbacks: false,
+          async: false,
+        }.freeze,
+      }.freeze
+
+      # Resolve an inherit configuration to a full hash
+      # @param inherit [Symbol, Hash] The inherit configuration
+      # @return [Hash] A hash with all inheritance options set to true/false
+      def self.resolve(inherit)
+        case inherit
+        when Symbol
+          PROFILES.fetch(inherit) do
+            raise ArgumentError, "Unknown inherit profile: #{inherit.inspect}. Valid profiles: #{PROFILES.keys.join(', ')}"
+          end
+        when Hash
+          # Validate hash keys
+          invalid_keys = inherit.keys - PROFILES[:none].keys
+          raise ArgumentError, "Invalid inherit keys: #{invalid_keys.join(', ')}. Valid keys: #{PROFILES[:none].keys.join(', ')}" if invalid_keys.any?
+
+          # Merge with none profile to ensure all keys are present
+          PROFILES[:none].merge(inherit)
+        else
+          raise ArgumentError, "inherit must be a Symbol or Hash. Got: #{inherit.class}"
+        end
+      end
+
+      # Check if a specific feature should be inherited
+      # @param inherit [Symbol, Hash] The inherit configuration
+      # @param feature [Symbol] The feature to check (e.g., :hooks, :async)
+      # @return [Boolean]
+      def self.inherit?(inherit, feature)
+        resolved = resolve(inherit)
+        resolved.fetch(feature)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "axn/exceptions"
+require "axn/mountable/descriptor"
+
+module Axn
+  module Mountable
+    class MountingStrategies
+      # Base module for all attachment strategies
+      module Base
+        # Hooks for strategy modules to configure themselves
+        def preprocess_kwargs(**kwargs) = kwargs
+        def strategy_specific_kwargs = [:inherit]
+
+        def default_inherit_mode = raise ArgumentError, "Strategy modules must implement default_inherit_mode"
+
+        # The actual per-strategy mounting logic
+        def mount(descriptor:, target:)
+          mount_to_namespace(descriptor:, target:)
+          mount_to_target(descriptor:, target:)
+        end
+
+        # Mount methods directly to the target class
+        def mount_to_target(descriptor:, target:) = raise NotImplementedError, "Strategy modules must implement mount_to_target"
+
+        def key = name.split("::").last.underscore.to_sym
+
+        # Helper method to define a method on target with collision checking
+        def mount_method(target:, method_name:, &)
+          # Check if method collision should raise an error
+          # We allow overriding if this is a child class with a parent that has axn methods (inheritance scenario)
+          # Otherwise, we raise an error for same-class method collisions
+          if _should_raise_method_collision_error?(target, method_name)
+            raise MountingError, "#{name.split('::').last} unable to attach -- method '#{method_name}' is already taken"
+          end
+
+          target.define_singleton_method(method_name, &)
+        end
+
+        # Mount methods to the namespace and register the action class
+        def mount_to_namespace(descriptor:, target:)
+          define_namespace_methods(descriptor:, target:)
+          # Register the action class as a constant in the namespace
+          action_class_builder = Helpers::ClassBuilder.new(descriptor)
+          action_class_builder.mount(target, descriptor.name.to_s)
+        end
+
+        # Define namespace methods on the target's Axns namespace
+        # This is public so it can be called from the inherited callback
+        # without re-registering the constant (which is already created by mounted_axn_for)
+        def define_namespace_methods(descriptor:, target:)
+          namespace = Helpers::NamespaceManager.get_or_create_namespace(target)
+          name = descriptor.name
+          descriptor_ref = descriptor
+
+          # Mount methods that delegate to the cached action
+          namespace.define_singleton_method(name) do |**kwargs|
+            axn = descriptor_ref.mounted_axn_for(target:)
+            axn.call(**kwargs)
+          end
+
+          namespace.define_singleton_method("#{name}!") do |**kwargs|
+            axn = descriptor_ref.mounted_axn_for(target:)
+            axn.call!(**kwargs)
+          end
+
+          namespace.define_singleton_method("#{name}_async") do |**kwargs|
+            axn = descriptor_ref.mounted_axn_for(target:)
+            axn.call_async(**kwargs)
+          end
+        end
+
+        # Check if we should raise an error for method collision
+        # Returns true if method exists AND target is not overriding a parent's method (same-class collision)
+        def _should_raise_method_collision_error?(target, method_name)
+          return false unless target.respond_to?(method_name)
+
+          # Check if this is an inheritance override by seeing if the parent has the same method
+          is_inheritance_override = target.superclass&.respond_to?(method_name)
+
+          # Only raise error if it's a same-class collision (not inheritance override)
+          !is_inheritance_override
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    class MountingStrategies
+      module Axn
+        include Base
+        extend self # rubocop:disable Style/ModuleFunction -- module_function breaks inheritance
+
+        def default_inherit_mode = :lifecycle
+
+        module DSL
+          def mount_axn(name, axn_klass = nil, inherit: MountingStrategies::Axn.default_inherit_mode, **, &)
+            # mount_axn defaults to :lifecycle - participates in parent's execution lifecycle
+            Helpers::Mounter.mount_via_strategy(
+              target: self,
+              as: :axn,
+              name:,
+              axn_klass:,
+              inherit:,
+              **,
+              &
+            )
+          end
+        end
+
+        def mount_to_target(descriptor:, target:)
+          name = descriptor.name
+
+          mount_method(target:, method_name: name) do |**kwargs|
+            axn = descriptor.mounted_axn_for(target: self)
+            axn.call(**kwargs)
+          end
+
+          mount_method(target:, method_name: "#{name}!") do |**kwargs|
+            axn = descriptor.mounted_axn_for(target: self)
+            axn.call!(**kwargs)
+          end
+
+          mount_method(target:, method_name: "#{name}_async") do |**kwargs|
+            axn = descriptor.mounted_axn_for(target: self)
+            axn.call_async(**kwargs)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Axn
+  module Mountable
+    class MountingStrategies
+      module Method
+        include Base
+        extend self
+
+        def default_inherit_mode = :lifecycle
+
+        module DSL
+          def mount_axn_method(name, axn_klass = nil, inherit: MountingStrategies::Method.default_inherit_mode, **, &)
+            # mount_axn_method defaults to :lifecycle - participates in parent's execution lifecycle
+            Helpers::Mounter.mount_via_strategy(
+              target: self,
+              as: :method,
+              name:,
+              axn_klass:,
+              inherit:,
+              **,
+              &
+            )
+          end
+        end
+
+        def strategy_specific_kwargs = super + [:expose_return_as]
+
+        def preprocess_kwargs(**kwargs)
+          # Call parent preprocessing first
+          processed_kwargs = super
+
+          # Methods require a return value
+          processed_kwargs[:expose_return_as] = processed_kwargs[:expose_return_as].presence || :value
+
+          # Methods aren't capable of returning multiple values
+          if processed_kwargs[:exposes].present?
+            raise MountingError,
+                  "Methods aren't capable of exposing multiple values (will automatically expose return value instead)"
+          end
+
+          # Check for existing axn class with multiple exposed fields
+          if processed_kwargs[:axn_klass].present?
+            axn_klass = processed_kwargs[:axn_klass]
+            exposed_fields = axn_klass.external_field_configs.map(&:field)
+
+            if exposed_fields.size > 1
+              raise MountingError,
+                    "Cannot determine expose_return_as for existing axn class with multiple exposed fields: #{exposed_fields.join(', ')}. " \
+                    "Use a fresh block with mount_axn_method or ensure the axn class has exactly one exposed field."
+            end
+          end
+
+          processed_kwargs
+        end
+
+        def mount_to_target(descriptor:, target:)
+          name = descriptor.name
+
+          mount_method(target:, method_name: "#{name}!") do |**kwargs|
+            # Lazy load the action class for the current target
+            axn_klass = descriptor.mounted_axn_for(target: self)
+
+            # Determine expose_return_as by introspecting the axn class
+            exposed_fields = axn_klass.external_field_configs.map(&:field)
+            expose_return_as = exposed_fields.size == 1 ? exposed_fields.first : nil
+
+            result = axn_klass.call!(**kwargs)
+            return result if expose_return_as.nil?
+
+            result.public_send(expose_return_as)
+          end
+        end
+
+        private
+
+        def _determine_exposure_to_return(axn_klass)
+          # Introspect the axn class to determine expose_return_as
+          exposed_fields = axn_klass.external_field_configs.map(&:field)
+
+          case exposed_fields.size
+          when 0
+            nil # No exposed fields, return nil to avoid public_send
+          when 1
+            exposed_fields.first # Single field, assume it's expose_return_as
+          else
+            raise MountingError,
+                  "Cannot determine expose_return_as for existing axn class with multiple exposed fields: #{exposed_fields.join(', ')}. " \
+                  "Use a fresh block with mount_axn_method or ensure the axn class has exactly one exposed field."
+          end
+        end
+      end
+    end
+  end
+end