cmdx 1.1.2 → 1.5.0

data/lib/cmdx/task_processor.rb

@@ -1,246 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Core task execution processor handling the complete task lifecycle.
-  #
-  # TaskProcessor manages the execution pipeline for individual tasks, coordinating
-  # parameter validation, callback invocation, error handling, and result state
-  # management. It provides both safe execution (capturing exceptions) and unsafe
-  # execution (re-raising exceptions) modes through call and call! methods respectively.
-  # The processor ensures proper state transitions, handles fault propagation, and
-  # maintains execution context throughout the task lifecycle.
-  class TaskProcessor
-
-    # @return [CMDx::Task] The task instance being executed
-    attr_reader :task
-
-    # Creates a new task processor for the specified task instance.
-    #
-    # @param task [CMDx::Task] the task instance to process
-    #
-    # @return [TaskProcessor] a new processor instance for the task
-    #
-    # @example Create a processor for a task
-    #   task = MyTask.new(user_id: 123)
-    #   processor = TaskProcessor.new(task)
-    def initialize(task)
-      @task = task
-    end
-
-    class << self
-
-      # Executes the specified task and returns the result without raising exceptions.
-      #
-      # Creates a new processor instance and executes the task through the complete
-      # lifecycle including validation, callbacks, and error handling. Exceptions
-      # are captured in the result rather than being raised to the caller.
-      #
-      # @param task [CMDx::Task] the task instance to execute
-      #
-      # @return [CMDx::Result] the execution result containing state and status information
-      #
-      # @example Execute a task safely
-      #   task = ProcessDataTask.new(data: raw_data)
-      #   result = TaskProcessor.call(task)
-      #   puts result.status #=> "success", "failed", or "skipped"
-      def call(task)
-        new(task).call
-      end
-
-      # Executes the specified task and raises exceptions on failure.
-      #
-      # Creates a new processor instance and executes the task through the complete
-      # lifecycle. Unlike call, this method will re-raise exceptions including
-      # Fault exceptions when their status matches the task's halt configuration.
-      #
-      # @param task [CMDx::Task] the task instance to execute
-      #
-      # @return [CMDx::Result] the execution result on success
-      #
-      # @raise [CMDx::Fault] when a fault occurs with status matching task halt configuration
-      # @raise [StandardError] when unexpected errors occur during execution
-      #
-      # @example Execute a task with exception raising
-      #   task = CriticalTask.new(operation: "delete")
-      #   begin
-      #     result = TaskProcessor.call!(task)
-      #     puts "Success: #{result.status}"
-      #   rescue CMDx::Fault => e
-      #     puts "Task failed: #{e.message}"
-      #   end
-      def call!(task)
-        new(task).call!
-      end
-
-    end
-
-    # Executes the task with safe error handling and returns the result.
-    #
-    # Runs the complete task execution pipeline including parameter validation,
-    # callback invocation, and the task's call method. Captures all exceptions
-    # as result status rather than raising them, ensuring the chain continues
-    # execution. Handles both standard errors and Fault exceptions according
-    # to the task's halt configuration.
-    #
-    # @return [CMDx::Result] the execution result with captured state and status
-    #
-    # @example Safe task execution
-    #   processor = TaskProcessor.new(task)
-    #   result = processor.call
-    #   if result.success?
-    #     puts "Task completed successfully"
-    #   else
-    #     puts "Task failed: #{result.metadata[:reason]}"
-    #   end
-    def call
-      task.result.runtime do
-        before_call
-        validate_parameters
-        task.call
-      rescue UndefinedCallError => e
-        raise(e)
-      rescue Fault => e
-        if Array(task.cmd_setting(:task_halt)).include?(e.result.status)
-          # No need to clear the Chain since exception is not being re-raised
-          task.result.throw!(e.result, original_exception: e)
-        end
-      rescue StandardError => e
-        task.result.fail!(reason: "[#{e.class}] #{e.message}", original_exception: e)
-      ensure
-        task.result.executed!
-        after_call
-      end
-
-      terminate_call
-    end
-
-    # Executes the task with exception raising on halt conditions.
-    #
-    # Runs the complete task execution pipeline including parameter validation,
-    # callback invocation, and the task's call method. Unlike call, this method
-    # will re-raise Fault exceptions when their status matches the task's halt
-    # configuration, and clears the execution chain before raising.
-    #
-    # @return [CMDx::Result] the execution result on successful completion
-    #
-    # @raise [CMDx::Fault] when a fault occurs with status matching task halt configuration
-    # @raise [CMDx::UndefinedCallError] when the task's call method is not implemented
-    # @raise [StandardError] when unexpected errors occur during execution
-    #
-    # @example Task execution with exception raising
-    #   processor = TaskProcessor.new(critical_task)
-    #   begin
-    #     result = processor.call!
-    #     puts "Task succeeded"
-    #   rescue CMDx::Fault => e
-    #     puts "Critical failure: #{e.message}"
-    #     # Chain is cleared, execution stops
-    #   end
-    def call!
-      task.result.runtime do
-        before_call
-        validate_parameters
-        task.call
-      rescue UndefinedCallError => e
-        raise!(e)
-      rescue Fault => e
-        task.result.executed!
-
-        raise!(e) if Array(task.cmd_setting(:task_halt)).include?(e.result.status)
-
-        after_call # HACK: treat as NO-OP
-      else
-        task.result.executed!
-        after_call # ELSE: treat as success
-      end
-
-      terminate_call
-    end
-
-    private
-
-    # Executes pre-execution callbacks and sets the task to executing state.
-    #
-    # Invokes before_execution callbacks, transitions the result to executing
-    # state, and triggers on_executing callbacks. This method prepares the
-    # task for execution and notifies registered callbacks about the state change.
-    #
-    # @return [void]
-    def before_call
-      task.cmd_callbacks.call(task, :before_execution)
-
-      task.result.executing!
-      task.cmd_callbacks.call(task, :on_executing)
-    end
-
-    # Validates task parameters and handles validation failures.
-    #
-    # Executes parameter validation callbacks, validates all task parameters
-    # against their defined rules, and sets the task result to failed if
-    # validation errors are found. Collects all validation messages into
-    # the result metadata.
-    #
-    # @return [void]
-    def validate_parameters
-      task.cmd_callbacks.call(task, :before_validation)
-
-      task.cmd_parameters.validate!(task)
-      unless task.errors.empty?
-        task.result.fail!(
-          reason: task.errors.full_messages.join(". "),
-          messages: task.errors.messages
-        )
-      end
-
-      task.cmd_callbacks.call(task, :after_validation)
-    end
-
-    # Clears the execution chain and raises the specified exception.
-    #
-    # This method is used to clean up the execution context before
-    # re-raising exceptions, ensuring that the chain state is properly
-    # reset when execution cannot continue.
-    #
-    # @param exception [Exception] the exception to raise after clearing the chain
-    #
-    # @return [void]
-    #
-    # @raise [Exception] the provided exception after chain cleanup
-    def raise!(exception)
-      Chain.clear
-      raise(exception)
-    end
-
-    # Executes post-execution callbacks based on task result state and status.
-    #
-    # Invokes appropriate callbacks based on the task's final execution state
-    # (success, failure, etc.) and status. Handles both state-specific and
-    # status-specific callback invocation, as well as general execution
-    # completion callbacks.
-    #
-    # @return [void]
-    def after_call
-      task.cmd_callbacks.call(task, :"on_#{task.result.state}")
-      task.cmd_callbacks.call(task, :on_executed) if task.result.executed?
-
-      task.cmd_callbacks.call(task, :"on_#{task.result.status}")
-      task.cmd_callbacks.call(task, :on_good) if task.result.good?
-      task.cmd_callbacks.call(task, :on_bad) if task.result.bad?
-
-      task.cmd_callbacks.call(task, :after_execution)
-    end
-
-    # Finalizes task execution by freezing state and logging results.
-    #
-    # Applies immutability to the task instance and logs the execution
-    # result. This method ensures that the task state cannot be modified
-    # after execution and provides visibility into the execution outcome.
-    #
-    # @return [void]
-    def terminate_call
-      Immutator.call(task)
-      ResultLogger.call(task.result)
-    end
-
-  end
-end

