cmdx 1.20.0 → 2.0.0

data/lib/cmdx/inputs.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of declared task inputs. Each registration creates an {Input} and
+  # defines a reader method on the task class. {#resolve} walks every input
+  # (and nested children) to populate the task's instance variables before `work`.
+  class Inputs
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {}
+    end
+
+    # @param source [Inputs] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Declares one or more inputs and defines accessor readers on `klass`.
+    # A block nests child inputs under each declared name (see {ChildBuilder}).
+    #
+    # @param klass [Class] the task class to define readers on
+    # @param names [Array<Symbol>] input names
+    # @param block [#call, nil] nested-input DSL (see {ChildBuilder})
+    # @param options [Hash{Symbol => Object}] passed to {Input#initialize}
+    # @option options [String] :description (also accepts `:desc`)
+    # @option options [Symbol] :as overrides the accessor name
+    # @option options [Boolean, String] :prefix prefix for the accessor name
+    # @option options [Boolean, String] :suffix suffix for the accessor name
+    # @option options [Symbol, Proc, #call] :source (`:context`) where to fetch from
+    # @option options [Object, Symbol, Proc, #call] :default
+    # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
+    # @option options [Symbol, Proc, #call] :if
+    # @option options [Symbol, Proc, #call] :unless
+    # @option options [Boolean] :required
+    # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
+    # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
+    # @return [Inputs] self for chaining
+    # @yield block evaluated in a {ChildBuilder} for nested inputs
+    def register(klass, *names, **options, &block)
+      children = block ? ChildBuilder.build(&block) : EMPTY_ARRAY
+
+      names.each do |name|
+        input = Input.new(name, children:, **options)
+        registry[input.name] = input
+        klass.send(:define_input_reader, input)
+      end
+
+      self
+    end
+
+    # Removes inputs and their accessor readers from `klass`.
+    #
+    # @param klass [Class]
+    # @param names [Array<Symbol>]
+    # @return [Inputs] self for chaining
+    def deregister(klass, *names)
+      names.each do |name|
+        input = registry.delete(name.to_sym)
+        klass.send(:undefine_input_reader, input)
+      end
+
+      self
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+    # Resolves every input (with children) for `task`, setting each input's
+    # computed value into its backing ivar so the generated readers return it.
+    #
+    # @param task [Task]
+    # @return [void]
+    def resolve(task)
+      registry.each_value do |input|
+        value = input.resolve(task)
+        task.instance_variable_set(input.ivar_name, value)
+        resolve_children(input, value, task)
+      end
+    end
+
+    private
+
+    # @param input [Input] parent input whose children should be resolved
+    # @param parent_value [Object] resolved parent value child inputs read from
+    # @param task [Task]
+    # @return [void]
+    def resolve_children(input, parent_value, task)
+      return if input.children.empty? || parent_value.nil?
+
+      input.children.each do |child|
+        child_value = child.resolve_from_parent(parent_value, task)
+        task.instance_variable_set(child.ivar_name, child_value)
+        resolve_children(child, child_value, task)
+      end
+    end
+
+    # DSL receiver for the block passed to {Inputs#register}. Builds a frozen
+    # list of child {Input}s. Supports arbitrary nesting: every DSL method
+    # accepts its own block.
+    class ChildBuilder
+
+      class << self
+
+        # @yield (see Inputs#register)
+        # @return [Array<Input>] frozen list of built children
+        def build(&)
+          builder = new
+          builder.instance_eval(&)
+          builder.children.freeze
+        end
+
+      end
+
+      attr_reader :children
+
+      def initialize
+        @children = []
+      end
+
+      # @param names [Array<Symbol>]
+      # @param options [Hash{Symbol => Object}] forwarded to {Input#initialize}
+      # @option options [String] :description (also accepts `:desc`)
+      # @option options [Symbol] :as overrides the accessor name
+      # @option options [Boolean, String] :prefix prefix for the accessor name
+      # @option options [Boolean, String] :suffix suffix for the accessor name
+      # @option options [Symbol, Proc, #call] :source (`:context`) where to fetch from
+      # @option options [Object, Symbol, Proc, #call] :default
+      # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
+      # @option options [Symbol, Proc, #call] :if
+      # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :required
+      # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
+      # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
+      # @yield nested child input DSL
+      # @return [Array<Input>]
+      def inputs(*names, **options, &)
+        build(*names, **options, &)
+      end
+      alias input inputs
+
+      # Declares optional child inputs (equivalent to `inputs ..., required: false`).
+      # @param names [Array<Symbol>]
+      # @param options [Hash{Symbol => Object}] forwarded to {Input#initialize}
+      # @option options [String] :description (also accepts `:desc`)
+      # @option options [Symbol] :as overrides the accessor name
+      # @option options [Boolean, String] :prefix prefix for the accessor name
+      # @option options [Boolean, String] :suffix suffix for the accessor name
+      # @option options [Symbol, Proc, #call] :source (`:context`) where to fetch from
+      # @option options [Object, Symbol, Proc, #call] :default
+      # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
+      # @option options [Symbol, Proc, #call] :if
+      # @option options [Symbol, Proc, #call] :unless
+      # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
+      # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
+      # @yield nested child input DSL
+      # @return [Array<Input>]
+      def optional(*names, **options, &)
+        build(*names, required: false, **options, &)
+      end
+
+      # Declares required child inputs (equivalent to `inputs ..., required: true`).
+      # @param names [Array<Symbol>]
+      # @param options [Hash{Symbol => Object}] forwarded to {Input#initialize}
+      # @option options [String] :description (also accepts `:desc`)
+      # @option options [Symbol] :as overrides the accessor name
+      # @option options [Boolean, String] :prefix prefix for the accessor name
+      # @option options [Boolean, String] :suffix suffix for the accessor name
+      # @option options [Symbol, Proc, #call] :source (`:context`) where to fetch from
+      # @option options [Object, Symbol, Proc, #call] :default
+      # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
+      # @option options [Symbol, Proc, #call] :if
+      # @option options [Symbol, Proc, #call] :unless
+      # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
+      # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
+      # @yield nested child input DSL
+      # @return [Array<Input>]
+      def required(*names, **options, &)
+        build(*names, required: true, **options, &)
+      end
+
+      private
+
+      # @param names [Array<Symbol>]
+      # @param block [#call, nil]
+      # @param options [Hash{Symbol => Object}] forwarded to {Input#initialize}
+      # @option options [String] :description (also accepts `:desc`)
+      # @option options [Symbol] :as overrides the accessor name
+      # @option options [Boolean, String] :prefix prefix for the accessor name
+      # @option options [Boolean, String] :suffix suffix for the accessor name
+      # @option options [Symbol, Proc, #call] :source (`:context`) where to fetch from
+      # @option options [Object, Symbol, Proc, #call] :default
+      # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
+      # @option options [Symbol, Proc, #call] :if
+      # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :required
+      # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
+      # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
+      # @return [Array<Input>]
+      # @yield nested child input DSL
+      def build(*names, **options, &block)
+        nested = block ? self.class.build(&block) : EMPTY_ARRAY
+        names.map { |name| children << Input.new(name, children: nested, **options) }
+      end
+
+    end
+
+  end
+end

