servactory 2.16.0 → 3.0.0.rc1

data/lib/servactory/stroma/hooks/hook.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Hooks
+      # Valid hook types for Hook validation.
+      VALID_HOOK_TYPES = %i[before after].freeze
+      private_constant :VALID_HOOK_TYPES
+
+      # Immutable value object representing a hook configuration.
+      #
+      # ## Purpose
+      #
+      # Defines when and where an extension module should be included
+      # relative to a registered DSL module. Hook is immutable - once
+      # created, it cannot be modified.
+      #
+      # ## Attributes
+      #
+      # @!attribute [r] type
+      #   @return [Symbol] Either :before or :after
+      # @!attribute [r] target_key
+      #   @return [Symbol] Key of the DSL module to hook into (:inputs, :actions, etc.)
+      # @!attribute [r] extension
+      #   @return [Module] The module to include at the hook point
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # hook = Servactory::Stroma::Hooks::Hook.new(
+      #   type: :before,
+      #   target_key: :actions,
+      #   extension: MyExtension
+      # )
+      # hook.before?  # => true
+      # hook.after?   # => false
+      # ```
+      #
+      # ## Immutability
+      #
+      # Hook is a Data object - frozen and immutable after creation.
+      Hook = Data.define(:type, :target_key, :extension) do
+        # Initializes a new Hook with validation.
+        #
+        # @param type [Symbol] Hook type (:before or :after)
+        # @param target_key [Symbol] Registry key to hook into
+        # @param extension [Module] Extension module to include
+        # @raise [Exceptions::InvalidHookType] If type is invalid
+        def initialize(type:, target_key:, extension:)
+          if VALID_HOOK_TYPES.exclude?(type)
+            raise Exceptions::InvalidHookType,
+                  "Invalid hook type: #{type.inspect}. Valid types: #{VALID_HOOK_TYPES.map(&:inspect).join(', ')}"
+          end
+
+          super
+        end
+
+        # Checks if this is a before hook.
+        #
+        # @return [Boolean] true if type is :before
+        def before?
+          type == :before
+        end
+
+        # Checks if this is an after hook.
+        #
+        # @return [Boolean] true if type is :after
+        def after?
+          type == :after
+        end
+      end
+    end
+  end
+end

data/lib/servactory/stroma/registry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    # Manages global registration of DSL modules for Servactory.
+    #
+    # ## Purpose
+    #
+    # Singleton registry that stores all DSL modules that will be included
+    # in service classes. Implements two-phase lifecycle: registration
+    # followed by finalization.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # # During gem initialization:
+    # Servactory::Stroma::Registry.register(:inputs, Servactory::Inputs::DSL)
+    # Servactory::Stroma::Registry.register(:outputs, Servactory::Outputs::DSL)
+    # Servactory::Stroma::Registry.finalize!
+    #
+    # # After finalization:
+    # Servactory::Stroma::Registry.keys       # => [:inputs, :outputs]
+    # Servactory::Stroma::Registry.key?(:inputs)  # => true
+    # ```
+    #
+    # ## Integration
+    #
+    # Used by Servactory::Stroma::DSL to include all registered modules in service classes.
+    # Used by Servactory::Stroma::Hooks::Factory to validate hook target keys.
+    #
+    # ## Thread Safety
+    #
+    # Registration must occur during single-threaded boot phase.
+    # After finalization, all read operations are thread-safe.
+    class Registry
+      include Singleton
+
+      class << self
+        delegate :register,
+                 :finalize!,
+                 :entries,
+                 :keys,
+                 :key?,
+                 to: :instance
+      end
+
+      def initialize
+        @entries = []
+        @finalized = false
+      end
+
+      def register(key, extension)
+        raise Exceptions::RegistryFrozen, "Registry is finalized" if @finalized
+
+        if @entries.any? { |e| e.key == key }
+          raise Exceptions::KeyAlreadyRegistered, "Key #{key.inspect} already registered"
+        end
+
+        @entries << Entry.new(key:, extension:)
+      end
+
+      def finalize!
+        return if @finalized
+
+        @entries.freeze
+        @finalized = true
+      end
+
+      def entries
+        ensure_finalized!
+        @entries
+      end
+
+      def keys
+        ensure_finalized!
+        @entries.map(&:key)
+      end
+
+      def key?(key)
+        ensure_finalized!
+        @entries.any? { |e| e.key == key }
+      end
+
+      private
+
+      def ensure_finalized!
+        return if @finalized
+
+        raise Exceptions::RegistryNotFinalized,
+              "Registry not finalized. Call Stroma::Registry.finalize! after registration."
+      end
+    end
+  end
+end