data/lib/cmdx/task_serializer.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Task serialization module for converting task objects to hash format.
-  #
-  # TaskSerializer provides functionality to serialize task objects into a
-  # standardized hash representation that includes essential metadata about
-  # the task such as its index, chain ID, type, class, ID, and tags. The
-  # serialized format is commonly used for debugging, logging, and introspection
-  # purposes throughout the task execution pipeline.
-  module TaskSerializer
-
-    module_function
-
-    # Serializes a task object into a hash representation.
-    #
-    # Converts a task instance into a standardized hash format containing
-    # key metadata about the task's execution context and classification.
-    # The serialization includes information from the task's result, chain,
-    # and command settings to provide comprehensive task identification.
-    #
-    # @param task [CMDx::Task, CMDx::Workflow] the task or workflow object to serialize
-    #
-    # @return [Hash] a hash containing the task's metadata
-    # @option return [Integer] :index the task's position index in the execution chain
-    # @option return [String] :chain_id the unique identifier of the task's execution chain
-    # @option return [String] :type the task type, either "Task" or "Workflow"
-    # @option return [String] :class the full class name of the task
-    # @option return [String] :id the unique identifier of the task instance
-    # @option return [Array] :tags the tags associated with the task from cmd settings
-    #
-    # @raise [NoMethodError] if the task doesn't respond to required methods
-    #
-    # @example Serialize a basic task
-    #   task = ProcessDataTask.new
-    #   TaskSerializer.call(task)
-    #   #=> {
-    #   #   index: 0,
-    #   #   chain_id: "abc123",
-    #   #   type: "Task",
-    #   #   class: "ProcessDataTask",
-    #   #   id: "def456",
-    #   #   tags: []
-    #   # }
-    def call(task)
-      {
-        index: task.result.index,
-        chain_id: task.chain.id,
-        type: task.is_a?(Workflow) ? "Workflow" : "Task",
-        class: task.class.name,
-        id: task.id,
-        tags: task.cmd_setting(:tags)
-      }
-    end
-
-  end
-end