data/lib/cmdx/log_formatters/json.rb

@@ -2,34 +2,23 @@
 
 module CMDx
   module LogFormatters
-    # Formats log messages as JSON for structured logging
-    #
-    # This formatter converts log entries into JSON format with standardized fields
-    # including severity, timestamp, program name, process ID, and formatted message.
-    # The output is suitable for log aggregation systems and structured analysis.
+    # `Logger` formatter that emits one JSON object per line with `severity`,
+    # ISO8601 `timestamp`, `progname`, `pid`, and `message` (rendered via
+    # `#to_h` when available — Result instances serialize themselves).
     class JSON
 
-      # Formats a log entry as a JSON string
-      #
-      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
-      # @param time [Time] The timestamp when the log entry was created
-      # @param progname [String, nil] The program name or identifier
-      # @param message [Object] The log message content
-      #
-      # @return [String] A JSON-formatted log entry with a trailing newline
-      #
-      # @example Basic usage
-      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
-      #   # => '{"severity":"INFO","timestamp":"2024-01-15T10:30:45.123456Z","progname":"MyApp","pid":12345,"message":"User logged in"}\n'
-      #
-      # @rbs (String severity, Time time, String? progname, String message) -> String
+      # @param severity [String] Logger severity name
+      # @param time [Time]
+      # @param progname [String, nil]
+      # @param message [Object] anything `Logger` was handed
+      # @return [String] JSON line terminated by `"\n"`
       def call(severity, time, progname, message)
         hash = {
           severity:,
           timestamp: time.utc.iso8601(6),
           progname:,
           pid: Process.pid,
-          message: Utils::Format.to_log(message)
+          message: message.respond_to?(:to_h) ? message.to_h : message
         }
 
         ::JSON.dump(hash) << "\n"

