cmdx 1.1.2 → 1.5.0

data/lib/cmdx/parameter_evaluator.rb

@@ -1,231 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Parameter evaluation system for task execution context.
-  #
-  # ParameterEvaluator processes parameter definitions by extracting values from
-  # task context sources, applying type coercions, performing validations, and
-  # handling optional parameters with default values. It ensures parameter values
-  # meet the requirements defined in parameter specifications before task execution.
-  class ParameterEvaluator
-
-    cmdx_attr_delegator :parent, :method_source, :name, :options, :required?, :optional?, :type,
-                        to: :parameter,
-                        private: true
-
-    # @return [CMDx::Task] The task instance being processed
-    attr_reader :task
-
-    # @return [CMDx::Parameter] The parameter definition being processed
-    attr_reader :parameter
-
-    # Creates a new parameter evaluator instance.
-    #
-    # @param task [CMDx::Task] the task instance containing parameter context
-    # @param parameter [CMDx::Parameter] the parameter definition to evaluate
-    #
-    # @example Create evaluator for a task parameter
-    #   evaluator = ParameterEvaluator.new(task, parameter)
-    def initialize(task, parameter)
-      @task      = task
-      @parameter = parameter
-    end
-
-    # Evaluates a parameter by creating a new evaluator instance and calling it.
-    #
-    # @param task [CMDx::Task] the task instance containing parameter context
-    # @param parameter [CMDx::Parameter] the parameter definition to evaluate
-    #
-    # @return [Object] the coerced and validated parameter value
-    #
-    # @raise [ValidationError] when parameter source is undefined or required parameter is missing
-    # @raise [CoercionError] when parameter value cannot be coerced to expected type
-    #
-    # @example Evaluate a parameter value
-    #   value = ParameterEvaluator.call(task, parameter)
-    def self.call(task, parameter)
-      new(task, parameter).call
-    end
-
-    # Evaluates the parameter by applying coercion and validation.
-    #
-    # @return [Object] the coerced and validated parameter value
-    #
-    # @raise [ValidationError] when parameter source is undefined or required parameter is missing
-    # @raise [CoercionError] when parameter value cannot be coerced to expected type
-    #
-    # @example Evaluate parameter with coercion and validation
-    #   evaluator = ParameterEvaluator.new(task, parameter)
-    #   value = evaluator.call
-    def call
-      coerce!.tap { validate! }
-    end
-
-    private
-
-    # Checks if the parameter source method is defined on the task.
-    #
-    # @return [Boolean] true if the source method exists, false otherwise
-    #
-    # @example Check if parameter source is defined
-    #   evaluator.send(:source_defined?) #=> true
-    def source_defined?
-      task.respond_to?(method_source, true) || task.cmdx_try(method_source)
-    end
-
-    # Retrieves the parameter source object from the task.
-    #
-    # @return [Object] the source object containing parameter values
-    #
-    # @raise [ValidationError] when the source method is not defined on the task
-    #
-    # @example Get parameter source
-    #   evaluator.send(:source) #=> #<Context:...>
-    def source
-      return @source if defined?(@source)
-
-      unless source_defined?
-        raise ValidationError, I18n.t(
-          "cmdx.parameters.undefined",
-          default: "delegates to undefined method #{method_source}",
-          source: method_source
-        )
-      end
-
-      @source = task.cmdx_try(method_source)
-    end
-
-    # Checks if the parameter value exists in the source object.
-    #
-    # @return [Boolean] true if the parameter value exists, false otherwise
-    #
-    # @example Check if parameter value exists
-    #   evaluator.send(:source_value?) #=> true
-    def source_value?
-      return false if source.nil?
-
-      source.cmdx_respond_to?(name, true)
-    end
-
-    # Checks if a required parameter value is missing from the source.
-    #
-    # @return [Boolean] true if required parameter is missing, false otherwise
-    #
-    # @example Check if required parameter is missing
-    #   evaluator.send(:source_value_required?) #=> false
-    def source_value_required?
-      return false if parent&.optional? && source.nil?
-
-      required? && !source_value?
-    end
-
-    # Extracts the parameter value from the source with default handling.
-    #
-    # @return [Object] the parameter value or default value
-    #
-    # @raise [ValidationError] when a required parameter is missing
-    #
-    # @example Get parameter value with default
-    #   evaluator.send(:value) #=> "default_value"
-    def value
-      return @value if defined?(@value)
-
-      if source_value_required?
-        raise ValidationError, I18n.t(
-          "cmdx.parameters.required",
-          default: "is a required parameter"
-        )
-      end
-
-      @value = source.cmdx_try(name)
-      return @value unless @value.nil? && options.key?(:default)
-
-      @value = task.cmdx_yield(options[:default])
-    end
-
-    # Applies type coercion to the parameter value.
-    #
-    # @return [Object] the coerced parameter value
-    #
-    # @raise [CoercionError] when value cannot be coerced to expected type
-    #
-    # @example Coerce parameter value
-    #   evaluator.send(:coerce!) #=> 42
-    def coerce!
-      types = Array(type)
-      tsize = types.size - 1
-
-      types.each_with_index do |key, i|
-        break CMDx.configuration.coercions.call(task, key, value, options)
-      rescue CoercionError => e
-        next if tsize != i
-
-        raise(e) if tsize.zero?
-
-        values = types.map(&:to_s).join(", ")
-        raise CoercionError, I18n.t(
-          "cmdx.coercions.into_any",
-          values:,
-          default: "could not coerce into one of: #{values}"
-        )
-      end
-    end
-
-    # Checks if validations should be skipped for optional missing arguments.
-    #
-    # @return [Boolean] true if validations should be skipped, false otherwise
-    #
-    # @example Check if validations should be skipped
-    #   evaluator.send(:skip_validations_due_to_optional_missing_argument?) #=> false
-    def skip_validations_due_to_optional_missing_argument?
-      optional? && value.nil? && !source.nil? && !source.cmdx_respond_to?(name, true)
-    end
-
-    # Checks if validator should be skipped due to conditional options.
-    #
-    # @param opts [Hash] the validator options
-    #
-    # @return [Boolean] true if validator should be skipped, false otherwise
-    #
-    # @example Check if validator should be skipped
-    #   evaluator.send(:skip_validator_due_to_conditional?, :presence) #=> false
-    def skip_validator_due_to_conditional?(opts)
-      opts.is_a?(Hash) && !task.cmdx_eval(opts)
-    end
-
-    # Checks if validator should be skipped due to allow_nil option.
-    #
-    # @param opts [Symbol] the validator options
-    #
-    # @return [Boolean] true if validator should be skipped, false otherwise
-    #
-    # @example Check if validator should be skipped for nil
-    #   evaluator.send(:skip_validator_due_to_allow_nil?, :presence) #=> true
-    def skip_validator_due_to_allow_nil?(opts)
-      opts.is_a?(Hash) && opts[:allow_nil] && value.nil?
-    end
-
-    # Applies all configured validations to the parameter value.
-    #
-    # @return [void]
-    #
-    # @raise [ValidationError] when parameter value fails validation
-    #
-    # @example Validate parameter value
-    #   evaluator.send(:validate!)
-    def validate!
-      return if skip_validations_due_to_optional_missing_argument?
-
-      types = CMDx.configuration.validators.registry.keys
-
-      options.slice(*types).each_key do |key|
-        opts = options[key]
-        next if skip_validator_due_to_allow_nil?(opts)
-        next if skip_validator_due_to_conditional?(opts)
-
-        CMDx.configuration.validators.call(task, key, value, opts)
-      end
-    end
-
-  end
-end

