cmdx 1.1.2 → 1.5.0

data/lib/cmdx/logger_serializer.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Logger serialization module for converting messages and task data into structured log format.
-  #
-  # LoggerSerializer provides functionality to serialize task execution messages into a
-  # standardized hash representation suitable for logging systems. It handles both result
-  # objects and arbitrary messages, applying consistent formatting with optional ANSI
-  # colorization for terminal output. The serializer intelligently processes different
-  # message types and enriches log data with task metadata and origin information.
-  module LoggerSerializer
-
-    COLORED_KEYS = %i[
-      state status outcome
-    ].freeze
-
-    module_function
-
-    # Serializes a log message with task context into structured hash format.
-    #
-    # Converts log messages into a standardized hash representation suitable for
-    # various logging systems and output formats. When the message is a Result object,
-    # it extracts the result's hash representation and optionally applies ANSI colors
-    # to specific keys for enhanced terminal visibility. For non-result messages,
-    # it enriches the log entry with task metadata from TaskSerializer. All log
-    # entries are tagged with CMDx origin for source identification.
-    #
-    # @param severity [Symbol] the log severity level (not used in current implementation)
-    # @param time [Time] the timestamp of the log entry (not used in current implementation)
-    # @param task [CMDx::Task, CMDx::Workflow] the task or workflow instance providing context
-    # @param message [CMDx::Result, Object] the primary message content to serialize
-    # @param options [Hash] additional options for serialization behavior
-    # @option options [Boolean] :ansi_colorize whether to apply ANSI colors to result keys
-    #
-    # @return [Hash] a structured hash containing the serialized log message and metadata
-    # @option return [String] :origin always set to "CMDx" for source identification
-    # @option return [Integer] :index the task's position index in the execution chain (when message is not Result)
-    # @option return [String] :chain_id the unique identifier of the task's execution chain (when message is not Result)
-    # @option return [String] :type the task type, either "Task" or "Workflow" (when message is not Result)
-    # @option return [String] :class the full class name of the task (when message is not Result)
-    # @option return [String] :id the unique identifier of the task instance (when message is not Result)
-    # @option return [Array] :tags the tags associated with the task from cmd settings (when message is not Result)
-    # @option return [Object] :message the original message content (when message is not Result)
-    # @option return [Symbol] :state the execution state with optional ANSI colors (when message is Result)
-    # @option return [Symbol] :status the execution status with optional ANSI colors (when message is Result)
-    # @option return [Symbol] :outcome the execution outcome with optional ANSI colors (when message is Result)
-    # @option return [Hash] :metadata additional metadata from result (when message is Result)
-    # @option return [Float] :runtime execution runtime in seconds (when message is Result)
-    #
-    # @raise [NoMethodError] if task doesn't respond to required methods for TaskSerializer
-    # @raise [NoMethodError] if result message doesn't respond to to_h method
-    #
-    # @example Serialize a result message with ANSI colors
-    #   task = ProcessDataTask.call(data: "test")
-    #   LoggerSerializer.call(:info, Time.now, task, task.result, ansi_colorize: true)
-    #   #=> {
-    #   #   origin: "CMDx",
-    #   #   index: 0,
-    #   #   chain_id: "abc123",
-    #   #   type: "Task",
-    #   #   class: "ProcessDataTask",
-    #   #   id: "def456",
-    #   #   tags: [],
-    #   #   state: "\e[0;32;49mcomplete\e[0m",
-    #   #   status: "\e[0;32;49msuccess\e[0m",
-    #   #   outcome: "\e[0;32;49mgood\e[0m",
-    #   #   metadata: {},
-    #   #   runtime: 0.045
-    #   # }
-    #
-    # @example Serialize a string message with task context
-    #   task = MyTask.new(context: {data: "test"})
-    #   LoggerSerializer.call(:warn, Time.now, task, "Processing started")
-    #   #=> {
-    #   #   origin: "CMDx",
-    #   #   index: 0,
-    #   #   chain_id: "abc123",
-    #   #   type: "Task",
-    #   #   class: "MyTask",
-    #   #   id: "def456",
-    #   #   tags: [],
-    #   #   message: "Processing started"
-    #   # }
-    #
-    # @example Serialize a result message without colors
-    #   task = ValidationTask.call(email: "invalid")
-    #   LoggerSerializer.call(:error, Time.now, task, task.result)
-    #   #=> {
-    #   #   origin: "CMDx",
-    #   #   index: 1,
-    #   #   chain_id: "xyz789",
-    #   #   type: "Task",
-    #   #   class: "ValidationTask",
-    #   #   id: "ghi012",
-    #   #   tags: [],
-    #   #   state: :interrupted,
-    #   #   status: :failed,
-    #   #   outcome: :bad,
-    #   #   metadata: { reason: "Invalid email format" },
-    #   #   runtime: 0.012
-    #   # }
-    def call(severity, time, task, message, **options) # rubocop:disable Lint/UnusedMethodArgument
-      m = message.is_a?(Result) ? message.to_h : {}
-
-      if options.delete(:ansi_colorize) && message.is_a?(Result)
-        COLORED_KEYS.each { |k| m[k] = ResultAnsi.call(m[k]) if m.key?(k) }
-      elsif !message.is_a?(Result)
-        m.merge!(TaskSerializer.call(task), message: message)
-      end
-
-      m[:origin] ||= "CMDx"
-      m
-    end
-
-  end
-end