data/lib/cmdx/utils/ansi_color.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Utils
-    # Utility module for applying ANSI color and formatting codes to text.
-    #
-    # This module provides functionality to colorize and format text output
-    # using ANSI escape sequences, supporting various colors and text modes.
-    module AnsiColor
-
-      COLOR_CODES = {
-        black: 30,
-        red: 31,
-        green: 32,
-        yellow: 33,
-        blue: 34,
-        magenta: 35,
-        cyan: 36,
-        white: 37,
-        default: 39,
-        light_black: 90,
-        light_red: 91,
-        light_green: 92,
-        light_yellow: 93,
-        light_blue: 94,
-        light_magenta: 95,
-        light_cyan: 96,
-        light_white: 97
-      }.freeze
-      MODE_CODES = {
-        default: 0,
-        bold: 1,
-        dim: 2,
-        italic: 3,
-        underline: 4,
-        blink: 5,
-        blink_slow: 5,
-        blink_fast: 6,
-        invert: 7,
-        hide: 8,
-        strike: 9,
-        double_underline: 20,
-        reveal: 28,
-        overlined: 53
-      }.freeze
-
-      module_function
-
-      # Applies ANSI color and formatting to the given text value.
-      #
-      # @param value [String] the text to format with ANSI codes
-      # @param color [Symbol] the color to apply (must be a key in COLOR_CODES)
-      # @param mode [Symbol] the formatting mode to apply (must be a key in MODE_CODES)
-      #
-      # @return [String] the formatted text with ANSI escape sequences
-      #
-      # @raise [KeyError] if the specified color or mode is not found in the respective code maps
-      #
-      # @example Basic color application
-      #   AnsiColor.call("Hello", color: :red) #=> "\e[0;31;49mHello\e[0m"
-      #
-      # @example Color with formatting mode
-      #   AnsiColor.call("Warning", color: :yellow, mode: :bold) #=> "\e[1;33;49mWarning\e[0m"
-      def call(value, color:, mode: :default)
-        color_code = COLOR_CODES.fetch(color)
-        mode_code  = MODE_CODES.fetch(mode)
-
-        "\e[#{mode_code};#{color_code};49m#{value}\e[0m"
-      end
-
-    end
-  end
-end

