cmdx 1.21.0 → 2.0.0

data/lib/cmdx/fault.rb

@@ -1,109 +1,116 @@
 # frozen_string_literal: true
 
 module CMDx
-
-  # Base fault class for handling task execution failures and interruptions.
+  # Exception raised by `execute!` (strict mode) when a task fails. Carries
+  # the originating {Result} (deepest in any propagation chain) and exposes
+  # `task`, `signal`, `context`, and `chain` as delegators. The backtrace is
+  # cleaned through the configured `backtrace_cleaner` when present.
   #
-  # Faults represent error conditions that occur during task execution, providing
-  # a structured way to handle and categorize different types of failures.
-  # Each fault contains a reference to the result object that caused the fault.
+  # Use {.for?} or {.matches?} to build matcher subclasses suitable for
+  # `rescue` clauses.
   class Fault < Error
 
-    extend Forwardable
-
-    # Returns the result that caused this fault.
-    #
-    # @return [Result] The result instance
-    #
-    # @example
-    #   fault.result.reason # => "Validation failed"
-    #
-    # @rbs @result: Result
-    attr_reader :result
-
-    def_delegators :result, :task, :context, :chain
-
-    # Initialize a new fault with the given result.
-    #
-    # @param result [Result] the result object that caused this fault
-    #
-    # @raise [ArgumentError] if result is nil or invalid
-    #
-    # @example
-    #   fault = Fault.new(task_result)
-    #   fault.result.reason # => "Task validation failed"
-    #
-    # @rbs (Result result) -> void
-    def initialize(result)
-      @result = result
-
-      super(result.reason)
-    end
-
     class << self
 
-      # Create a fault class that matches specific task types.
-      #
-      # @param tasks [Array<Class>] array of task classes to match against
+      # Returns a matcher subclass that matches Faults whose `task` is (or
+      # inherits from) any of the given task classes. Suitable for use in
+      # `rescue`.
       #
-      # @return [Class] a new fault class that matches the specified tasks
+      # @param tasks [Array<Class>] one or more Task classes
+      # @return [Class<Fault>] anonymous matcher subclass
+      # @raise [ArgumentError] when no tasks are given
       #
       # @example
-      #   Fault.for?(UserTask, AdminUserTask)
-      #   # => true if fault.task is a UserTask or AdminUserTask
-      #
-      # @rbs (*Class tasks) -> Class
+      #   begin
+      #     MyTask.execute!(ctx)
+      #   rescue Fault.for?(ProcessOrder, ChargeCard) => fault
+      #     Alert.for_fault(fault)
+      #   end
       def for?(*tasks)
-        temp_fault = Class.new(self) do
-          def self.===(other)
-            other.is_a?(superclass) && @tasks.any? { |task| other.task.is_a?(task) }
-          end
-        end
+        tasks = tasks.flatten
+        raise ArgumentError, "at least one task required" if tasks.empty?
 
-        temp_fault.tap { |c| c.instance_variable_set(:@tasks, tasks) }
+        matcher do |other|
+          tasks.any? { |task| other.task <= task }
+        end
       end
 
-      # Create a fault class that matches based on a custom block.
-      #
-      # @param block [Proc] block that determines if a fault matches
+      # Returns a matcher subclass that matches Faults whose `result.reason`
+      # is equal to the given string. Suitable for use in `rescue`.
       #
-      # @return [Class] a new fault class that matches based on the block
-      #
-      # @raise [ArgumentError] if no block is provided
+      # @param reason [String] the reason to match
+      # @return [Class<Fault>] anonymous matcher subclass
+      # @raise [ArgumentError] when no reason is given
       #
       # @example
-      #   Fault.matches? { |fault| fault.result.metadata[:critical] }
-      #   # => true if fault has critical metadata
+      #   begin
+      #     MyTask.execute!(ctx)
+      #   rescue Fault.reason?("Payment failed") => fault
+      #     Alert.for_fault(fault)
+      #   end
+      def reason?(reason)
+        raise ArgumentError, "reason required" unless reason
+
+        matcher do |other|
+          other.result.reason == reason
+        end
+      end
+
+      # Returns a matcher subclass whose `===` runs `block` against the fault.
       #
-      # @rbs () { (Fault) -> bool } -> Class
+      # @param block [#call] `(fault) -> Boolean` matcher body
+      # @yieldparam fault [Fault]
+      # @yieldreturn [Boolean]
+      # @return [Class<Fault>] anonymous matcher subclass
+      # @raise [ArgumentError] when no block is given
       def matches?(&block)
