servactory 3.1.0.rc2 → 3.1.0.rc4

data/lib/servactory/configuration/option_helpers/option_helpers_collection.rb

@@ -9,7 +9,20 @@ module Servactory
       #
       # OptionHelpersCollection provides a unified interface for storing and
       # querying Helper instances used by the configuration system.
-      # It wraps a Set to ensure uniqueness and delegates common enumeration methods.
+      # It keeps helpers in an insertion-ordered Hash keyed by helper name,
+      # so every name resolves to exactly one helper.
+      #
+      # ## Built-in Helpers
+      #
+      # Helpers passed to the constructor are built-in: their names are
+      # reserved, and only `replace` may swap them (used to rebind built-in
+      # dynamic options to the configuration of a subclass).
+      #
+      # ## Inheritance
+      #
+      # A collection accepts one helper per name. A duplicate, made when
+      # a service class is inherited, may replace a helper registered before
+      # duplication in place without affecting the original.
       #
       # ## Usage
       #
@@ -17,70 +30,184 @@ module Servactory
       # to manage registered option helpers:
       #
       # ```ruby
-      # collection = OptionHelpersCollection.new
-      # collection << helper
+      # collection = OptionHelpersCollection.new(builtin_helpers)
+      # collection.register(helper)       # => :registered
+      # collection << other_helper        # => collection, or raises ArgumentError
+      # collection.merge([third_helper])  # => collection, or raises ArgumentError
       #
       # collection.find_by(name: :must)   # => helper instance
       # collection.dynamic_options        # => filtered OptionHelpersCollection
       # ```
       #
+      # ## Enumeration
+      #
+      # The collection includes Enumerable and yields helpers in registration
+      # order. Enumerable methods return plain values rather than collections:
+      # `filter` and `map` return Arrays, `find` returns a helper or nil, and
+      # `each_with_object` returns the memo object. Use `dynamic_options`
+      # to get a filtered OptionHelpersCollection.
+      #
       # ## Performance
       #
-      # The collection uses memoization for frequently accessed data:
-      # - `helpers_index` - cached hash for O(1) lookups by name
+      # Registration and lookup by name are O(1) Hash operations without
+      # cached indexes, so helpers registered after attributes are declared
+      # are visible to subsequent declarations.
       #
       class OptionHelpersCollection
-        extend Forwardable
+        include Enumerable
 
-        def_delegators :@collection,
-                       :<<,
-                       :filter,
-                       :each_with_object,
-                       :map,
-                       :merge
-
-        # Initializes the collection with an optional pre-built Set.
+        # Initializes the collection with built-in helpers.
         #
-        # @param collection [Set] initial set of helpers
+        # @param builtin_helpers [Enumerable<Maintenance::Options::Helper>] helpers whose names are reserved
         # @return [OptionHelpersCollection]
-        def initialize(collection = Set.new)
-          @collection = collection
+        def initialize(builtin_helpers = [])
+          @helpers = builtin_helpers.to_h { |helper| [helper.name, helper] }
+          @builtin_names = @helpers.keys.to_set.freeze
+          @own_names = Set.new
         end
 
-        # Duplicates the collection, resetting memoized caches.
+        # Duplicates the collection so that registrations do not leak into the original.
+        #
+        # Helpers of the original may be replaced once in the duplicate.
         #
         # @param original [OptionHelpersCollection] the collection being duplicated
         # @return [void]
         def initialize_dup(original)
           super