data/lib/cmdx/utils/log_timestamp.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Utils
-    # Utility module for formatting timestamps into standardized string representations.
-    #
-    # This module provides functionality to convert Time objects into consistent
-    # ISO 8601-like formatted strings with microsecond precision, suitable for
-    # logging and timestamp display purposes.
-    module LogTimestamp
-
-      DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N"
-
-      module_function
-
-      # Formats a Time object into a standardized timestamp string.
-      #
-      # @param time [Time] the time object to format
-      #
-      # @return [String] the formatted timestamp string in ISO 8601-like format
-      #
-      # @raise [NoMethodError] if the time object doesn't respond to strftime
-      #
-      # @example Basic timestamp formatting
-      #   LogTimestamp.call(Time.now) #=> "2023-12-25T10:30:45.123456"
-      #
-      # @example With specific time
-      #   time = Time.new(2023, 12, 25, 10, 30, 45, 123456)
-      #   LogTimestamp.call(time) #=> "2023-12-25T10:30:45.123456"
-      def call(time)
-        time.strftime(DATETIME_FORMAT)
-      end
-
-    end
-  end
-end

data/lib/cmdx/utils/monotonic_runtime.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Utils
-    # Utility module for measuring execution time using monotonic clock.
-    #
-    # This module provides functionality to measure the time taken to execute
-    # a block of code using the monotonic clock, which is not affected by
-    # system clock adjustments and provides more accurate timing measurements.
-    module MonotonicRuntime
-
-      module_function
-
-      # Measures the execution time of a given block using monotonic clock.
-      #
-      # @param block [Proc] the block of code to measure execution time for
-      # @yield executes the provided block while measuring its runtime
-      #
-      # @return [Integer] the execution time in milliseconds
-      #
-      # @example Basic usage
-      #   MonotonicRuntime.call { sleep(0.1) } #=> 100 (approximately)
-      #
-      # @example Measuring database query time
-      #   MonotonicRuntime.call { User.find(1) } #=> 15 (milliseconds)
-      def call(&)
-        now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-        yield
-        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - now
-      end
-
-    end
-  end
-end

data/lib/cmdx/utils/name_affix.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module Utils
-    # Utility module for generating method names with configurable prefixes and suffixes.
-    #
-    # This module provides functionality to dynamically construct method names
-    # by applying prefixes and suffixes to a base method name, with support
-    # for custom naming through options.
-    module NameAffix
-
-      # Proc that handles affix logic - returns block result if value is true, otherwise returns value as-is.
-      AFFIX = proc do |o, &block|
-        o == true ? block.call : o
-      end.freeze
-
-      module_function
-
-      # Generates a method name with optional prefix and suffix based on source and options.
-      #
-      # @param method_name [String, Symbol] the base method name to be affixed
-      # @param source [String, Symbol] the source identifier used for generating default prefixes/suffixes
-      # @param options [Hash] configuration options for name generation
-      # @option options [String, Symbol, true] :prefix custom prefix or true for default "#{source}_"
-      # @option options [String, Symbol, true] :suffix custom suffix or true for default "_#{source}"
-      # @option options [String, Symbol] :as override the entire generated name
-      #
-      # @return [Symbol] the generated method name as a symbol
-      #
-      # @example Using default prefix and suffix
-      #   NameAffix.call("process", "user", prefix: true, suffix: true) #=> :user_process_user
-      #
-      # @example Using custom prefix
-      #   NameAffix.call("process", "user", prefix: "handle_") #=> :handle_process
-      #
-      # @example Using custom suffix
-      #   NameAffix.call("process", "user", suffix: "_data") #=> :process_data
-      #
-      # @example Overriding with custom name
-      #   NameAffix.call("process", "user", as: "custom_method") #=> :custom_method
-      def call(method_name, source, options = {})
-        options[:as] || begin
-          prefix = AFFIX.call(options[:prefix]) { "#{source}_" }
-          suffix = AFFIX.call(options[:suffix]) { "_#{source}" }
-
-          "#{prefix}#{method_name}#{suffix}".strip.to_sym
-        end
-      end
-
-    end
-  end
-end