data/lib/cmdx/parameter_inspector.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Provides formatted inspection and display functionality for parameter objects.
-  #
-  # This module formats parameter information into human-readable string representations,
-  # including nested parameter structures with proper indentation. It processes parameter
-  # hashes in a consistent order and handles child parameter relationships for complex
-  # parameter hierarchies.
-  module ParameterInspector
-
-    ORDERED_KEYS = %i[
-      name type source required options children
-    ].freeze
-
-    module_function
-
-    # Formats a parameter hash into a human-readable inspection string.
-    #
-    # Creates a formatted string representation of parameter information,
-    # displaying attributes in a consistent order with proper indentation
-    # for nested child parameters. The method recursively processes child
-    # parameters with increased indentation depth for visual hierarchy.
-    #
-    # @param parameter [Hash] the parameter hash to format
-    # @option parameter [Symbol, String] :name the parameter name
-    # @option parameter [Symbol, Array<Symbol>] :type the parameter type(s)
-    # @option parameter [Symbol] :source the parameter source context
-    # @option parameter [Boolean] :required whether the parameter is required
-    # @option parameter [Hash] :options additional parameter configuration options
-    # @option parameter [Array<Hash>] :children nested child parameter definitions
-    # @param depth [Integer] the indentation depth for nested parameters (defaults to 1)
-    #
-    # @return [String] formatted multi-line string representation of the parameter
-    #
-    # @example Format a simple parameter
-    #   parameter = { name: :user_id, type: :integer, required: true }
-    #   ParameterInspector.call(parameter)
-    #   #=> "Parameter: name=user_id type=integer required=true"
-    #
-    # @example Format a parameter with children
-    #   parameter = {
-    #     name: :payment,
-    #     type: :hash,
-    #     required: true,
-    #     children: [
-    #       { name: :amount, type: :big_decimal, required: true },
-    #       { name: :currency, type: :string, required: true }
-    #     ]
-    #   }
-    #   ParameterInspector.call(parameter)
-    #   #=> "Parameter: name=payment type=hash required=true
-    #   #       ↳ Parameter: name=amount type=big_decimal required=true
-    #   #       ↳ Parameter: name=currency type=string required=true"
-    def call(parameter, depth = 1)
-      ORDERED_KEYS.filter_map do |key|
-        value = parameter[key]
-        next "#{key}=#{value}" unless key == :children
-
-        spaces = " " * (depth * 2)
-        value.map { |h| "\n#{spaces}↳ #{call(h, depth + 1)}" }.join
-      end.unshift("Parameter:").join(" ")
-    end
-
-  end
-end