data/lib/servactory/stroma/settings/collection.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Settings
+      # Top-level hierarchical container for extension settings.
+      #
+      # ## Purpose
+      #
+      # Provides two-level hierarchical access to extension settings:
+      # registry_key -> extension_name -> setting values.
+      # Auto-vivifies RegistrySettings on first access.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # settings = Servactory::Stroma::Settings::Collection.new
+      # settings[:actions][:authorization][:method_name] = :authorize
+      # settings[:actions][:transactional][:enabled] = true
+      #
+      # settings.keys    # => [:actions]
+      # settings.empty?  # => false
+      # settings.to_h    # => { actions: { authorization: { method_name: :authorize }, ... } }
+      # ```
+      #
+      # ## Integration
+      #
+      # Stored in Servactory::Stroma::State alongside Hooks::Collection.
+      # Accessed via `stroma.settings` in service classes.
+      # Properly duplicated during class inheritance via initialize_dup.
+      class Collection
+        extend Forwardable
+
+        # @!method each
+        #   Iterates over all registry key settings.
+        #   @yield [key, settings] Each registry key and its RegistrySettings
+        # @!method keys
+        #   Returns all registry keys with settings.
+        #   @return [Array<Symbol>] List of registry keys
+        # @!method size
+        #   Returns the number of registry keys configured.
+        #   @return [Integer] Number of registry keys
+        # @!method empty?
+        #   Checks if no settings are configured.
+        #   @return [Boolean] true if empty
+        # @!method map
+        #   Maps over all registry key settings.
+        #   @yield [key, settings] Each registry key and its RegistrySettings
+        #   @return [Array] Mapped results
+        def_delegators :@storage, :each, :keys, :size, :empty?, :map
+
+        # Creates a new settings collection.
+        #
+        # @param storage [Hash] Initial storage (default: empty Hash)
+        def initialize(storage = {})
+          @storage = storage
+        end
+
+        # Creates a deep copy during inheritance.
+        #
+        # @param original [Collection] The original collection being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+        end
+
+        # Accesses or creates RegistrySettings for a registry key.
+        #
+        # Auto-vivifies a new RegistrySettings on first access.
+        #
+        # @param registry_key [Symbol] The registry key (e.g., :actions)
+        # @return [RegistrySettings] Settings for that registry key
+        #
+        # @example
+        #   settings[:actions][:authorization][:method_name] = :authorize
+        def [](registry_key)
+          @storage[registry_key.to_sym] ||= RegistrySettings.new
+        end
+
+        # Converts to a nested Hash.
+        #
+        # @return [Hash] Deep nested hash of all settings
+        def to_h
+          @storage.transform_values(&:to_h)
+        end
+      end
+    end
+  end
+end

data/lib/servactory/stroma/settings/registry_settings.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Settings
+      # Collection of Setting objects for one registry key.
+      #
+      # ## Purpose
+      #
+      # Groups extension settings by registry key (e.g., :actions).
+      # Provides auto-vivifying access to individual Setting objects.
+      # This is the middle layer in the settings hierarchy.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # settings = Servactory::Stroma::Settings::RegistrySettings.new
+      # settings[:authorization][:method_name] = :authorize
+      # settings[:transactional][:enabled] = true
+      #
+      # settings.keys   # => [:authorization, :transactional]
+      # settings.empty? # => false
+      # ```
+      #
+      # ## Integration
+      #
+      # Used by Collection as second-level container.
+      # Properly duplicated during class inheritance via initialize_dup.
+      class RegistrySettings
+        extend Forwardable
+
+        # @!method each
+        #   Iterates over all extension settings.
+        #   @yield [name, setting] Each extension name and its Setting
+        # @!method keys
+        #   Returns all extension names.
+        #   @return [Array<Symbol>] List of extension names
+        # @!method size
+        #   Returns the number of extensions configured.
+        #   @return [Integer] Number of extensions
+        # @!method empty?
+        #   Checks if no extensions are configured.
+        #   @return [Boolean] true if empty
+        # @!method map
+        #   Maps over all extension settings.
+        #   @yield [name, setting] Each extension name and its Setting
+        #   @return [Array] Mapped results
+        def_delegators :@storage, :each, :keys, :size, :empty?, :map
+
+        # Creates a new registry settings container.
+        #
+        # @param storage [Hash] Initial storage (default: empty Hash)
+        def initialize(storage = {})
+          @storage = storage
+        end
+
+        # Creates a deep copy during inheritance.
+        #
+        # @param original [RegistrySettings] The original being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+        end
+
+        # Accesses or creates a Setting for an extension.
+        #
+        # Auto-vivifies a new Setting on first access.
+        #
+        # @param extension_name [Symbol] The extension name
+        # @return [Setting] The extension's setting container
+        #
+        # @example
+        #   settings[:authorization][:method_name] = :authorize
+        def [](extension_name)
+          @storage[extension_name.to_sym] ||= Setting.new
+        end
+
+        # Converts to a nested Hash.
+        #
+        # @return [Hash] Nested hash of all settings
+        def to_h
+          @storage.transform_values(&:to_h)
+        end
+      end
+    end
+  end
+end