data/lib/cmdx/middleware.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Base class for implementing middleware functionality in task processing pipelines.
-  #
-  # Middleware provides a way to wrap task execution with custom logic that runs before
-  # and after task processing. Middleware can be used for cross-cutting concerns such as
-  # logging, authentication, caching, error handling, and other aspects that should be
-  # applied consistently across multiple tasks. All middleware implementations must
-  # inherit from this class and implement the abstract call method.
-  class Middleware
-
-    # Executes middleware by creating a new instance and calling it.
-    #
-    # This class method provides a convenient way to execute middleware without
-    # manually instantiating the middleware class. It creates a new instance
-    # and delegates to the instance call method with the provided arguments.
-    #
-    # @param task [CMDx::Task] the task instance being processed
-    # @param callable [Proc] the callable that executes the next middleware or task logic
-    #
-    # @return [Object] the result returned by the middleware implementation
-    #
-    # @raise [UndefinedCallError] when the middleware subclass doesn't implement call
-    #
-    # @example Execute middleware on a task
-    #   class LoggingMiddleware < CMDx::Middleware
-    #     def call(task, callable)
-    #       task.logger.info "Starting #{task.class.name}"
-    #       result = callable.call
-    #       task.logger.info "Completed #{task.class.name}"
-    #       result
-    #     end
-    #   end
-    #
-    #   LoggingMiddleware.call(my_task, -> { my_task.process })
-    def self.call(task, callable)
-      new.call(task, callable)
-    end
-
-    # Abstract method that must be implemented by middleware subclasses.
-    #
-    # This method contains the actual middleware logic that wraps task execution.
-    # Subclasses must override this method to provide their specific middleware
-    # implementation. The method should call the provided callable to continue
-    # the middleware chain or execute the task logic.
-    #
-    # @param _task [CMDx::Task] the task instance being processed
-    # @param _callable [Proc] the callable that executes the next middleware or task logic
-    #
-    # @return [Object] the result of the middleware processing
-    #
-    # @raise [UndefinedCallError] always raised in the base class
-    #
-    # @example Implement middleware in a subclass
-    #   class TimingMiddleware < CMDx::Middleware
-    #     def call(task, callable)
-    #       start_time = Time.now
-    #       result = callable.call
-    #       duration = Time.now - start_time
-    #       task.logger.info "Task completed in #{duration}s"
-    #       result
-    #     end
-    #   end
-    def call(_task, _callable)
-      raise UndefinedCallError, "call method not defined in #{self.class.name}"
-    end
-
-  end
-end

