servactory 3.0.0.rc1 → 3.0.0.rc3

data/lib/servactory/stroma/exceptions/registry_not_finalized.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Exceptions
-      # Raised when accessing registry before finalization
-      #
-      # ## Purpose
-      #
-      # Indicates that the Stroma::Registry was accessed before finalize! was called.
-      # The registry must be finalized before it can be used to ensure all DSL modules
-      # are registered in the correct order.
-      #
-      # ## Usage
-      #
-      # Raised when accessing registry methods before finalization:
-      #
-      # ```ruby
-      # # Before finalize! is called
-      # Servactory::Stroma::Registry.entries
-      # # Raises: Servactory::Stroma::Exceptions::RegistryNotFinalized
-      # ```
-      #
-      # ## Integration
-      #
-      # This exception typically indicates that Servactory::DSL module was not
-      # properly loaded. Ensure servactory gem is properly required before
-      # defining service classes.
-      class RegistryNotFinalized < Base
-      end
-    end
-  end
-end

data/lib/servactory/stroma/exceptions/unknown_hook_target.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Exceptions
-      # Raised when using an invalid hook target key
-      #
-      # ## Purpose
-      #
-      # Indicates that an unknown key was used as a hook target in the
-      # extensions block. Only registered DSL module keys can be used
-      # as hook targets.
-      #
-      # ## Usage
-      #
-      # Raised when using an invalid key in extensions block:
-      #
-      # ```ruby
-      # class ApplicationService::Base
-      #   include Servactory::DSL
-      #
-      #   extensions do
-      #     before :unknown_key, SomeModule
-      #     # Raises: Servactory::Stroma::Exceptions::UnknownHookTarget
-      #   end
-      # end
-      # ```
-      #
-      # ## Integration
-      #
-      # Valid hook target keys are determined by registered DSL modules:
-      # :configuration, :info, :context, :inputs, :internals, :outputs, :actions
-      #
-      # Check Servactory::Stroma::Registry.keys for the list of valid targets.
-      class UnknownHookTarget < Base
-      end
-    end
-  end
-end

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

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Hooks
-      # Applies registered hooks to a target class.
-      #
-      # ## Purpose
-      #
-      # Iterates through all registered DSL modules and includes corresponding
-      # before/after hooks in the target class. For each registry entry,
-      # before hooks are included first, then after hooks.
-      #
-      # ## Usage
-      #
-      # ```ruby
-      # applier = Servactory::Stroma::Hooks::Applier.new(ChildService, hooks)
-      # applier.apply!
-      # # ChildService now includes all hook modules
-      # ```
-      #
-      # ## Integration
-      #
-      # Called by Servactory::Stroma::DSL.inherited after duplicating
-      # parent's configuration. Uses Registry.entries to determine
-      # hook application order.
-      class Applier
-        # Creates a new applier for applying hooks to a class.
-        #
-        # @param target_class [Class] The class to apply hooks to
-        # @param hooks [Collection] The hooks collection to apply
-        def initialize(target_class, hooks)
-          @target_class = target_class
-          @hooks = hooks
-        end
-
-        # Applies all registered hooks to the target class.
-        #
-        # For each registry entry, includes before hooks first,
-        # then after hooks. Does nothing if hooks collection is empty.
-        #
-        # @return [void]
-        #
-        # @example
-        #   applier.apply!
-        #   # Target class now includes all extension modules
-        def apply!
-          return if @hooks.empty?
-
-          Registry.entries.each do |entry|
-            @hooks.before(entry.key).each do |hook|
-              @target_class.include(hook.extension)
-            end
-
-            @hooks.after(entry.key).each do |hook|
-              @target_class.include(hook.extension)
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Hooks
-      # Mutable collection manager for Hook objects.
-      #
-      # ## Purpose
-      #
-      # Stores Hook objects and provides query methods to retrieve hooks
-      # by type and target key. Supports proper duplication during class
-      # inheritance to ensure configuration isolation.
-      #
-      # ## Usage
-      #
-      # ```ruby
-      # hooks = Servactory::Stroma::Hooks::Collection.new
-      # hooks.add(:before, :actions, MyModule)
-      # hooks.add(:after, :actions, AnotherModule)
-      #
-      # hooks.before(:actions)  # => [Hook(...)]
-      # hooks.after(:actions)   # => [Hook(...)]
-      # hooks.empty?            # => false
-      # hooks.size              # => 2
-      # ```
-      #
-      # ## Integration
-      #
-      # Stored in Servactory::Stroma::State and used by
-      # Servactory::Stroma::Hooks::Applier to apply hooks to classes.
-      # Properly duplicated during class inheritance via initialize_dup.
-      class Collection
-        extend Forwardable
-
-        # @!method each
-        #   Iterates over all hooks in the collection.
-        #   @yield [Hook] Each hook in the collection
-        # @!method map
-        #   Maps over all hooks in the collection.
-        #   @yield [Hook] Each hook in the collection
-        #   @return [Array] Mapped results
-        # @!method size
-        #   Returns the number of hooks in the collection.
-        #   @return [Integer] Number of hooks
-        # @!method empty?
-        #   Checks if the collection is empty.
-        #   @return [Boolean] true if no hooks registered
-        def_delegators :@collection, :each, :map, :size, :empty?
-
-        # Creates a new hooks collection.
-        #
-        # @param collection [Set] Initial collection of hooks (default: empty Set)
-        def initialize(collection = Set.new)
-          @collection = collection
-        end
-
-        # Creates a deep copy during inheritance.
-        #
-        # @param original [Collection] The original collection being duplicated
-        # @return [void]
-        def initialize_dup(original)
-          super
-          @collection = original.instance_variable_get(:@collection).dup
-        end
-
-        # Adds a new hook to the collection.
-        #
-        # @param type [Symbol] Hook type (:before or :after)
-        # @param target_key [Symbol] Registry key to hook into
-        # @param extension [Module] Extension module to include
-        # @return [Set] The updated collection
-        #
-        # @example
-        #   hooks.add(:before, :actions, ValidationModule)
-        def add(type, target_key, extension)
-          @collection << Hook.new(type:, target_key:, extension:)
-        end
-
-        # Returns all before hooks for a given key.
-        #
-        # @param key [Symbol] The target key to filter by
-        # @return [Array<Hook>] Hooks that run before the target
-        #
-        # @example
-        #   hooks.before(:actions)  # => [Hook(type: :before, ...)]
-        def before(key)
-          @collection.select { |hook| hook.before? && hook.target_key == key }
-        end
-
-        # Returns all after hooks for a given key.
-        #
-        # @param key [Symbol] The target key to filter by
-        # @return [Array<Hook>] Hooks that run after the target
-        #
-        # @example
-        #   hooks.after(:actions)  # => [Hook(type: :after, ...)]
-        def after(key)
-          @collection.select { |hook| hook.after? && hook.target_key == key }
-        end
-      end
-    end
-  end
-end

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

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-module Servactory
-  module Stroma
-    module Hooks
-      # DSL interface for registering hooks in extensions block.
-      #
-      # ## Purpose
-      #
-      # Provides the `before` and `after` methods used within the extensions
-      # block to register hooks. Validates that target keys exist in Registry
-      # before adding hooks.
-      #
-      # ## Usage
-      #
-      # ```ruby
-      # class ApplicationService::Base < Servactory::Base
-      #   extensions do
-      #     before :actions, ValidationModule
-      #     after :outputs, LoggingModule
-      #   end
-      # end
-      # ```
-      #
-      # ## Integration
-      #
-      # Created by DSL.extensions method and receives instance_eval of the block.
-      # Validates keys against Registry.keys and raises UnknownHookTarget
-      # for invalid keys.
-      class Factory
-        # Creates a new factory for registering hooks.
-        #
-        # @param hooks [Collection] The hooks collection to add to
-        def initialize(hooks)
-          @hooks = hooks
-        end
-
-        # Registers one or more before hooks for a target key.
-        #
-        # @param key [Symbol] The registry key to hook before
-        # @param extensions [Array<Module>] Extension modules to include
-        # @raise [Exceptions::UnknownHookTarget] If key is not registered
-        #
-        # @example
-        #   before :actions, ValidationModule, AuthorizationModule
-        def before(key, *extensions)
-          validate_key!(key)
-          extensions.each { |extension| @hooks.add(:before, key, extension) }
-        end
-
-        # Registers one or more after hooks for a target key.
-        #
-        # @param key [Symbol] The registry key to hook after
-        # @param extensions [Array<Module>] Extension modules to include
-        # @raise [Exceptions::UnknownHookTarget] If key is not registered
-        #
-        # @example
-        #   after :outputs, LoggingModule, AuditModule
-        def after(key, *extensions)
-          validate_key!(key)
-          extensions.each { |extension| @hooks.add(:after, key, extension) }
-        end
-
-        private
-
-        # Validates that the key exists in the Registry.
-        #
-        # @param key [Symbol] The key to validate
-        # @raise [Exceptions::UnknownHookTarget] If key is not registered
-        def validate_key!(key)
-          return if Registry.key?(key)
-
-          raise Exceptions::UnknownHookTarget,
-                "Unknown hook target: #{key.inspect}. " \
-                "Valid keys: #{Registry.keys.map(&:inspect).join(', ')}"
-        end
-      end
-    end
-  end
-end

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

@@ -1,74 +0,0 @@
-# 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

@@ -1,94 +0,0 @@
-# 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

@@ -1,90 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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