data/lib/cmdx/log_formatters/key_value.rb

@@ -2,37 +2,26 @@
 
 module CMDx
   module LogFormatters
-    # Formats log messages as key-value pairs for structured logging
-    #
-    # This formatter converts log entries into key-value format with standardized fields
-    # including severity, timestamp, program name, process ID, and formatted message.
-    # The output is suitable for log parsing tools and human-readable structured logs.
+    # `Logger` formatter that emits `key=value.inspect` pairs on a single
+    # line. Hash-like messages (including Result) are flattened into the
+    # top-level `message` field via `#to_h`.
     class KeyValue
 
-      # Formats a log entry as a key-value string
-      #
-      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
-      # @param time [Time] The timestamp when the log entry was created
-      # @param progname [String, nil] The program name or identifier
-      # @param message [Object] The log message content
-      #
-      # @return [String] A key-value formatted log entry with a trailing newline
-      #
-      # @example Basic usage
-      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
-      #   # => "severity=INFO timestamp=2024-01-15T10:30:45.123456Z progname=MyApp pid=12345 message=User logged in\n"
-      #
-      # @rbs (String severity, Time time, String? progname, String message) -> String
+      # @param severity [String] Logger severity name
+      # @param time [Time]
+      # @param progname [String, nil]
+      # @param message [Object]
+      # @return [String] single-line key=value line terminated by `"\n"`
       def call(severity, time, progname, message)
         hash = {
           severity:,
           timestamp: time.utc.iso8601(6),
           progname:,
           pid: Process.pid,
-          message: Utils::Format.to_log(message)
+          message: message.respond_to?(:to_h) ? message.to_h : message
         }
 
-        Utils::Format.to_str(hash) << "\n"
+        hash.map { |k, v| "#{k}=#{v.inspect}" }.join(" ") << "\n"
       end
 
     end

data/lib/cmdx/log_formatters/line.rb

@@ -2,27 +2,15 @@
 
 module CMDx
   module LogFormatters
-    # Formats log messages as single-line text for human-readable logging
-    #
-    # This formatter converts log entries into a compact single-line format with
-    # severity abbreviation, ISO8601 timestamp, process ID, and formatted message.
-    # The output is optimized for human readability and traditional log file formats.
+    # Default formatter. Emits a human-readable single-line log entry that
+    # mirrors Ruby's built-in `Logger::Formatter` style.
     class Line
 
-      # Formats a log entry as a single-line string
-      #
-      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
-      # @param time [Time] The timestamp when the log entry was created
-      # @param progname [String, nil] The program name or identifier
-      # @param message [Object] The log message content
-      #
-      # @return [String] A single-line formatted log entry with a trailing newline
-      #
-      # @example Basic usage
-      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
-      #   # => "I, [2024-01-15T10:30:45.123456Z #12345] INFO -- MyApp: User logged in\n"
-      #
-      # @rbs (String severity, Time time, String? progname, String message) -> String
+      # @param severity [String] Logger severity name
+      # @param time [Time]
+      # @param progname [String, nil]
+      # @param message [Object]
+      # @return [String] formatted line terminated by `"\n"`
       def call(severity, time, progname, message)
         "#{severity[0]}, [#{time.utc.iso8601(6)} ##{Process.pid}] #{severity} -- #{progname}: #{message}\n"
       end