data/lib/cmdx/parameter.rb

@@ -1,312 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Parameter definition and management for task attribute configuration.
-  #
-  # Parameter provides a flexible system for defining, validating, and managing
-  # task parameters with support for type coercion, nested parameter structures,
-  # validation rules, and dynamic attribute generation. Parameters can be defined
-  # as required or optional with various configuration options including custom
-  # naming, source specification, and child parameter definitions.
-  class Parameter
-
-    cmdx_attr_delegator :invalid?, :valid?,
-                        to: :errors
-
-    # @return [CMDx::Task] The task class this parameter belongs to
-    attr_accessor :task
-
-    # @return [Class] The task class this parameter is defined in
-    attr_reader :klass
-
-    # @return [Parameter, nil] The parent parameter for nested parameters
-    attr_reader :parent
-
-    # @return [Symbol] The parameter name
-    attr_reader :name
-
-    # @return [Symbol, Array<Symbol>] The parameter type(s) for coercion
-    attr_reader :type
-
-    # @return [Hash] The parameter configuration options
-    attr_reader :options
-
-    # @return [Array<Parameter>] Child parameters for nested parameter definitions
-    attr_reader :children
-
-    # @return [CMDx::Errors] Validation errors for this parameter
-    attr_reader :errors
-
-    # Creates a new parameter definition with the specified configuration.
-    #
-    # @param name [Symbol, String] the parameter name
-    # @param options [Hash] parameter configuration options
-    # @option options [Class] :klass the task class this parameter belongs to (required)
-    # @option options [Parameter] :parent the parent parameter for nested definitions
-    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
-    # @option options [Boolean] :required whether the parameter is required for task execution
-    # @option options [Symbol] :source the source context for parameter resolution
-    # @option options [Symbol, String] :as custom method name for the parameter
-    # @option options [Hash] :validates validation rules to apply to the parameter
-    # @option options [Object] :default default value when parameter is not provided
-    # @param block [Proc] optional block for defining nested parameters
-    #
-    # @return [Parameter] a new parameter instance
-    #
-    # @raise [KeyError] if the :klass option is not provided
-    #
-    # @example Create a simple required parameter
-    #   Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
-    #
-    # @example Create parameter with validation
-    #   Parameter.new(:email, klass: MyTask, type: :string, validates: { format: /@/ })
-    #
-    # @example Create nested parameter with children
-    #   Parameter.new(:user, klass: MyTask, type: :hash) do
-    #     required :name, type: :string
-    #     optional :age, type: :integer
-    #   end
-    def initialize(name, **options, &)
-      @klass    = options.delete(:klass) || raise(KeyError, "klass option required")
-      @parent   = options.delete(:parent)
-      @type     = options.delete(:type) || :virtual
-      @required = options.delete(:required) || false
-
-      @name     = name
-      @options  = options
-      @children = []
-      @errors   = Errors.new
-
-      define_attribute(self)
-      instance_eval(&) if block_given?
-    end
-
-    class << self
-
-      # Creates one or more optional parameter definitions.
-      #
-      # @param names [Array<Symbol>] parameter names to define as optional
-      # @param options [Hash] parameter configuration options
-      # @option options [Class] :klass the task class this parameter belongs to
-      # @option options [Parameter] :parent the parent parameter for nested definitions
-      # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
-      # @option options [Symbol] :source the source context for parameter resolution
-      # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
-      # @option options [Hash] :validates validation rules to apply to the parameter
-      # @option options [Object] :default default value when parameter is not provided
-      # @param block [Proc] optional block for defining nested parameters
-      #
-      # @return [Array<Parameter>] array of created optional parameter instances
-      #
-      # @raise [ArgumentError] if no parameter names are provided
-      # @raise [ArgumentError] if :as option is used with multiple parameter names
-      #
-      # @example Define single optional parameter
-      #   Parameter.optional(:description, klass: MyTask, type: :string)
-      #
-      # @example Define multiple optional parameters
-      #   Parameter.optional(:name, :email, klass: MyTask, type: :string)
-      #
-      # @example Define optional parameter with custom name
-      #   Parameter.optional(:user_id, klass: MyTask, type: :integer, as: :current_user_id)
-      def optional(*names, **options, &)
-        if names.none?
-          raise ArgumentError, "no parameters given"
-        elsif !names.one? && options.key?(:as)
-          raise ArgumentError, ":as option only supports one parameter per definition"
-        end
-
-        names.filter_map { |n| new(n, **options, &) }
-      end
-
-      # Creates one or more required parameter definitions.
-      #
-      # @param names [Array<Symbol>] parameter names to define as required
-      # @param options [Hash] parameter configuration options
-      # @option options [Class] :klass the task class this parameter belongs to
-      # @option options [Parameter] :parent the parent parameter for nested definitions
-      # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
-      # @option options [Symbol] :source the source context for parameter resolution
-      # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
-      # @option options [Hash] :validates validation rules to apply to the parameter
-      # @option options [Object] :default default value when parameter is not provided
-      # @param block [Proc] optional block for defining nested parameters
-      #
-      # @return [Array<Parameter>] array of created required parameter instances
-      #
-      # @raise [ArgumentError] if no parameter names are provided
-      # @raise [ArgumentError] if :as option is used with multiple parameter names
-      #
-      # @example Define single required parameter
-      #   Parameter.required(:user_id, klass: MyTask, type: :integer)
-      #
-      # @example Define multiple required parameters
-      #   Parameter.required(:name, :email, klass: MyTask, type: :string)
-      #
-      # @example Define required parameter with validation
-      #   Parameter.required(:email, klass: MyTask, type: :string, validates: { format: /@/ })
-      def required(*names, **options, &)
-        optional(*names, **options.merge(required: true), &)
-      end
-
-    end
-
-    # Defines optional child parameters for nested parameter structures.
-    #
-    # @param names [Array<Symbol>] parameter names to define as optional children
-    # @param options [Hash] parameter configuration options
-    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
-    # @option options [Symbol] :source the source context for parameter resolution
-    # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
-    # @option options [Hash] :validates validation rules to apply to the parameter
-    # @option options [Object] :default default value when parameter is not provided
-    # @param block [Proc] optional block for defining nested parameters
-    #
-    # @return [Array<Parameter>] array of created optional child parameter instances
-    #
-    # @raise [ArgumentError] if no parameter names are provided
-    # @raise [ArgumentError] if :as option is used with multiple parameter names
-    #
-    # @example Define optional child parameters
-    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash)
-    #   user_param.optional(:description, :bio, type: :string)
-    def optional(*names, **options, &)
-      parameters = Parameter.optional(*names, **options.merge(klass: @klass, parent: self), &)
-      children.concat(parameters)
-    end
-
-    # Defines required child parameters for nested parameter structures.
-    #
-    # @param names [Array<Symbol>] parameter names to define as required children
-    # @param options [Hash] parameter configuration options
-    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
-    # @option options [Symbol] :source the source context for parameter resolution
-    # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
-    # @option options [Hash] :validates validation rules to apply to the parameter
-    # @option options [Object] :default default value when parameter is not provided
-    # @param block [Proc] optional block for defining nested parameters
-    #
-    # @return [Array<Parameter>] array of created required child parameter instances
-    #
-    # @raise [ArgumentError] if no parameter names are provided
-    # @raise [ArgumentError] if :as option is used with multiple parameter names
-    #
-    # @example Define required child parameters
-    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash)
-    #   user_param.required(:name, :email, type: :string)
-    def required(*names, **options, &)
-      parameters = Parameter.required(*names, **options.merge(klass: @klass, parent: self), &)
-      children.concat(parameters)
-    end
-
-    # Checks if the parameter is marked as required for task execution.
-    #
-    # @return [Boolean] true if the parameter is required, false otherwise
-    #
-    # @example Check if parameter is required
-    #   param = Parameter.new(:name, klass: MyTask, required: true)
-    #   param.required? #=> true
-    def required?
-      !!@required
-    end
-
-    # Checks if the parameter is marked as optional for task execution.
-    #
-    # @return [Boolean] true if the parameter is optional, false otherwise
-    #
-    # @example Check if parameter is optional
-    #   param = Parameter.new(:description, klass: MyTask, required: false)
-    #   param.optional? #=> true
-    def optional?
-      !required?
-    end
-
-    # Generates the method name that will be created on the task class for this parameter.
-    #
-    # @return [Symbol] the method name with any configured prefix, suffix, or custom naming
-    #
-    # @example Get method name for simple parameter
-    #   param = Parameter.new(:user_id, klass: MyTask)
-    #   param.method_name #=> :user_id
-    #
-    # @example Get method name with custom naming
-    #   param = Parameter.new(:user_id, klass: MyTask, as: :current_user_id)
-    #   param.method_name #=> :current_user_id
-    def method_name
-      @method_name ||= Utils::NameAffix.call(name, method_source, options)
-    end
-
-    # Determines the source context for parameter resolution and method name generation.
-    #
-    # @return [Symbol] the source identifier used for parameter resolution
-    #
-    # @example Get method source for simple parameter
-    #   param = Parameter.new(:user_id, klass: MyTask)
-    #   param.method_source #=> :context
-    #
-    # @example Get method source for nested parameter
-    #   parent = Parameter.new(:user, klass: MyTask)
-    #   child = Parameter.new(:name, klass: MyTask, parent: parent)
-    #   child.method_source #=> :user
-    def method_source
-      @method_source ||= options[:source] || parent&.method_name || :context
-    end
-
-    # Converts the parameter to a hash representation for serialization.
-    #
-    # @return [Hash] hash containing all parameter metadata and configuration
-    #
-    # @example Convert parameter to hash
-    #   param = Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
-    #   param.to_h
-    #   #=> { name: :user_id, type: :integer, required: true, ... }
-    def to_h
-      ParameterSerializer.call(self)
-    end
-
-    # Converts the parameter to a formatted string representation for inspection.
-    #
-    # @return [String] human-readable string representation of the parameter
-    #
-    # @example Convert parameter to string
-    #   param = Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
-    #   param.to_s
-    #   #=> "Parameter: name=user_id type=integer required=true ..."
-    def to_s
-      ParameterInspector.call(to_h)
-    end
-
-    private
-
-    # Dynamically defines a method on the task class for parameter value access.
-    #
-    # @param parameter [Parameter] the parameter to create a method for
-    #
-    # @return [void]
-    #
-    # @example Define parameter method on task class
-    #   # Creates a private method that evaluates and caches parameter values
-    #   # with automatic error handling for coercion and validation failures
-    def define_attribute(parameter)
-      klass.send(:define_method, parameter.method_name) do
-        @cmd_parameter_value_cache ||= {}
-
-        unless @cmd_parameter_value_cache.key?(parameter.method_name)
-          begin
-            parameter_value = ParameterEvaluator.call(self, parameter)
-          rescue CoercionError, ValidationError => e
-            parameter.errors.add(parameter.method_name, e.message)
-            errors.merge!(parameter.errors.to_hash)
-          ensure
-            @cmd_parameter_value_cache[parameter.method_name] = parameter_value
-          end
-        end
-
-        @cmd_parameter_value_cache[parameter.method_name]
-      end
-
-      klass.send(:private, parameter.method_name)
-    end
-
-  end
-end