-        raise ArgumentError, "block required" unless block_given?
+        raise ArgumentError, "block required" unless block
 
-        temp_fault = Class.new(self) do
-          def self.===(other)
-            other.is_a?(superclass) && @block.call(other)
+        matcher(&block)
+      end
+
+      private
+
+      def matcher(&)
+        fault_class = self
+        Class.new(fault_class) do
+          define_singleton_method(:===) do |other|
+            fault_class === other && yield(other)
           end
         end
-
-        temp_fault.tap { |c| c.instance_variable_set(:@block, block) }
       end
 
     end
 
-  end
+    attr_reader :result
 
-  # Fault raised when a task is intentionally skipped during execution.
-  #
-  # This fault occurs when a task determines it should not execute based on
-  # its current context or conditions. Skipped tasks are not considered failures
-  # but rather intentional bypasses of task execution logic.
-  SkipFault = Class.new(Fault)
+    # @param result [Result] the failed result this Fault represents
+    def initialize(result)
+      @result = result
 
-  # Fault raised when a task execution fails due to errors or validation failures.
-  #
-  # This fault occurs when a task encounters an error condition, validation failure,
-  # or any other condition that prevents successful completion. Failed tasks indicate
-  # that the intended operation could not be completed successfully.
-  FailFault = Class.new(Fault)
+      super(I18nProxy.tr(result.reason))
 
+      if (frames = result.backtrace || result.cause&.backtrace_locations)
+        frames = frames.map(&:to_s)
+        frames = task.settings.backtrace_cleaner&.call(frames) || frames
+        set_backtrace(frames)
+      end
+    end
+
+    # @return [Class<Task>] the failing task class
+    def task
+      @result.task
+    end
+
+    # @return [Context] the failed task's context
+    def context
+      @result.context
+    end
+
+    # @return [Chain] the chain the failed result belongs to
+    def chain
+      @result.chain
+    end
+
+  end
 end

data/lib/cmdx/i18n_proxy.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Translation façade used internally for coercion, validator, and output
+  # error messages. Delegates to `I18n.translate` when the `i18n` gem is
+  # available; otherwise loads CMDx's bundled YAML locale file and performs
+  # percent-interpolation on the string itself. Results are memoized.
+  class I18nProxy
+
+    class << self
+
+      # @return [Array<String>] directories searched (in order) for bundled locale YAMLs
+      def locale_paths
+        @locale_paths ||= [File.expand_path("../locales", __dir__)]
+      end
+
+      # @param key [String, Symbol] dot-separated translation key
+      # @param options [Hash{Symbol => Object}] forwarded to `I18n.translate` or bundled interpolation
+      # @option options [Object] :default fallback when the bundled YAML lookup misses
+      # @option options [Hash{Symbol => Object}] extra keys interpolated via `String#%` for bundled translations
+      # @return [String, Object] the translated string (or the raw default value)
+      def translate(key, **options)
+        @proxy ||= new
+        @proxy.translate(key, **options)
+      end
+
+      # @param (see .translate)
+      # @option (see .translate)
+      # @return (see .translate)
+      def t(key, **options)
+        translate(key, **options)
+      end
+
+      # Register an additional directory containing locale YAML files. Later
+      # registrations take precedence over earlier ones (the most recently
+      # registered path's values win during deep merge). Resets the memoized
+      # proxy so subsequent lookups see the new path.
+      #
+      # @param path [String] absolute path to a directory of `<locale>.yml` files
+      # @return [Array<String>] the updated locale paths
+      def register(path)
+        locale_paths.push(path) unless locale_paths.include?(path)
+        @proxy = nil
+        locale_paths
+      end
+
+      # Resolves a reason string through translation, falling back to either
+      # the literal reason (when present) or the `cmdx.reasons.unspecified`
+      # default (when nil).
+      #
+      # @param reason [String, Symbol, nil] reason text or translation key
+      # @return [String] translated message, literal reason, or default
+      def tr(reason)
+        translate(reason || "cmdx.reasons.unspecified", default: reason)
+      end
+
+    end
+
+    # @param key [String, Symbol] dot-separated translation key
+    # @param options [Hash{Symbol => Object}] interpolation values
+    # @option options [Object] :default fallback when the bundled YAML lookup misses
+    # @option options [Hash{Symbol => Object}] extra keys interpolated via `String#%` for bundled translations
+    # @return [String, Object] the translated/interpolated message
+    def translate(key, **options)
+      return ::I18n.translate(key, **options) if defined?(::I18n) && ::I18n.respond_to?(:translate)
+
+      message = translation_default(key) || options[:default]
+
+      case message
+      when String
+        message % options
+      when NilClass
+        "Translation missing: #{key}"
+      else
+        message
+      end
+    end
+    alias t translate
+
+    private
+
+    # @param key [String, Symbol] lookup key (without locale prefix)
+    # @return [Object, nil] message template from bundled YAML, when present
+    def translation_default(key)
+      default_locale  = CMDx.configuration.default_locale || "en"
+      translation_key = "#{default_locale}.#{key}"
+
+      @defaults ||= {}
+      return @defaults[translation_key] if @defaults.key?(translation_key)
+
+      @translations ||= {}
+      @translations[default_locale] ||= begin
+        file = "#{default_locale}.yml"
+        paths = self.class.locale_paths.map { |dir| File.join(dir, file) }.select { |p| File.exist?(p) }
+        raise LoadError, "unable to load #{default_locale} translations" if paths.empty?
+
+        paths.reduce({}) { |hash, path| hash.merge(YAML.safe_load_file(path)) }.freeze
+      end
+
+      @defaults[translation_key] = @translations[default_locale].dig(*translation_key.split("."))
+    end
+
+  end
+end

