servactory 3.0.0 → 3.1.0.rc2

data/lib/servactory/inputs/tools/validation.rb

@@ -3,81 +3,56 @@
 module Servactory
   module Inputs
     module Tools
-      class Validation
-        def self.validate!(...)
-          new(...).validate!
-        end
-
-        def initialize(context, collection_of_inputs)
-          @context = context
-          @collection_of_inputs = collection_of_inputs
-          @first_error = nil
-        end
-
-        def validate!
-          @collection_of_inputs.each do |input|
-            process_input(input)
-            break if @first_error.present?
+      module Validation
+        extend self
+
+        def validate!(context, collection_of_inputs) # rubocop:disable Metrics/MethodLength
+          warehouse = context.send(:servactory_service_warehouse)
+          first_error = nil
+          failed_input = nil
+
+          collection_of_inputs.each do |input|
+            first_error = process_input(context, warehouse, input)
+            if first_error.present?
+              failed_input = input
+              break
+            end
           end
 
-          raise_errors
+          return if first_error.nil?
+
+          context.fail_input!(failed_input.name, message: first_error)
         end
 
         private
 
-        def process_input(input)
+        def process_input(context, warehouse, input)
+          value = warehouse.fetch_input(input.name)
+
           input.options_for_checks.each do |check_key, check_options|
-            process_option(check_key, check_options, input:)
-            break if @first_error.present?
+            error = process_option(context, input, value, check_key, check_options)
+            return error if error.present?
           end
+
+          nil
         end
 
-        def process_option(check_key, check_options, input:) # rubocop:disable Metrics/MethodLength
-          validation_classes = validation_classes_from(input)
+        def process_option(context, input, value, check_key, check_options) # rubocop:disable Metrics/MethodLength
+          validation_classes = input.collection_of_options.validation_classes
           return if validation_classes.empty?
 
           validation_classes.each do |validation_class|