data/lib/cmdx/log_formatters/logstash.rb

@@ -2,34 +2,21 @@
 
 module CMDx
   module LogFormatters
-    # Formats log messages as Logstash-compatible JSON for structured logging
-    #
-    # This formatter converts log entries into Logstash-compatible JSON format with
-    # standardized fields including @version, @timestamp, severity, program name,
-    # process ID, and formatted message. The output follows Logstash event format
-    # specifications for seamless integration with ELK stack and similar systems.
+    # `Logger` formatter that produces one JSON line per entry in the shape
+    # expected by Logstash (`@version` + `@timestamp`).
     class Logstash
 
-      # Formats a log entry as a Logstash-compatible JSON string
-      #
-      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
-      # @param time [Time] The timestamp when the log entry was created
-      # @param progname [String, nil] The program name or identifier
-      # @param message [Object] The log message content
-      #
-      # @return [String] A Logstash-compatible JSON-formatted log entry with a trailing newline
-      #
-      # @example Basic usage
-      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
-      #   # => '{"severity":"INFO","progname":"MyApp","pid":12345,"message":"User logged in","@version":"1","@timestamp":"2024-01-15T10:30:45.123456Z"}\n'
-      #
-      # @rbs (String severity, Time time, String? progname, String message) -> String
+      # @param severity [String] Logger severity name
+      # @param time [Time]
+      # @param progname [String, nil]
+      # @param message [Object]
+      # @return [String] JSON line terminated by `"\n"`
       def call(severity, time, progname, message)
         hash = {
           severity:,
           progname:,
           pid: Process.pid,
-          message: Utils::Format.to_log(message),
+          message: message.respond_to?(:to_h) ? message.to_h : message,
           "@version" => "1",
           "@timestamp" => time.utc.iso8601(6)
         }

data/lib/cmdx/log_formatters/raw.rb

@@ -2,28 +2,16 @@
 
 module CMDx
   module LogFormatters
-    # Formats log messages as raw text without additional formatting
-    #
-    # This formatter outputs log messages in their original form with minimal
-    # processing, adding only a trailing newline. It's useful for scenarios
-    # where you want to preserve the exact message content without metadata
-    # or structured formatting.
+    # Passthrough formatter that writes only the message (terminated with
+    # `"\n"`). Useful when surrounding infrastructure already supplies
+    # severity and timestamp.
     class Raw
 
-      # Formats a log entry as raw text
-      #
-      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
-      # @param time [Time] The timestamp when the log entry was created
-      # @param progname [String, nil] The program name or identifier
-      # @param message [Object] The log message content
-      #
-      # @return [String] The raw message with a trailing newline
-      #
-      # @example Basic usage
-      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
-      #   # => "User logged in\n"
-      #
-      # @rbs (String severity, Time time, String? progname, String message) -> String
+      # @param severity [String] ignored
+      # @param time [Time] ignored
+      # @param progname [String, nil] ignored
+      # @param message [Object]
+      # @return [String] `"#{message}\n"`
       def call(severity, time, progname, message)
         "#{message}\n"
       end

data/lib/cmdx/logger_proxy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Returns a logger tailored to a task's settings. If the task overrides
+  # `log_level` or `log_formatter`, the base logger is `dup`'d so those
+  # overrides don't leak into sibling tasks sharing the same global logger.
+  module LoggerProxy
+
+    extend self
+
+    # @param task [Task]
+    # @return [Logger] a logger configured with the task's level/formatter
+    def logger(task)
+      settings  = task.class.settings
+      logger    = settings.logger
+      level     = settings.log_level
+      formatter = settings.log_formatter
+
+      change_level     = level && level != logger.level
+      change_formatter = formatter && !logger.formatter.equal?(formatter)
+      return logger unless change_level || change_formatter
+
+      logger = logger.dup
+      logger.level     = level     if change_level
+      logger.formatter = formatter if change_formatter
+      logger
+    end
+
+  end
+end