-          @collection = original.instance_variable_get(:@collection).dup
-          @helpers_index = nil
+          @helpers = original.instance_variable_get(:@helpers).dup
+          @own_names = Set.new
+        end
+
+        # Iterates over helpers in registration order.
+        #
+        # @yieldparam helper [Maintenance::Options::Helper] each registered helper
+        # @return [OptionHelpersCollection, Enumerator] self, or an enumerator without a block
+        def each(&block)
+          return enum_for(:each) unless block_given?
+
+          @helpers.each_value(&block)
+          self
+        end
+
+        # Registers a helper under its name.
+        #
+        # A helper with a new name is appended; a helper replacing one registered
+        # before duplication keeps its position. The helpers are left unchanged
+        # unless the result is `:registered`.
+        #
+        # @param helper [Maintenance::Options::Helper] the helper to register
+        # @return [Symbol] `:registered`, `:skipped` when this very helper is
+        #   already registered (the name then counts as registered by this collection
+        #   itself), `:reserved` when the name belongs to a built-in helper,
+        #   or `:duplicated` when this collection already registered the name itself
+        #   since it was created or duplicated
+        def register(helper)
+          name = helper.name
+
+          if @helpers[name].equal?(helper)
+            @own_names << name
+            return :skipped
+          end
+
+          return :reserved if @builtin_names.include?(name)
+          return :duplicated if @own_names.include?(name)
+
+          @own_names << name
+          @helpers[name] = helper
+          :registered
+        end
+
+        # Registers a helper under its name, raising when the name is rejected.
+        #
+        # Follows `register`: a helper registered before duplication may be
+        # replaced once. Re-adding this very helper leaves the helpers unchanged
+        # but still counts as this collection registering the name itself, so
+        # after re-adding an inherited helper a different helper with that name
+        # raises instead of replacing it.
+        #
+        # @param helper [Maintenance::Options::Helper] the helper to register
+        # @return [OptionHelpersCollection] self
+        # @raise [ArgumentError] when the name belongs to a built-in helper
+        #   or this collection already registered the name itself
+        def <<(helper)
+          case register(helper)
+          when :reserved
+            raise_error_about_reserved_name_with(helper.name)
+          when :duplicated
+            raise_error_about_duplicated_name_with(helper.name)
+          end
+
+          self
+        end
+
+        # Registers every helper of the given enumerables in order with `<<`.
+        #
+        # Helpers preceding a rejected one stay registered.
+        #
+        # A built-in helper coming from another service's collection counts as
+        # a reserved name unless it is the very helper of this collection. Each
+        # service rebinds the built-in dynamic options (`consists_of`, `schema`)
+        # to its own configuration, so merging another service's whole
+        # collection raises.
+        #
+        # @param enums [Array<Enumerable<Maintenance::Options::Helper>>] the helpers to register
+        # @return [OptionHelpersCollection] self
+        # @raise [ArgumentError] when `<<` rejects a helper
+        def merge(*enums)
+          enums.each { |helpers| helpers.each { |helper| self << helper } }
+          self
         end
 
         # Returns a new collection containing only dynamic option helpers.
         #
         # @return [OptionHelpersCollection] filtered collection of dynamic helpers
         def dynamic_options
-          OptionHelpersCollection.new(filter(&:dynamic_option?))
+          each_with_object(OptionHelpersCollection.new) do |helper, collection|
+            collection.register(helper) if helper.dynamic_option?
+          end
         end
 
-        # Finds a helper by its name using indexed lookup.
+        # Finds a helper by its name with a direct Hash lookup.
         #
         # @param name [Symbol] the helper name to find
         # @return [Maintenance::Options::Helper, nil] the found helper or nil
         def find_by(name:)
-          helpers_index[name]
+          @helpers[name]
+        end
+
+        # Replaces a built-in helper by name with a new one, keeping its position.
+        #
+        # Names that do not belong to a built-in helper are ignored.
+        #
+        # @param name [Symbol] the built-in helper name to replace
+        # @param with [Maintenance::Options::Helper] the replacement helper
+        # @return [void]
+        def replace(name:, with:)
+          return unless @builtin_names.include?(name)
+
+          @helpers[name] = with
         end
 
         private
 
-        # Builds and caches a hash index for O(1) helper lookups.
+        # Raises an error about a name that belongs to a built-in helper.
         #
