servactory 3.0.0.rc1 → 3.0.0.rc2

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

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

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

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