data/lib/cmdx/validator.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Base class for implementing parameter validation functionality in task processing.
-  #
-  # Validators are used to validate parameter values against specific rules and constraints,
-  # supporting both built-in validation types and custom validation logic. All validator
-  # implementations must inherit from this class and implement the abstract call method.
-  class Validator
-
-    # Executes a validator by creating a new instance and calling it.
-    #
-    # @param value [Object] the value to be validated
-    # @param options [Hash] additional options for the validation
-    #
-    # @return [Object] the validated value if validation passes
-    #
-    # @raise [UndefinedCallError] when the validator subclass doesn't implement call
-    # @raise [ValidationError] when validation fails
-    #
-    # @example Execute a validator on a value
-    #   PresenceValidator.call("some_value") #=> "some_value"
-    #
-    # @example Execute with options
-    #   NumericValidator.call(42, greater_than: 10) #=> 42
-    def self.call(value, options = {})
-      new.call(value, options)
-    end
-
-    # Abstract method that must be implemented by validator subclasses.
-    #
-    # This method contains the actual validation logic to verify the input
-    # value meets the specified criteria. Subclasses must override this method
-    # to provide their specific validation implementation.
-    #
-    # @param value [Object] the value to be validated
-    # @param options [Hash] additional options for the validation
-    #
-    # @return [Object] the validated value if validation passes
-    #
-    # @raise [UndefinedCallError] always raised in the base class
-    # @raise [ValidationError] when validation fails in subclass implementations
-    #
-    # @example Implement in a subclass
-    #   class BlankValidator < CMDx::Validator
-    #     def call(value, options = {})
-    #       if value.nil? || value.empty?
-    #         raise ValidationError, options[:message] || "Value cannot be blank"
-    #       end
-    #     end
-    #   end
-    def call(value, options = {}) # rubocop:disable Lint/UnusedMethodArgument
-      raise UndefinedCallError, "call method not defined in #{self.class.name}"
-    end
-
-  end
-end

data/lib/generators/cmdx/templates/workflow.rb.tt

@@ -1,7 +0,0 @@
-<% module_namespacing do -%>
-  class <%= class_name %> < <%= parent_class_name %>
-
-    process # TODO
-
-  end
-<% end -%>