-        # @return [Hash{Symbol => Maintenance::Options::Helper}] helper names mapped to Helper instances
-        def helpers_index
-          @helpers_index ||= each_with_object({}) do |helper, index|
-            index[helper.name] = helper
-          end
+        # @param name [Symbol] the rejected helper name
+        # @raise [ArgumentError] always
+        def raise_error_about_reserved_name_with(name)
+          raise ArgumentError,
+                "The `#{name}` option helper name is reserved by a built-in option helper. " \
+                "See configuration example here: https://servactory.com/guide/configuration"
+        end
+
+        # Raises an error about a name this collection already registered itself.
+        #
+        # @param name [Symbol] the rejected helper name
+        # @raise [ArgumentError] always
+        def raise_error_about_duplicated_name_with(name)
+          raise ArgumentError,
+                "The `#{name}` option helper is already registered in this collection. " \
+                "See configuration example here: https://servactory.com/guide/configuration"
         end
       end
     end

data/lib/servactory/context/warehouse/inputs.rb

@@ -45,7 +45,7 @@ module Servactory
         # @param _args [Array] Method arguments (unused)
         # @return [Object] Input value or predicate result
         def method_missing(name, *_args)
-          predicate = @context.config.predicate_methods_enabled && name.end_with?("?")
+          predicate = @context.class.config.predicate_methods_enabled && name.end_with?("?")
 
           input_name = predicate ? name.to_s.chomp("?").to_sym : name
 

data/lib/servactory/context/workspace/inputs.rb

@@ -38,7 +38,7 @@ module Servactory
         private
 
         def fetch_with(name:, &_block)
-          predicate = @context.config.predicate_methods_enabled && name.end_with?("?")
+          predicate = @context.class.config.predicate_methods_enabled && name.end_with?("?")
 
           input_name = predicate ? name.to_s.chomp("?").to_sym : name
 
@@ -67,7 +67,7 @@ module Servactory
         def resolve_input(name)
           return true if @collection_of_inputs.find_by(name:)
 
-          @context.config.predicate_methods_enabled &&
+          @context.class.config.predicate_methods_enabled &&
             name.to_s.end_with?("?") &&
             @collection_of_inputs.find_by(name: name.to_s.chomp("?").to_sym)
         end

data/lib/servactory/context/workspace/internals.rb

@@ -60,7 +60,7 @@ module Servactory
         end
 
         def fetch_with(name:, &_block)
-          predicate = @context.config.predicate_methods_enabled && name.end_with?("?")
+          predicate = @context.class.config.predicate_methods_enabled && name.end_with?("?")
 
           internal_name = predicate ? name.to_s.chomp("?").to_sym : name
           internal = @collection_of_internals.find_by(name: internal_name)
@@ -89,7 +89,7 @@ module Servactory
         def resolve_internal(name)
           return true if @collection_of_internals.find_by(name:)
 
-          @context.config.predicate_methods_enabled &&
+          @context.class.config.predicate_methods_enabled &&
             name.to_s.end_with?("?") &&
             @collection_of_internals.find_by(name: name.to_s.chomp("?").to_sym)
         end

data/lib/servactory/context/workspace/outputs.rb

@@ -52,7 +52,7 @@ module Servactory
         end
 
         def fetch_with(name:, &_block)
-          predicate = @context.config.predicate_methods_enabled && name.end_with?("?")
+          predicate = @context.class.config.predicate_methods_enabled && name.end_with?("?")
 
           output_name = predicate ? name.to_s.chomp("?").to_sym : name
           output = @collection_of_outputs.find_by(name: output_name)
@@ -67,7 +67,7 @@ module Servactory
         def resolve_output(name)
           return true if @collection_of_outputs.find_by(name:)
 
-          @context.config.predicate_methods_enabled &&
+          @context.class.config.predicate_methods_enabled &&
             name.to_s.end_with?("?") &&
             @collection_of_outputs.find_by(name: name.to_s.chomp("?").to_sym)
         end

data/lib/servactory/context/workspace.rb

@@ -8,7 +8,7 @@ module Servactory
 
         def initialize(context)
           @class_name = context.class.name
-          @i18n_root_key = context.config.i18n_root_key
+          @i18n_root_key = context.class.config.i18n_root_key
         end
 
         def translate(key, **options)
@@ -42,11 +42,11 @@ module Servactory
       end
 
       def success!
-        raise config.success_class.new(context: self)
+        raise self.class.config.success_class.new(context: self)
       end
 
       def fail_input!(input_name, message:, meta: nil)