data/lib/servactory/stroma/settings/setting.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Settings
+      # Dynamic key-value storage for extension configuration.
+      #
+      # ## Purpose
+      #
+      # Provides a Hash-based container for storing extension-specific
+      # configuration data. Uses Forwardable delegation for consistent API.
+      # This is the leaf-level container in the settings hierarchy.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # setting = Servactory::Stroma::Settings::Setting.new
+      # setting[:method_name] = :authorize
+      # setting[:method_name]  # => :authorize
+      # setting.key?(:method_name)  # => true
+      # ```
+      #
+      # ## Integration
+      #
+      # Used by RegistrySettings to store individual extension settings.
+      # Properly duplicated during class inheritance via initialize_dup.
+      class Setting
+        extend Forwardable
+
+        # @!method [](key)
+        #   Retrieves a value by key.
+        #   @param key [Symbol] The key to look up
+        #   @return [Object, nil] The stored value or nil
+        # @!method []=(key, value)
+        #   Stores a value by key.
+        #   @param key [Symbol] The key to store under
+        #   @param value [Object] The value to store
+        # @!method key?(key)
+        #   Checks if a key exists.
+        #   @param key [Symbol] The key to check
+        #   @return [Boolean] true if key exists
+        # @!method keys
+        #   Returns all stored keys.
+        #   @return [Array<Symbol>] List of keys
+        # @!method each
+        #   Iterates over all key-value pairs.
+        #   @yield [key, value] Each stored pair
+        # @!method empty?
+        #   Checks if no values are stored.
+        #   @return [Boolean] true if empty
+        # @!method size
+        #   Returns the number of stored values.
+        #   @return [Integer] Number of entries
+        # @!method map
+        #   Maps over all key-value pairs.
+        #   @yield [key, value] Each stored pair
+        #   @return [Array] Mapped results
+        def_delegators :@data, :[], :[]=, :key?, :keys, :each, :empty?, :size, :map
+
+        # Creates a new setting container.
+        #
+        # @param data [Hash] Initial data (default: empty Hash)
+        def initialize(data = {})
+          @data = data
+        end
+
+        # Creates a deep copy during inheritance.
+        #
+        # @param original [Setting] The original setting being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @data = deep_dup(original.instance_variable_get(:@data))
+        end
+
+        # Converts to a plain Hash.
+        #
+        # @return [Hash] Deep copy of internal data
+        def to_h
+          deep_dup(@data)
+        end
+
+        # Fetches a value with optional default.
+        #
+        # @param key [Symbol] The key to fetch
+        # @param args [Array] Optional default value
+        # @yield Optional block for default value
+        # @return [Object] The fetched value or default
+        #
+        # @example
+        #   setting.fetch(:method_name, :default_method)
+        #   setting.fetch(:method_name) { :computed_default }
+        def fetch(key, *args, &block)
+          @data.fetch(key.to_sym, *args, &block)
+        end
+
+        private
+
+        # Recursively duplicates nested Hash and Array structures.
+        #
+        # @param obj [Object] The object to duplicate
+        # @return [Object] Deep copy of the object
+        def deep_dup(obj)
+          case obj
+          when Hash then obj.transform_values { |v| deep_dup(v) }
+          when Array then obj.map { |v| deep_dup(v) }
+          else obj.respond_to?(:dup) ? obj.dup : obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/stroma/state.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    # Holds the complete Stroma state for a service class.
+    #
+    # ## Purpose
+    #
+    # Central container that stores:
+    # - Hooks collection for before/after extension points
+    # - Settings collection for extension-specific configuration
+    #
+    # Each service class has its own State instance, duplicated during
+    # inheritance to ensure independent configuration.
+    #
+    # ## Usage
+    #
+    # Accessed via `stroma` method in service classes:
+    #
+    # ```ruby
+    # class MyService < ApplicationService::Base
+    #   # In ClassMethods:
+    #   stroma.hooks.before(:actions)
+    #   stroma.settings[:actions][:authorization][:method_name]
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Stored as @stroma instance variable on each service class.
+    # Duplicated in DSL.inherited to provide inheritance isolation.
+    class State
+      # @!attribute [r] hooks
+      #   @return [Hooks::Collection] The hooks collection for this class
+      # @!attribute [r] settings
+      #   @return [Settings::Collection] The settings collection for this class
+      attr_reader :hooks, :settings
+
+      # Creates a new State with empty collections.
+      def initialize
+        @hooks = Hooks::Collection.new
+        @settings = Settings::Collection.new
+      end
+
+      # Creates a deep copy during inheritance.
+      #
+      # Ensures child classes have independent hooks and settings
+      # that don't affect the parent class.
+      #
+      # @param original [State] The original state being duplicated
+      # @return [void]
+      def initialize_dup(original)
+        super
+        @hooks = original.instance_variable_get(:@hooks).dup
+        @settings = original.instance_variable_get(:@settings).dup
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/fake_type.rb