data/lib/cmdx/parameter_registry.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Registry for managing parameter definitions within tasks.
-  #
-  # This registry maintains a collection of parameter definitions and provides
-  # validation functionality to ensure all parameters are properly configured
-  # and accessible on their associated tasks. It supports both flat and nested
-  # parameter structures through recursive validation.
-  class ParameterRegistry
-
-    # @return [Array<Parameter>] array containing parameter definition objects
-    attr_reader :registry
-
-    # Initializes a new parameter registry with an empty parameter collection.
-    #
-    # @return [ParameterRegistry] a new parameter registry instance
-    #
-    # @example Creating a new registry
-    #   registry = ParameterRegistry.new
-    #   registry.registry #=> []
-    def initialize
-      @registry = []
-    end
-
-    # Creates a duplicate of the parameter registry with deep-copied parameters.
-    #
-    # This method creates a new registry instance with duplicated parameter
-    # definitions, ensuring changes to the duplicate don't affect the original.
-    #
-    # @return [ParameterRegistry] a new registry instance with duplicated parameters
-    #
-    # @example Duplicate a registry
-    #   original = ParameterRegistry.new
-    #   duplicate = original.dup
-    #   duplicate.object_id != original.object_id #=> true
-    def dup
-      new_registry = self.class.new
-      new_registry.instance_variable_set(:@registry, registry.map(&:dup))
-      new_registry
-    end
-
-    # Checks if all parameters in the registry are valid.
-    #
-    # @return [Boolean] true if all parameters are valid, false otherwise
-    #
-    # @example Check registry validity
-    #   registry.valid? #=> true
-    def valid?
-      registry.all?(&:valid?)
-    end
-
-    # Validates all parameters in the registry against a task instance.
-    #
-    # This method ensures that each parameter is properly defined and accessible
-    # on the provided task, including nested parameters through recursive validation.
-    #
-    # @param task [Task] the task instance to validate parameters against
-    #
-    # @return [void]
-    #
-    # @raise [NoMethodError] if a parameter method is not defined on the task
-    #
-    # @example Validate parameters against a task
-    #   registry.validate!(task_instance)
-    def validate!(task)
-      registry.each { |p| recursive_validate!(task, p) }
-    end
-
-    # Converts the parameter registry to a hash representation.
-    #
-    # @return [Array<Hash>] array of parameter hash representations
-    #
-    # @example Convert registry to hash
-    #   registry.to_h #=> [{name: :user_id, type: :integer}, {name: :email, type: :string}]
-    def to_h
-      registry.map(&:to_h)
-    end
-
-    # Converts the parameter registry to a string representation.
-    #
-    # @return [String] string representation of all parameters, joined by newlines
-    #
-    # @example Convert registry to string
-    #   registry.to_s #=> "user_id: integer\nemail: string"
-    def to_s
-      registry.map(&:to_s).join("\n")
-    end
-
-    private
-
-    # Recursively validates a parameter and its children against a task.
-    #
-    # @param task [Task] the task instance to validate the parameter against
-    # @param parameter [Parameter] the parameter to validate
-    #
-    # @return [void]
-    #
-    # @raise [NoMethodError] if the parameter method is not defined on the task
-    def recursive_validate!(task, parameter)
-      task.send(parameter.method_name) # Make sure parameter is defined on task
-      parameter.children.each { |child| recursive_validate!(task, child) }
-    end
-
-  end
-end