-        raise config.input_exception_class.new(
+        raise self.class.config.input_exception_class.new(
           context: self,
           input_name:,
           message:,
@@ -55,7 +55,7 @@ module Servactory
       end
 
       def fail_internal!(internal_name, message:, meta: nil)
-        raise config.internal_exception_class.new(
+        raise self.class.config.internal_exception_class.new(
           context: self,
           internal_name:,
           message:,
@@ -64,7 +64,7 @@ module Servactory
       end
 
       def fail_output!(output_name, message:, meta: nil)
-        raise config.output_exception_class.new(
+        raise self.class.config.output_exception_class.new(
           context: self,
           output_name:,
           message:,
@@ -73,7 +73,7 @@ module Servactory
       end
 
       def fail!(type = :base, message:, meta: nil)
-        raise config.failure_class.new(type:, message:, meta:)
+        raise self.class.config.failure_class.new(type:, message:, meta:)
       end
 
       def fail_result!(service_result)
@@ -118,7 +118,7 @@ module Servactory
       end
 
       def call
-        raise config.failure_class.new(
+        raise self.class.config.failure_class.new(
           type: :base,
           message: servactory_service_info.translate(
             "methods.call.not_used"

data/lib/servactory/info/builder.rb

@@ -26,7 +26,7 @@ module Servactory
 
       private
 
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def build_all_attributes(inputs:, internals:, outputs:, stages:, config:)
         build_input_attributes_with(
           collection: inputs,
@@ -45,7 +45,6 @@ module Servactory
 
         build_action_stages_with(collection: stages)
       end
-      # rubocop:enable Metrics/MethodLength
 
       def build_input_attributes_with(collection:, dynamic_options:)
         @inputs = build_attributes_with(
@@ -142,11 +141,13 @@ module Servactory
       end
 
       def enrich_options_with_common_fields(attribute:, options:)
+        types = attribute.collection_of_options.find_by(name: :types)
         must = attribute.collection_of_options.find_by(name: :must)
 
         options.merge(
           actor: attribute.actor,
-          types: attribute.types,
+          type: { is: types.value, message: types.body[:message] },
+          types: types.value,
           must: must&.value
         )
       end

data/lib/servactory/inputs/dsl.rb

@@ -18,12 +18,16 @@ module Servactory
         private
 
         def input(name, *helpers, **options)
-          collection_of_inputs << Input.new(
+          input = Input.new(
             name,
             *helpers,
             option_helpers: config.input_option_helpers,
             **options
           )
+
+          raise ArgumentError, "[#{self.name}] Input `#{name}` must have the `type` option" if input.types.empty?
+
+          collection_of_inputs << input
         end
 
         def collection_of_inputs

data/lib/servactory/inputs/input.rb

@@ -52,7 +52,7 @@ module Servactory
 
       attr_reader :internal_name
 
-      # rubocop:disable Style/KeywordParametersOrder
+      # rubocop:disable-next Style/KeywordParametersOrder
       def initialize(
         name,
         *helpers,
@@ -64,7 +64,6 @@ module Servactory
 
         super(name, *helpers, option_helpers:, **options)
       end
-      # rubocop:enable Style/KeywordParametersOrder
 
       def conflict_code
         @collection_of_options.defined_conflict_code

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

@@ -29,30 +29,22 @@ module Servactory
         def process_input(context, warehouse, input)
           value = warehouse.fetch_input(input.name)
 
-          input.options_for_checks.each do |check_key, check_options|
-            error = process_option(context, input, value, check_key, check_options)
+          input.collection_of_options.validations_for_checks.each do |check_key, check_options, validation_class|
+            error = process_option(context, input, value, check_key, check_options, validation_class)
             return error if error.present?
           end
 
           nil
         end
 
-        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 = validation_class.check(
-              context:,
-              attribute: input,
-              value:,
-              check_key:,
-              check_options:
-            )
-            return error_message if error_message.present?
-          end
-
-          nil
+        def process_option(context, input, value, check_key, check_options, validation_class)
+          validation_class.check(
+            context:,
+            attribute: input,
+            value:,
+            check_key:,
+            check_options:
+          )
         end
       end
     end

data/lib/servactory/internals/dsl.rb

@@ -17,12 +17,18 @@ module Servactory
         private
 
         def internal(name, *helpers, **options)
-          collection_of_internals << Internal.new(
+          internal = Internal.new(
             name,
             *helpers,
             option_helpers: config.internal_option_helpers,
             **options
           )
+
+          if internal.types.empty?
+            raise ArgumentError, "[#{self.name}] Internal attribute `#{name}` must have the `type` option"
+          end
+
+          collection_of_internals << internal
         end
 
         def collection_of_internals

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

@@ -39,8 +39,11 @@ module Servactory
           @collection_of_options = options_registrar.collection
         end
 
+        # @deprecated Use collection_of_options.validations_for_checks instead.
         def options_for_checks
-          @collection_of_options.options_for_checks
+          warn "[DEPRECATION] Servactory::Maintenance::Attributes::Base#options_for_checks is deprecated. " \
+               "Use collection_of_options.validations_for_checks instead."
+          @collection_of_options.send(:check_options_by_key)
         end
 
         def system_name

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

@@ -13,6 +13,10 @@ module Servactory
       # how attributes are indexed and filtered (e.g., inputs use `internal_name`
       # for the `as:` parameter).
       #
+      # An attribute is declared once per name: adding an attribute whose
+      # `name` is already declared (e.g., redeclaring a parent's input in
+      # a child service) replaces the earlier declaration in place.
+      #
       # ## Usage
       #
       # Subclasses are used internally by Input, Internal, and Output DSL modules
@@ -32,16 +36,15 @@ module Servactory
       #
       # The collection uses memoization for frequently accessed data:
       # - `attributes_index` - cached hash for O(1) lookups by name
+      # - `declarations_index` - cached hash for O(1) redeclaration checks
       #
       class Collection
         extend Forwardable
 
         def_delegators :@collection,
-                       :<<,
                        :filter,
                        :each, :each_with_object,
-                       :map, :to_h,
-                       :merge
+                       :map, :to_h
 
         # Initializes the collection with an optional pre-built Set.
         #
@@ -51,6 +54,50 @@ module Servactory
           @collection = collection
         end
 
+        # Duplicates the collection, resetting memoized caches.
+        #
+        # @param original [Collection] the collection being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+          @attributes_index = nil
+          @declarations_index = nil
+        end
+
+        # Adds an attribute to the collection, invalidating the index cache.
+        #
+        # An attribute with an already declared `name` replaces
+        # the earlier declaration in place, keeping its position.
+        #
+        # @param attribute [Object] the attribute to add
+        # @return [Collection] self
+        def <<(attribute)
+          redeclared = declarations_index[attribute.name]
+
+          if redeclared.nil?
+            @collection << attribute
+          else
+            @collection = Set.new(@collection) { |declared| declared.equal?(redeclared) ? attribute : declared }
+          end
+
+          declarations_index[attribute.name] = attribute
+          @attributes_index = nil
+          self
+        end
+
+        # Merges attributes from another collection, invalidating the index cache.
+        #
+        # Each attribute is added as with `<<`, so redeclarations replace
+        # the earlier declarations in place.
+        #
+        # @param other [Collection, Enumerable] attributes to merge
+        # @return [Collection] self
+        def merge(other)
+          other.each { |attribute| self << attribute }
+          self
+        end
+
         # Returns names of all attributes in the collection.
         #
         # @return [Array<Symbol>] list of attribute names
@@ -88,9 +135,17 @@ module Servactory
         #
         # @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
+          @attributes_index ||= to_h { |attribute| [lookup_name(attribute), attribute] }
+        end
+
+        # Builds and caches a hash index of declared attributes by `name`.
+        #
+        # Unlike `attributes_index`, it is keyed by the declared name
+        # (the external name for inputs), which identifies a redeclaration.
+        #
+        # @return [Hash{Symbol => Object}] declared names mapped to attribute instances
+        def declarations_index
+          @declarations_index ||= to_h { |attribute| [attribute.name, attribute] }
         end
 
         # Returns the name used for indexing and filtering a given attribute.