-            error_message = process_validation_class(
-              validation_class:,
-              input:,
+            error_message = validation_class.check(
+              context:,
+              attribute: input,
+              value:,
               check_key:,
               check_options:
             )
-
-            next if error_message.blank?
-
-            @first_error = error_message
-            break
+            return error_message if error_message.present?
           end
-        end
-
-        def process_validation_class(
-          validation_class:,
-          input:,
-          check_key:,
-          check_options:
-        )
-          validation_class.check(
-            context: @context,
-            attribute: input,
-            value: @context.send(:servactory_service_warehouse).fetch_input(input.name),
-            check_key:,
-            check_options:
-          )
-        end
-
-        ########################################################################
-
-        def validation_classes_from(input)
-          @validation_classes_cache ||= input.collection_of_options.validation_classes # rubocop:disable Naming/MemoizedInstanceVariableName
-        end
-
-        ########################################################################
-
-        def raise_errors
-          return if @first_error.nil?
 
-          @context.fail_input!(nil, message: @first_error)
+          nil
         end
       end
     end

data/lib/servactory/inputs/validations/required.rb

@@ -22,7 +22,7 @@ module Servactory
       # end
       # ```
       class Required
-        extend Servactory::Maintenance::Attributes::Validations::Concerns::ErrorBuilder
+        extend Servactory::Maintenance::Validations::Concerns::ErrorBuilder
 
         # Validates that a required input has a present value.
         #
@@ -30,8 +30,9 @@ module Servactory
         # @param attribute [Inputs::Input] Input attribute to validate
         # @param value [Object] Value to check for presence
         # @param check_key [Symbol] Must be :required to trigger validation
+        # @param check_options [Hash, nil] Unused, accepted for uniform checker interface
         # @return [String, nil] Error message on failure, nil on success
-        def self.check(context:, attribute:, value:, check_key:, **)
+        def self.check(context:, attribute:, value:, check_key:, check_options: nil) # rubocop:disable Lint/UnusedMethodArgument
           return unless should_be_checked_for?(attribute, check_key)
           return if Servactory::Utils.value_present?(value)
 

data/lib/servactory/internals/collection.rb

@@ -2,30 +2,11 @@
 
 module Servactory
   module Internals
-    class Collection
-      extend Forwardable
-
-      def_delegators :@collection, :<<, :filter, :each, :map, :to_h, :merge, :find
-
-      def initialize(collection = Set.new)
-        @collection = collection
-      end
-
-      def only(*names)
-        Collection.new(filter { |internal| names.include?(internal.name) })
-      end
-
-      def except(*names)
-        Collection.new(filter { |internal| names.exclude?(internal.name) })
-      end
-
-      def names
-        map(&:name)
-      end
-
-      def find_by(name:)
-        find { |internal| internal.name == name }
-      end
+    # Specialized collection for Internal attributes.
+    #
+    # Inherits all behavior from the base Attributes::Collection
+    # without any overrides.
+    class Collection < Servactory::Maintenance::Attributes::Collection
     end
   end
 end

data/lib/servactory/internals/internal.rb

@@ -2,7 +2,7 @@
 
 module Servactory
   module Internals
-    class Internal
+    class Internal < Servactory::Maintenance::Attributes::Base
       class Actor
         attr_reader :name,
                     :types,
@@ -26,138 +26,30 @@ module Servactory
         # The methods below are required to support the internal work.
 
         def input?
-          false
+          @attribute.input?
         end
 
         def internal?
-          true
+          @attribute.internal?
         end
 
         def output?
-          false
+          @attribute.output?
         end
       end
 
-      attr_reader :name,
-                  :collection_of_options,
-                  :options
-
-      def initialize(
-        name,
-        *helpers,
-        option_helpers:,
-        **options
-      )
-        @name = name
-        @option_helpers = option_helpers
-
-        register_options(helpers:, options:)
-      end
-
-      def method_missing(name, *args, &block)
-        option = @collection_of_options.find_by(name:)
-        return super if option.nil?
-
-        option.body
-      end
-
-      def respond_to_missing?(name, *)
-        @collection_of_options.names.include?(name) || super
-      end
-
-      def register_options(helpers:, options:)
-        merged_options = augment_options_with_helpers(helpers:, options:)
-        options_registrar = create_options_registrar(options: merged_options)
-
-        @options = merged_options
-        @collection_of_options = options_registrar.collection
-      end
-
-      def options_for_checks
-        @collection_of_options.options_for_checks
-      end
-
-      def system_name
-        self.class.name.demodulize.downcase.to_sym
-      end
-
-      def i18n_name
-        system_name.to_s.pluralize
-      end
-
-      def input?
-        false
-      end
-
       def internal?
         true
       end
 
-      def output?
-        false
-      end
-
       private
 
-      def create_options_registrar(options:)
-        Servactory::Maintenance::Attributes::Options::Registrar.register(
-          attribute: self,
-          options:,
-          features: available_feature_options
-        )
-      end
-
       def available_feature_options
         {
           types: true,
           must: true
         }
       end
-
-      def augment_options_with_helpers(helpers:, options:)
-        result_options = options.dup
-        merge_standard_helpers_into(target_options: result_options, helpers:) if helpers.present?
-        merge_advanced_helpers_into(target_options: result_options, source_options: options)
-        result_options
-      end
-
-      def merge_standard_helpers_into(target_options:, helpers:)
-        standard_helpers_result = transform_helpers_to_options(helpers:)
-        target_options.deep_merge!(standard_helpers_result)
-      end
-
-      def merge_advanced_helpers_into(target_options:, source_options:)
-        advanced_helpers = filter_advanced_helpers(options: source_options)
-        return if advanced_helpers.blank?
-
-        advanced_helpers_result = transform_helpers_to_options(helpers: advanced_helpers)
-        target_options.deep_merge!(advanced_helpers_result)
-      end
-
-      def filter_advanced_helpers(options:)
-        reserved_options = Servactory::Maintenance::Attributes::Options::Registrar::RESERVED_OPTIONS
-        options.except(*reserved_options)
-      end
-
-      def transform_helpers_to_options(helpers:)
-        helpers.each_with_object({}) do |(helper_name, values), result|
-          helper = @option_helpers.find_by(name: helper_name)
-          next if helper.blank?
-
-          transformed_option = transform_helper_to_option(helper:, values:)
-          result.deep_merge!(transformed_option) if transformed_option.present?
-        end
-      end
-
-      def transform_helper_to_option(helper:, values:)
-        return helper.equivalent unless helper.equivalent.is_a?(Proc)
-
-        if values.is_a?(Hash)
-          helper.equivalent.call(**values)
-        else
-          helper.equivalent.call(values)
-        end
-      end
     end
   end
 end

data/lib/servactory/maintenance/attributes/base.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Maintenance
+    module Attributes
+      class Base
+        attr_reader :name,
+                    :collection_of_options,
+                    :options
+
+        def initialize(
+          name,
+          *helpers,
+          option_helpers:,
+          **options
+        )
+          @name = name
+          @option_helpers = option_helpers
+
+          register_options(helpers:, options:)
+        end
+
+        def method_missing(name, *args, &block)
+          option = @collection_of_options.find_by(name:)
+          return super if option.nil?
+
+          option.body_for_access
+        end
+
+        def respond_to_missing?(name, *)
+          @collection_of_options.names.include?(name) || super
+        end
+
+        def register_options(helpers:, options:)
+          merged_options = augment_options_with_helpers(helpers:, options:)
+          options_registrar = create_options_registrar(options: merged_options)
+
+          @options = merged_options
+          @collection_of_options = options_registrar.collection
+        end
+
+        def options_for_checks
+          @collection_of_options.options_for_checks
+        end
+
+        def system_name
+          @system_name ||= self.class.name.demodulize.downcase.to_sym
+        end
+
+        def i18n_name
+          @i18n_name ||= system_name.to_s.pluralize
+        end
+
+        def actor
+          @actor ||= self.class::Actor.new(self)
+        end
+
+        def typed_actor_kwargs
+          @typed_actor_kwargs ||= { system_name => actor }.freeze
+        end
+
+        def input?
+          false
+        end
+
+        def internal?
+          false
+        end
+
+        def output?
+          false
+        end
+
+        private
+
+        def create_options_registrar(options:)
+          Servactory::Maintenance::Options::Registrar.register(
+            attribute: self,
+            options:,
+            features: available_feature_options
+          )
+        end
+
+        def available_feature_options
+          raise NotImplementedError, "Subclass must implement available_feature_options"
+        end
+
+        def augment_options_with_helpers(helpers:, options:)
+          result_options = options.dup
+          merge_standard_helpers_into(target_options: result_options, helpers:) if helpers.present?
+          merge_advanced_helpers_into(target_options: result_options, source_options: options)
+          result_options
+        end
+
+        def merge_standard_helpers_into(target_options:, helpers:)
+          standard_helpers_result = transform_helpers_to_options(helpers:)
+          target_options.deep_merge!(standard_helpers_result)
+        end
+
+        def merge_advanced_helpers_into(target_options:, source_options:)
+          advanced_helpers = filter_advanced_helpers(options: source_options)
+          return if advanced_helpers.blank?
+
+          advanced_helpers_result = transform_helpers_to_options(helpers: advanced_helpers)
+          target_options.deep_merge!(advanced_helpers_result)
+        end
+
+        def filter_advanced_helpers(options:)
+          reserved_options = Servactory::Maintenance::Options::Registrar::RESERVED_OPTIONS
+          options.except(*reserved_options)
+        end
+
+        def transform_helpers_to_options(helpers:)
+          helpers.each_with_object({}) do |(helper_name, values), result|
+            helper = @option_helpers.find_by(name: helper_name)
+            next if helper.blank?
+
+            transformed_option = transform_helper_to_option(helper:, values:)
+            result.deep_merge!(transformed_option) if transformed_option.present?
+          end
+        end
+
+        def transform_helper_to_option(helper:, values:)
+          return helper.equivalent unless helper.equivalent.is_a?(Proc)
+
+          if values.is_a?(Hash)
+            helper.equivalent.call(**values)
+          else
+            helper.equivalent.call(values)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/maintenance/attributes/collection.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Maintenance
+    module Attributes
+      # Collection wrapper for managing attribute objects (inputs, internals, outputs).
+      #
+      # ## Purpose
+      #
+      # Collection provides a polymorphic base for storing and querying attribute
+      # instances. It wraps a Set to ensure uniqueness and delegates common
+      # enumeration methods. Subclasses override `lookup_name` to customize
+      # how attributes are indexed and filtered (e.g., inputs use `internal_name`
+      # for the `as:` parameter).
+      #
+      # ## Usage
+      #
+      # Subclasses are used internally by Input, Internal, and Output DSL modules
+      # to manage their registered attributes:
+      #
+      # ```ruby
+      # collection = Collection.new
+      # collection << attribute
+      #
+      # collection.names                      # => [:first_name, :last_name]
+      # collection.find_by(name: :first_name) # => attribute instance
+      # collection.only(:first_name)          # => filtered Collection
+      # collection.except(:last_name)         # => filtered Collection
+      # ```
+      #
+      # ## Performance
+      #
+      # The collection uses memoization for frequently accessed data:
+      # - `attributes_index` - cached hash for O(1) lookups by name
+      #
+      class Collection
+        extend Forwardable
+
+        def_delegators :@collection,
+                       :<<,
+                       :filter,
+                       :each, :each_with_object,
+                       :map, :to_h,
+                       :merge
+
+        # Initializes the collection with an optional pre-built Set.
+        #
+        # @param collection [Set] initial set of attributes
+        # @return [Collection]
+        def initialize(collection = Set.new)
+          @collection = collection
+        end
+
+        # Returns names of all attributes in the collection.
+        #
+        # @return [Array<Symbol>] list of attribute names
+        def names
+          map(&:name)
+        end
+
+        # Returns a new collection containing only the named attributes.
+        #
+        # @param names [Array<Symbol>] attribute names to include
+        # @return [Collection] filtered collection
+        def only(*names)
+          self.class.new(filter { |attribute| names.include?(lookup_name(attribute)) })
+        end
+
+        # Returns a new collection excluding the named attributes.
+        #
+        # @param names [Array<Symbol>] attribute names to exclude
+        # @return [Collection] filtered collection
+        def except(*names)
+          self.class.new(filter { |attribute| names.exclude?(lookup_name(attribute)) })
+        end
+
+        # Finds an attribute by its name using indexed lookup.
+        #
+        # @param name [Symbol] the attribute name to find
+        # @return [Object, nil] the found attribute or nil
+        def find_by(name:)
+          attributes_index[name]
+        end
+
+        private
+
+        # Builds and caches a hash index for O(1) attribute lookups.
+        #
+        # @return [Hash{Symbol => Object}] attribute names mapped to attribute instances
+        def attributes_index
+          @attributes_index ||= each_with_object({}) do |attribute, index|
+            index[lookup_name(attribute)] = attribute
+          end
+        end
+
+        # Returns the name used for indexing and filtering a given attribute.
+        #
+        # Subclasses override this to use alternative name fields
+        # (e.g., `internal_name` for inputs with the `as:` parameter).
+        #
+        # @param attribute [Object] the attribute to extract a name from
+        # @return [Symbol] the lookup name
+        def lookup_name(attribute)
+          attribute.name
+        end
+      end
+    end
+  end
+end

data/lib/servactory/maintenance/attributes/option_helper.rb

@@ -3,19 +3,40 @@
 module Servactory
   module Maintenance
     module Attributes
-      class OptionHelper
-        attr_reader :name,
-                    :equivalent,
-                    :meta
-
+      # @deprecated Use {Servactory::Maintenance::Options::Helper} instead.
+      #   This class is maintained for backward compatibility only and will be
+      #   removed in a future major version.
+      #
+      # OptionHelper provides a simple way to define custom option helpers
+      # for service inputs, internals, and outputs configuration.
+      #
+      # @example Creating a custom option helper
+      #   Servactory::Maintenance::Attributes::OptionHelper.new(
+      #     name: :must_be_positive,
+      #     equivalent: {
+      #       must: {
+      #         be_positive: {
+      #           is: ->(value:, **) { value.positive? },
+      #           message: "must be positive"
+      #         }
+      #       }
+      #     }
+      #   )
+      #
+      # @see Servactory::Maintenance::Options::Helper The new preferred class
+      class OptionHelper < Servactory::Maintenance::Options::Helper
+        # @deprecated This class is deprecated. Use Options::Helper instead.
+        #
+        # Creates a new OptionHelper instance.
+        #
+        # @param name [Symbol] The name of the option helper
+        # @param equivalent [Hash, Proc] The equivalent option configuration
+        # @param meta [Hash] Additional metadata for the helper
+        # @return [OptionHelper] A new instance
         def initialize(name:, equivalent:, meta: {})
-          @name = name
-          @equivalent = equivalent
-          @meta = meta
-        end
-
-        def dynamic_option?
-          meta[:type] == :dynamic_option
+          warn "[DEPRECATION] Servactory::Maintenance::Attributes::OptionHelper is deprecated. " \
+               "Use Servactory::Maintenance::Options::Helper instead."
+          super
         end
       end
     end

data/lib/servactory/maintenance/{attributes/options_collection.rb → options/collection.rb}

@@ -2,12 +2,12 @@
 
 module Servactory
   module Maintenance
-    module Attributes
+    module Options
       # Collection wrapper for managing Option objects.
       #
       # ## Purpose
       #
-      # OptionsCollection provides a unified interface for storing and querying
+      # Collection provides a unified interface for storing and querying
       # Option instances associated with service attributes (inputs, internals, outputs).
       # It wraps a Set to ensure uniqueness and delegates common enumeration methods.
       #
@@ -17,7 +17,7 @@ module Servactory
       # to manage their registered options:
       #
       # ```ruby
-      # collection = OptionsCollection.new
+      # collection = Collection.new
       # collection << Option.new(name: :required, ...)
       # collection << Option.new(name: :types, ...)
       #
@@ -32,21 +32,20 @@ module Servactory
       # - `options_for_checks` - cached hash for validation pipeline
       # - `options_index` - cached hash for O(1) lookups by name
       #
-      class OptionsCollection
+      class Collection
         extend Forwardable
 
         def_delegators :@collection,
                        :<<,
                        :filter,
-                       :each, :each_with_object,
+                       :each_with_object,
                        :map, :flat_map,
-                       :find,
                        :size,
                        :empty?
 
         # Initializes an empty collection.
         #
-        # @return [OptionsCollection]
+        # @return [Collection]
         def initialize
           @collection = Set.new
         end

data/lib/servactory/maintenance/{attributes → options}/define_conflict.rb

@@ -2,7 +2,7 @@
 
 module Servactory
   module Maintenance
-    module Attributes
+    module Options
       class DefineConflict
         attr_reader :content
 

data/lib/servactory/maintenance/{attributes → options}/define_method.rb

@@ -2,7 +2,7 @@
 
 module Servactory
   module Maintenance
-    module Attributes
+    module Options
       class DefineMethod
         attr_reader :name,
                     :content