@@ -2,6 +2,29 @@
 
 module Servactory
   module TestKit
+    # Dummy class used as a type mismatch value in tests.
+    #
+    # ## Purpose
+    #
+    # FakeType is an empty class that doesn't match any expected service
+    # input types. It's used by ValidWithSubmatcher to test type validation
+    # by providing a value guaranteed to fail type checks.
+    #
+    # ## Usage
+    #
+    # Used internally by valid_with tests:
+    #
+    # ```ruby
+    # # In valid_with submatcher
+    # prepared_attributes[attribute_name] = Servactory::TestKit::FakeType.new
+    # # This triggers type validation failure
+    # ```
+    #
+    # ## Note
+    #
+    # The class is intentionally empty - its sole purpose is to be a type
+    # that doesn't match String, Integer, Hash, Array, or any other type
+    # that a service might expect.
     class FakeType; end # rubocop:disable Lint/EmptyClass
   end
 end

data/lib/servactory/test_kit/result.rb

@@ -2,7 +2,41 @@
 
 module Servactory
   module TestKit
+    # Factory for creating mock Servactory result objects.
+    #
+    # ## Purpose
+    #
+    # Provides factory methods for creating success and failure result objects
+    # in tests without actually calling a service. Used internally by the
+    # service mocking helpers to generate return values.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # # Create success result with outputs
+    # result = Servactory::TestKit::Result.as_success(
+    #   service_class: MyService,
+    #   user: user_object,
+    #   status: :active
+    # )
+    #
+    # # Create failure result with exception
+    # result = Servactory::TestKit::Result.as_failure(
+    #   service_class: MyService,
+    #   exception: Servactory::Exceptions::Failure.new(message: "Error")
+    # )
+    # ```
+    #
+    # ## Service Class Resolution
+    #
+    # When `service_class` is provided, uses that service's configured
+    # `result_class` for proper result type. Otherwise, uses the default
+    # `Servactory::Result` class.
     class Result
+      # Creates a successful mock result with given outputs.
+      #
+      # @param attributes [Hash] Output attributes and optional :service_class
+      # @return [Servactory::Result] Success result with outputs as methods
       def self.as_success(**attributes)
         service_class = attributes.delete(:service_class) || self
 
@@ -15,6 +49,10 @@ module Servactory
         end
       end
 
+      # Creates a failed mock result with given exception.
+      #
+      # @param attributes [Hash] Output attributes, :exception, and optional :service_class
+      # @return [Servactory::Result] Failure result with error accessor
       def self.as_failure(**attributes)
         service_class = attributes.delete(:service_class) || self
         exception = attributes.delete(:exception)
@@ -28,6 +66,10 @@ module Servactory
         end
       end
 
+      # Initializes result with attribute accessors.
+      #
+      # @param attributes [Hash] Output name-value pairs
+      # @return [Result] New result instance
       def initialize(attributes = {})
         attributes.each_pair do |name, value|
           servactory_service_warehouse.assign_output(name, value)
@@ -38,6 +80,9 @@ module Servactory
 
       private
 
+      # Internal warehouse for storing output values.
+      #
+      # @return [Servactory::Context::Warehouse::Setup] Warehouse instance
       def servactory_service_warehouse
         @servactory_service_warehouse ||= Servactory::Context::Warehouse::Setup.new(self)
       end