data/lib/cmdx/mergers/deep_merge.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Mergers
+    # Recursively merges `Hash` values from the parallel task's context into
+    # the workflow context. Scalar-vs-hash collisions still follow
+    # last-write-wins.
+    #
+    # @api private
+    module DeepMerge
+
+      extend self
+
+      # @param ctx [Context] workflow context being folded into
+      # @param result [Result] successful parallel task result
+      # @return [void]
+      def call(ctx, result)
+        ctx.deep_merge(result.context)
+      end
+
+    end
+  end
+end

data/lib/cmdx/mergers/last_write_wins.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Mergers
+    # Default merger. Shallow-merges the parallel task's context into the
+    # workflow context via `Hash#merge` semantics; on key conflicts, the
+    # later-declared task wins.
+    #
+    # @api private
+    module LastWriteWins
+
+      extend self
+
+      # @param ctx [Context] workflow context being folded into
+      # @param result [Result] successful parallel task result
+      # @return [void]
+      def call(ctx, result)
+        ctx.merge(result.context)
+      end
+
+    end
+  end
+end

data/lib/cmdx/mergers/no_merge.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Mergers
+    # No-op merger. Leaves the workflow context untouched; per-task results
+    # remain inspectable via `result.chain`.
+    #
+    # @api private
+    module NoMerge
+
+      extend self
+
+      # @param _ctx [Context] ignored
+      # @param _result [Result] ignored
+      # @return [void]
+      def call(_ctx, _result); end
+
+    end
+  end
+end

data/lib/cmdx/mergers.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of named merge strategies used to fold successful parallel task
+  # results back into the workflow context. Ships with built-ins for
+  # `:last_write_wins` (default), `:deep_merge`, and `:no_merge`. A merger is
+  # any callable accepting `call(workflow_context, result)`.
+  class Mergers
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {
+        last_write_wins: Mergers::LastWriteWins,
+        deep_merge: Mergers::DeepMerge,
+        no_merge: Mergers::NoMerge
+      }
+    end
+
+    # @param source [Mergers] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Registers a named merger, overwriting any existing entry.
+    #
+    # @param name [Symbol]
+    # @param callable [#call, nil] pass either this or a block
+    # @param block [#call, nil] merger callable when `callable` is omitted
+    # @yield merger body — `call(workflow_context, result)`
+    # @return [Mergers] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are given, or
+    #   when the resolved merger isn't callable
+    def register(name, callable = nil, &block)
+      merger = callable || block
+
+      if callable && block
+        raise ArgumentError, "provide either a callable or a block, not both"
+      elsif !merger.respond_to?(:call)
+        raise ArgumentError, "merger must respond to #call"
+      end
+
+      registry[name.to_sym] = merger
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Mergers] self for chaining
+    def deregister(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [#call] the registered merger
+    # @raise [ArgumentError] when `name` isn't registered
+    def lookup(name)
+      registry[name] || begin
+        raise ArgumentError, "unknown merger: #{name.inspect}"
+      end
+    end
+
+    # Resolves a declaration's `:merger` option to a concrete
+    # callable. Accepts `nil` (default `:last_write_wins`), a Symbol
+    # (registry lookup), or any object responding to `#call`.
+    #
+    # @param spec [Symbol, #call, nil]
+    # @return [#call]
+    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    def resolve(spec)
+      case spec
+      when NilClass
+        lookup(:last_write_wins)
+      when Symbol
+        lookup(spec)
+      else
+        return spec if spec.respond_to?(:call)
+
+        raise ArgumentError, "unknown merger: #{spec.inspect}"
+      end
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+  end
+end