data/lib/cmdx/input.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module CMDx
+  # A single declared task input. Holds declaration options (`:source`,
+  # `:default`, `:required`, `:coerce`, validators, `:transform`, etc.) and
+  # owns the resolution pipeline that produces the value the task will read
+  # through the generated accessor.
+  class Input
+
+    attr_reader :name, :children
+
+    # @param name [Symbol, String] input key (symbolized)
+    # @param children [Array<Input>] nested child inputs resolved from this one's value
+    # @param options [Hash{Symbol => Object}] declaration options
+    # @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
+    def initialize(name, children: EMPTY_ARRAY, **options)
+      @name     = name.to_sym
+      @children = children.freeze
+      @options  = options.freeze
+    end
+
+    # @return [String, nil]
+    def description
+      @options[:description] || @options[:desc]
+    end
+
+    # @return [Symbol, nil]
+    def as
+      @options[:as]
+    end
+
+    # @return [Boolean, String, nil]
+    def prefix
+      @options[:prefix]
+    end
+
+    # @return [Boolean, String, nil]
+    def suffix
+      @options[:suffix]
+    end
+
+    # @return [Symbol, Proc, #call]
+    def source
+      @options[:source] || :context
+    end
+
+    # @return [Object, Symbol, Proc, #call, nil]
+    def default
+      @options[:default]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def transform
+      @options[:transform]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_if
+      @options[:if]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_unless
+      @options[:unless]
+    end
+
+    # @return [Boolean]
+    def required
+      @options.fetch(:required, false)
+    end
+
+    # Computed accessor/reader method name. Uses `:as` when provided,
+    # otherwise combines `:prefix`, `name`, and `:suffix` around the source.
+    #
+    # @return [Symbol]
+    def accessor_name
+      return as if as
+
+      @accessor_name ||= begin
+        prefix_str =
+          case prefix
+          when true
+            "#{source}_"
+          when ::String
+            prefix
+          end
+        suffix_str =
+          case suffix
+          when true
+            "_#{source}"
+          when ::String
+            suffix
+          end
+
+        :"#{prefix_str}#{name}#{suffix_str}"
+      end
+    end
+
+    # @return [Symbol] backing ivar used by the generated reader method
+    def ivar_name
+      @ivar_name ||= :"@_input_#{accessor_name}"
+    end
+
+    # Evaluates required-ness against `task`, respecting `:if`/`:unless`.
+    # When called without a task, returns the static `:required` flag.
+    #
+    # @param task [Task, nil]
+    # @return [Boolean]
+    def required?(task = nil)
+      return false unless required
+      return true if task.nil?
+      return false unless Util.satisfied?(condition_if, condition_unless, task)
+
+      true
+    end
+
+    # Fetches + coerces + transforms + validates the value from its
+    # configured `:source` on `task`. Missing-but-required inputs add a
+    # validation error to `task.errors`. Returns `nil` when coercion or any
+    # validator fails (the failure message is recorded on `task.errors`).
+    #
+    # @param task [Task]
+    # @return [Object, nil] the resolved value (`nil` on failure)
+    def resolve(task)
+      value, key_provided = resolve_with_key(task)
+      run_pipeline(value, key_provided, task)
+    end
+
+    # Same as {#resolve} but fetches the value from `parent_value` (used for
+    # nested child inputs) instead of the declared `:source`.
+    #
+    # @param parent_value [#[], #key?, Object] the parent input's resolved value
+    # @param task [Task]
+    # @return [Object, nil]
+    def resolve_from_parent(parent_value, task)
+      value, key_provided = resolve_from_parent_with_key(parent_value)
+      run_pipeline(value, key_provided, task)
+    end
+
+    # @return [Hash{Symbol => Object}] serialized schema used by `inputs_schema`
+    def to_h
+      {
+        name: accessor_name,
+        description:,
+        required: required?,
+        options: @options,
+        children: children.map(&:to_h)
+      }
+    end
+
+    # JSON-friendly hash view. Aliases {#to_h} for conventional `as_json`
+    # callers (e.g. Rails).
+    #
+    # @return [Hash{Symbol => Object}]
+    def as_json(*)
+      to_h
+    end
+
+    # Serializes the input schema to a JSON string. Non-primitive entries in
+    # `:options` (Procs, arbitrary callables) emit via their stdlib `to_json`
+    # defaults.
+    #
+    # @param args [Array] forwarded to `Hash#to_json`
+    # @return [String]
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    private
+
+    # @param value [Object] candidate after source resolution
+    # @param key_provided [Boolean] whether the source reported an explicit key/value pair
+    # @param task [Task]
+    # @return [Object, nil]
+    def run_pipeline(value, key_provided, task)
+      if required?(task) && !key_provided
+        task.errors.add(accessor_name, I18nProxy.t("cmdx.attributes.required"))
+        return
+      end
+
+      value = apply_default(task) if value.nil?
+      return if value.nil?
+
+      @coercions ||= task.class.coercions.extract(@options)
+      value = task.class.coercions.coerce(task, accessor_name, value, @coercions)
+      return if value.is_a?(Coercions::Failure)
+
+      value = apply_transform(value, task) if transform
+      @validators ||= task.class.validators.extract(@options)
+      task.class.validators.validate(task, accessor_name, value, @validators)
+      return if task.errors.for?(accessor_name)
+
+      value
+    end
+
+    # @param task [Task]
+    # @return [Array(Object, Boolean)] `[value, key_provided]`
+    def resolve_with_key(task)
+      case source
+      when :context
+        [task.context[name], task.context.key?(name)]
+      when Symbol
+        obj = task.send(source)
+        return [nil, false] if obj.nil?
+
+        fetch_by_name(obj)
+      when Proc
+        [task.instance_exec(&source), true]
+      else
+        return [source.call(task), true] if source.respond_to?(:call)
+
+        raise ArgumentError, "source must be a Symbol, Proc, or respond to #call"
+      end
+    end
+
+    # @param parent_value [#[], #key?, Object]
+    # @return [Array(Object, Boolean)] `[value, key_provided]`
+    def resolve_from_parent_with_key(parent_value)
+      return [nil, false] unless parent_value.respond_to?(:[])
+
+      fetch_by_name(parent_value)
+    end
+
+    # @param obj [Object] source object (`Hash`, duck-typed reader, etc.)
+    # @return [Array(Object, Boolean)] `[value, key_provided]`
+    def fetch_by_name(obj)
+      if obj.respond_to?(name, true)
+        [obj.send(name), true]
+      elsif obj.respond_to?(:key?)
+        if obj.key?(name)
+          [obj[name], true]
+        elsif obj.key?(name_str = name.to_s)
+          [obj[name_str], true]
+        else
+          [nil, false]
+        end
+      elsif obj.respond_to?(:[])
+        # Without #key? we cannot distinguish "key absent" from "value is nil",
+        # so an explicit nil is treated as not provided (triggers default/required).
+        value = obj[name] || obj[name.to_s]
+        [value, !value.nil?]
+      else
+        [nil, false]
+      end
+    end
+
+    # @param task [Task]
+    # @return [Object, nil]
+    def apply_default(task)
+      return if default.nil?
+
+      case default
+      when Symbol
+        task.send(default)
+      when Proc
+        task.instance_exec(&default)
+      else
+        return default unless default.respond_to?(:call)
+
+        default.call(task)
+      end
+    end
+
+    # @param value [Object]
+    # @param task [Task]
+    # @return [Object]
+    def apply_transform(value, task)
+      case transform
+      when Symbol
+        if value.respond_to?(transform, true)
+          value.send(transform)
+        else
+          task.send(transform, value)
+        end
+      when Proc
+        task.instance_exec(value, &transform)
+      else
+        return transform.call(value, task) if transform.respond_to?(:call)
+
+        raise ArgumentError, "transform must be a Symbol, Proc, or respond to #call"
+      end
+    end
+
+  end
+end