data/lib/cmdx/parameter_serializer.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Parameter serialization utilities for converting parameter objects to hash representations.
-  #
-  # ParameterSerializer provides functionality to convert parameter definition objects
-  # into structured hash format for serialization, introspection, and data exchange.
-  # It extracts essential parameter metadata including source context, method names,
-  # type information, requirement status, options, and nested child parameters.
-  module ParameterSerializer
-
-    module_function
-
-    # Converts a parameter object into a hash representation for serialization.
-    #
-    # This method extracts key metadata from a parameter definition and structures
-    # it into a hash format suitable for serialization, storage, or transmission.
-    # Child parameters are recursively serialized to maintain nested structure.
-    #
-    # @param parameter [CMDx::Parameter] the parameter object to serialize
-    #
-    # @return [Hash] a hash containing the parameter's metadata and configuration
-    # @option return [Symbol] :source the source context for parameter resolution
-    # @option return [Symbol] :name the method name generated for this parameter
-    # @option return [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
-    # @option return [Boolean] :required whether the parameter is required for execution
-    # @option return [Hash] :options the parameter configuration options
-    # @option return [Array<Hash>] :children serialized child parameters for nested structures
-    #
-    # @example Serialize a nested parameter with children
-    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash) do
-    #     required :name, type: :string
-    #     optional :age, type: :integer
-    #   end
-    #   ParameterSerializer.call(user_param)
-    #   #=> {
-    #   #   source: :context,
-    #   #   name: :user,
-    #   #   type: :hash,
-    #   #   required: false,
-    #   #   options: {},
-    #   #   children: [
-    #   #     { source: :user, name: :name, type: :string, required: true, options: {}, children: [] },
-    #   #     { source: :user, name: :age, type: :integer, required: false, options: {}, children: [] }
-    #   #   ]
-    #   # }
-    def call(parameter)
-      {
-        source: parameter.method_source,
-        name: parameter.method_name,
-        type: parameter.type,
-        required: parameter.required?,
-        options: parameter.options,
-        children: parameter.children.map(&:to_h)
-      }
-    end
-
-  end
-end