data/lib/generators/cmdx/workflow_generator.rb

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-
-module Cmdx
-  # Rails generator for creating CMDx workflow files.
-  #
-  # This generator creates workflow files in the app/cmds directory with proper
-  # class naming conventions and inheritance. It ensures workflow names end with
-  # "Workflow" suffix and creates files in the correct location within the Rails
-  # application structure.
-  class WorkflowGenerator < Rails::Generators::NamedBase
-
-    source_root File.expand_path("templates", __dir__)
-    check_class_collision suffix: "Workflow"
-
-    desc "Creates a workflow with the given NAME"
-
-    # Creates the workflow file from the template.
-    #
-    # Generates a new workflow file in the app/cmds directory based on the provided
-    # name. The file name is normalized to ensure it ends with "_workflow.rb" and
-    # is placed in the appropriate subdirectory structure.
-    #
-    # @return [void]
-    #
-    # @raise [Thor::Error] if the destination file cannot be created or already exists without force
-    #
-    # @example Generate a user workflow
-    #   rails generate cmdx:workflow user
-    #   #=> Creates app/cmds/user_workflow.rb
-    #
-    # @example Generate a nested workflow
-    #   rails generate cmdx:workflow admin/users
-    #   #=> Creates app/cmds/admin/users_workflow.rb
-    def copy_files
-      name = file_name.sub(/_?workflow$/i, "")
-      path = File.join("app/cmds", class_path, "#{name}_workflow.rb")
-      template("workflow.rb.tt", path)
-    end
-
-    private
-
-    # Ensures the class name ends with "Workflow" suffix.
-    #
-    # Takes the provided class name and appends "Workflow" if it doesn't already
-    # end with that suffix, ensuring consistent naming conventions across
-    # all generated workflow classes.
-    #
-    # @return [String] the class name with "Workflow" suffix
-    #
-    # @example Class name without suffix
-    #   # Given name: "User"
-    #   class_name #=> "UserWorkflow"
-    #
-    # @example Class name with suffix
-    #   # Given name: "UserWorkflow"
-    #   class_name #=> "UserWorkflow"
-    def class_name
-      @class_name ||= super.end_with?("Workflow") ? super : "#{super}Workflow"
-    end
-
-    # Determines the parent class for the generated workflow.
-    #
-    # Attempts to use ApplicationWorkflow as the parent class if it exists in the
-    # application, otherwise falls back to CMDx::Workflow as the base class.
-    # This allows applications to define their own base workflow class with
-    # common functionality.
-    #
-    # @return [Class] the parent class for the generated workflow
-    #
-    # @raise [StandardError] if neither ApplicationWorkflow nor CMDx::Workflow are available
-    #
-    # @example With ApplicationWorkflow defined
-    #   parent_class_name #=> ApplicationWorkflow
-    #
-    # @example Without ApplicationWorkflow
-    #   parent_class_name #=> CMDx::Workflow
-    def parent_class_name
-      ApplicationWorkflow
-    rescue StandardError
-      CMDx::Workflow
-    end
-
-  end
-end

data/lib/locales/ar.yml

@@ -1,35 +0,0 @@
-ar:
-  cmdx:
-    coercions:
-      into_a: "لا يمكن تحويل إلى %{type}"
-      into_an: "لا يمكن تحويل إلى %{type}"
-      into_any: "لا يمكن تحويل إلى أي من: %{values}"
-      unknown: "نوع التحويل %{type} غير معروف"
-    faults:
-      unspecified: "لم يتم تحديد سبب"
-    parameters:
-      required: "معامل مطلوب"
-      undefined: "يفوض لطريقة غير معرفة %{source}"
-    validators:
-      exclusion:
-        of: "يجب ألا يكون أحد: %{values}"
-        within: "يجب ألا يكون بين %{min} و %{max}"
-      format: "له تنسيق غير صالح"
-      inclusion:
-        of: "يجب أن يكون أحد: %{values}"
-        within: "يجب أن يكون بين %{min} و %{max}"
-      length:
-        is: "يجب أن يكون الطول %{is}"
-        is_not: "يجب ألا يكون الطول %{is_not}"
-        min: "يجب أن يكون الطول على الأقل %{min}"
-        max: "يجب أن يكون الطول على الأكثر %{max}"
-        not_within: "يجب ألا يكون الطول بين %{min} و %{max}"
-        within: "يجب أن يكون الطول بين %{min} و %{max}"
-      numeric:
-        is: "يجب أن يكون %{is}"
-        is_not: "يجب ألا يكون %{is_not}"
-        min: "يجب أن يكون على الأقل %{min}"
-        max: "يجب أن يكون على الأكثر %{max}"
-        not_within: "يجب ألا يكون بين %{min} و %{max}"
-        within: "يجب أن يكون بين %{min} و %{max}"
-      presence: "لا يمكن أن يكون فارغاً"