data/lib/cmdx/result_ansi.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # ANSI color formatting utilities for result states and statuses.
-  #
-  # This module provides functionality to apply appropriate ANSI colors to
-  # result states and statuses for enhanced terminal output visibility.
-  # It maps different execution states and statuses to their corresponding
-  # colors and delegates the actual color application to the AnsiColor utility.
-  module ResultAnsi
-
-    STATE_COLORS = {
-      Result::INITIALIZED => :blue,     # Initial state - blue
-      Result::EXECUTING => :yellow,     # Currently executing - yellow
-      Result::COMPLETE => :green,       # Successfully completed - green
-      Result::INTERRUPTED => :red       # Execution interrupted - red
-    }.freeze
-    STATUS_COLORS = {
-      Result::SUCCESS => :green,        # Successful completion - green
-      Result::SKIPPED => :yellow,       # Intentionally skipped - yellow
-      Result::FAILED => :red            # Failed execution - red
-    }.freeze
-
-    module_function
-
-    # Applies ANSI color formatting to a result state or status string.
-    #
-    # Takes a result state or status string and applies the appropriate ANSI
-    # color formatting using the predefined color mappings. This provides
-    # visual distinction for different execution outcomes in terminal output.
-    #
-    # @param s [String] the result state or status string to colorize
-    #
-    # @return [String] the input string with ANSI color codes applied
-    #
-    # @example Colorize a success status
-    #   ResultAnsi.call("success") #=> "\e[0;32;49msuccess\e[0m" (green)
-    #
-    # @example Colorize a failed status
-    #   ResultAnsi.call("failed") #=> "\e[0;31;49mfailed\e[0m" (red)
-    #
-    # @example Colorize an executing state
-    #   ResultAnsi.call("executing") #=> "\e[0;33;49mexecuting\e[0m" (yellow)
-    def call(s)
-      Utils::AnsiColor.call(s, color: color(s))
-    end
-
-    # Determines the appropriate color for a result state or status.
-    #
-    # Looks up the color mapping for the given state or status string,
-    # returning the corresponding color symbol or :default if no specific
-    # mapping is found.
-    #
-    # @param s [String] the result state or status string to find color for
-    #
-    # @return [Symbol] the color symbol (:blue, :yellow, :green, :red, or :default)
-    #
-    # @example Get color for success status
-    #   ResultAnsi.color("success") #=> :green
-    #
-    # @example Get color for unknown value
-    #   ResultAnsi.color("unknown") #=> :default
-    #
-    # @example Get color for executing state
-    #   ResultAnsi.color("executing") #=> :yellow
-    def color(s)
-      STATE_COLORS[s] || STATUS_COLORS[s] || :default
-    end
-
-  end
-end

data/lib/cmdx/result_inspector.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Result inspection and formatting utilities for readable result representation.
-  #
-  # This module provides functionality to format result metadata into human-readable
-  # strings for debugging, logging, and introspection purposes. It processes result
-  # hashes and displays essential result information in a structured, ordered format
-  # that emphasizes the most important attributes first.
-  module ResultInspector
-
-    ORDERED_KEYS = %i[
-      class type index id state status outcome metadata
-      tags pid runtime caused_failure threw_failure
-    ].freeze
-
-    module_function
-
-    # Formats a result hash into a human-readable string representation.
-    #
-    # This method converts result metadata into a structured string format that
-    # displays key result information in a predefined order. It handles special
-    # formatting for class names, failure references, and standard key-value pairs.
-    # The method filters the result hash to only include keys defined in ORDERED_KEYS
-    # and applies appropriate formatting based on the key type.
-    #
-    # @param result [Hash] the result hash to format
-    # @option result [String] :class the class name of the task or workflow
-    # @option result [String] :type the type identifier (e.g., "Task", "Workflow")
-    # @option result [Integer] :index the position index in the execution chain
-    # @option result [String] :id the unique identifier of the result
-    # @option result [String] :state the execution state (e.g., "executed", "skipped")
-    # @option result [String] :status the execution status (e.g., "success", "failure")
-    # @option result [String] :outcome the overall outcome (e.g., "good", "bad")
-    # @option result [Hash] :metadata additional metadata associated with the result
-    # @option result [Array] :tags the tags associated with the result
-    # @option result [Integer] :pid the process ID if applicable
-    # @option result [Float] :runtime the execution runtime in seconds
-    # @option result [Hash] :caused_failure reference to a failure this result caused
-    # @option result [Hash] :threw_failure reference to a failure this result threw
-    #
-    # @return [String] a formatted string representation of the result with key information
-    #
-    # @example Format a successful task result
-    #   result = MyTask.call
-    #   ResultInspector.call(result)
-    #   #=> "MyTask: type=Task index=0 id=abc123 state=executed status=success outcome=good"
-    #
-    # @example Format a result with failure reference
-    #   result = MyTask.call
-    #   ResultInspector.call(result)
-    #   #=> "MyTask: index=1 state=executed status=failure caused_failure=<[2] ValidationError: def456>"
-    def call(result)
-      ORDERED_KEYS.filter_map do |key|
-        next unless result.key?(key)
-
-        value = result[key]
-
-        case key
-        when :class
-          "#{value}:"
-        when :caused_failure, :threw_failure
-          "#{key}=<[#{value[:index]}] #{value[:class]}: #{value[:id]}>"
-        else
-          "#{key}=#{value}"
-        end
-      end.join(" ")
-    end
-
-  end
-end

data/lib/cmdx/result_logger.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Logger utilities for task execution results.
-  #
-  # This module provides functionality to log task execution results with
-  # appropriate severity levels based on the result status. It automatically
-  # determines the correct log level (info, warn, error) based on whether
-  # the task succeeded, was skipped, or failed, and delegates to the task's
-  # configured logger instance.
-  module ResultLogger
-
-    STATUS_TO_SEVERITY = {
-      Result::SUCCESS => :info,   # Successful task completion
-      Result::SKIPPED => :warn,   # Task was skipped
-      Result::FAILED => :error    # Task execution failed
-    }.freeze
-
-    module_function
-
-    # Logs a task execution result with the appropriate severity level.
-    #
-    # Retrieves the logger from the task instance and logs the result object
-    # using the severity level determined by the result's status. If no logger
-    # is configured for the task, the method returns early without logging.
-    # The logger level is temporarily set to match the severity to ensure
-    # the message is captured regardless of current log level configuration.
-    #
-    # @param result [CMDx::Result] the task execution result to log
-    #
-    # @return [void]
-    #
-    # @example Log a successful task result
-    #   task = ProcessDataTask.call(data: "input")
-    #   ResultLogger.call(task.result)
-    #   # Logs at :info level: "Result: ProcessDataTask completed successfully"
-    #
-    # @example Log a failed task result
-    #   task = ValidateDataTask.call(data: "invalid")
-    #   ResultLogger.call(task.result)
-    #   # Logs at :error level: "Result: ValidateDataTask failed with error"
-    #
-    # @example Log a skipped task result
-    #   task = ConditionalTask.call(condition: false)
-    #   ResultLogger.call(task.result)
-    #   # Logs at :warn level: "Result: ConditionalTask was skipped"
-    def call(result)
-      logger = result.task.send(:logger)
-      return if logger.nil?
-
-      severity = STATUS_TO_SEVERITY[result.status]
-
-      logger.with_level(severity) do
-        logger.send(severity) { result }
-      end
-    end
-
-  end
-end