cmdx 2.0.0 → 2.1.0

data/lib/cmdx/workflow.rb

@@ -24,10 +24,11 @@ module CMDx
         @pipeline ||= []
       end
 
-      # Declares a task group. With no arguments, returns the pipeline.
-      # Tasks must be `Task` subclasses.
+      # Declares a task group. At least one `Task` subclass is required —
+      # invoking with no arguments raises `DefinitionError`. Use {.pipeline}
+      # to read the existing group list.
       #
-      # @param tasks [Array<Class<Task>>]
+      # @param tasks [Array<Class<Task>>] one or more `Task` subclasses
       # @param options [Hash{Symbol => Object}]
       # @option options [:sequential, :parallel] :strategy (:sequential)
       # @option options [Integer] :pool_size parallel worker/fiber count
@@ -55,18 +56,26 @@ module CMDx
       #   `:parallel` cancels pending tasks (in-flight tasks still finish).
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
-      # @return [Array<ExecutionGroup>] the full pipeline
-      # @raise [DefinitionError] when called with options but no tasks
+      # @return [Array<ExecutionGroup>] the full pipeline (with the new group appended)
+      # @raise [DefinitionError] when called with no tasks
       # @raise [TypeError] when any element isn't a `Task` subclass
       def tasks(*tasks, **options)
-        raise DefinitionError, "#{name}: cannot declare an empty task group" if tasks.empty?
+        if tasks.empty?
+          raise DefinitionError, <<~MSG.chomp
+            #{name}: cannot declare an empty task group; pass at least one Task subclass.
+            See https://drexed.github.io/cmdx/workflows/#declarations
+          MSG
+        end
 
         pipeline << ExecutionGroup.new(
           tasks:
             tasks.map do |task|
               next task if task.is_a?(Class) && (task <= Task)
 
-              raise TypeError, "#{task.inspect} is not a Task"
+              raise TypeError, <<~MSG.chomp
+                #{task.inspect} is not a Task subclass.
+                See https://drexed.github.io/cmdx/workflows/#declarations
+              MSG
             end,
           options:
         )
@@ -75,16 +84,13 @@ module CMDx
 
       private
 
-      # Forbids user-defined `work` on workflows; `Workflow#work` delegates
-      # to {Pipeline}.
-      #
-      # @param method_name [Symbol] hook name reported by Ruby
-      # @return [void]
-      # @raise [ImplementationError] when a workflow defines `work`
       def method_added(method_name)
         return super unless method_name == :work
 
-        raise ImplementationError, "cannot define #{name}##{method_name} in a workflow"
+        raise ImplementationError, <<~MSG.chomp
+          cannot define #{name}##{method_name} in a workflow; #work is auto-generated to delegate to Pipeline.
+          See https://drexed.github.io/cmdx/workflows/#declarations
+        MSG
       end
 
     end
@@ -95,7 +101,15 @@ module CMDx
     # @api private
     # @param base [Class] task class including this mixin
     # @return [void]
+    # @raise [ImplementationError] when `base` is not a {Task} subclass
     def self.included(base)
+      unless base.is_a?(Class) && base <= Task
+        raise ImplementationError, <<~MSG.chomp
+          CMDx::Workflow can only be included in a CMDx::Task subclass (got #{base.inspect}).
+          See https://drexed.github.io/cmdx/workflows/#declarations
+        MSG
+      end
+
       base.extend(ClassMethods)
     end
 

data/lib/cmdx.rb

@@ -24,6 +24,13 @@ module CMDx
   EMPTY_HASH = {}.freeze
   private_constant :EMPTY_HASH
 
+  # Sentinel object used as a placeholder return value to avoid per-call
+  # allocations on hot paths.
+  #
+  # @api private
+  EMPTY_SENTINEL = Object.new.freeze
+  private_constant :EMPTY_SENTINEL
+
   # Shared empty string constant used as a sentinel default. Intentionally
   # not frozen so callers may treat it as a mutable seed when needed.
   #
@@ -51,6 +58,11 @@ module CMDx
   # before continuing.
   DeprecationError = Class.new(Error)
 
+  # Raised when a control-flow signal (e.g. `skip!`, `fail!`) is thrown against
+  # a task that has already completed and been frozen, making further state
+  # transitions impossible.
+  FrozenTaskError = Class.new(Error)
+
   # Raised when a subclass fails to fulfill an abstract contract — most
   # commonly when {Task} is invoked without overriding `#work`, or when a
   # {Workflow} attempts to define `#work` itself.
@@ -60,6 +72,18 @@ module CMDx
   # yield to `next_link`, which would otherwise silently skip the task body.
   MiddlewareError = Class.new(Error)
 
+  # Raised by {Context} in strict mode when accessing a key that was never
+  # assigned, preventing silent `nil` propagation across task boundaries.
+  UnknownAccessorError = Class.new(Error)
+
+  # Raised when a registry lookup (coercion, validator, middleware, etc.) is
+  # performed against a name that has not been registered.
+  UnknownEntryError = Class.new(Error)
+
+  # Raised when the configured locale cannot be resolved to a translation
+  # file on the i18n load path.
+  UnknownLocaleError = Class.new(Error)
+
 end
 
 require_relative "cmdx/version"

data/lib/generators/cmdx/templates/install.rb

@@ -1,40 +1,54 @@
 # frozen_string_literal: true
 
 CMDx.configure do |config|
+  # Full configuration reference:
+  # https://drexed.github.io/cmdx/configuration
+
   # ===========================================================================
-  # Locale
+  # Default locale
+  # https://drexed.github.io/cmdx/configuration/#default-locale
   # ===========================================================================
-  # Fallback locale for built-in messages (validation, coercion, etc.) when
-  # the I18n gem is not present. With I18n loaded, CMDx follows `I18n.locale`.
+  # The language CMDx uses for its built-in messages (validation errors,
+  # coercion errors, etc.) when the `I18n` gem isn't around. If `I18n` IS
+  # loaded, CMDx follows `I18n.locale` and ignores this setting.
   #
   # config.default_locale = "en"
 
   # ===========================================================================
   # Strict context
+  # https://drexed.github.io/cmdx/configuration/#strict-context
   # ===========================================================================
-  # When true, dynamic reads on `context` raise `NoMethodError` for unknown
-  # keys instead of returning `nil` (`[]`, `fetch`, `dig`, and `?` predicates
-  # stay lenient). Override per-task via `settings(strict_context: true)`.
+  # Catches typos early. With strict mode on, `context.usr_id` (instead of
+  # `context.user_id`) raises `CMDx::UnknownAccessorError` instead of silently
+  # returning `nil`. Hash-style reads (`[]`, `fetch`, `dig`, `?` predicates)
+  # stay forgiving. Flip it per task with `settings(strict_context: true)`.
   #
   # config.strict_context = true
 
   # ===========================================================================
   # Correlation ID (xid)
+  # https://drexed.github.io/cmdx/configuration/#correlation-id-xid
   # ===========================================================================
-  # Resolves an external correlation id (e.g. Rails `request_id`) once per
-  # root execution. The value is stored on the Chain and surfaces on every
-  # Result (`result.xid`, `result.to_h[:xid]`) and Telemetry::Event (`event.xid`),
-  # so all tasks within the same request can be filtered together in logs.
+  # Stamps every task in a run with the same id so you can grep your logs by
+  # request. The callable runs ONCE per root execution; every nested task
+  # inherits the value. Surfaces as `result.xid`, `result.to_h[:xid]`, and
+  # `event.xid` on telemetry events.
   #
   # config.correlation_id = -> { Current.request_id }
 
   # ===========================================================================
   # Logging
+  # https://drexed.github.io/cmdx/configuration/#logging
   # ===========================================================================
-  # In Rails, the Railtie already wires `config.logger = Rails.logger` and a
-  # backtrace cleaner — override here only if you need something different.
+  # Pick where logs go, how they look, and what to hide. In Rails, the Railtie
+  # already points `logger` at `Rails.logger` and wires a backtrace cleaner —
+  # only override here if you want something different.
+  #
+  # Built-in formatters (under `CMDx::LogFormatters`):
+  #   Line (default), JSON, KeyValue, Logstash, Raw
   #
-  # Formatters: Line (default), Json, KeyValue, Logstash, Raw
+  # `log_exclusions` only strips keys from the LOG LINE — the in-memory
+  # `Result` and telemetry payloads stay complete.
   #
   # config.backtrace_cleaner = ->(bt) { Rails.backtrace_cleaner.clean(bt) }
   # config.log_exclusions = [:context]
@@ -44,8 +58,12 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Middlewares
+  # https://drexed.github.io/cmdx/configuration/#middlewares
   # ===========================================================================
-  # Wrap every task's execution. Must respond to `call(task) { ... }`.
+  # Wrap every task with shared behavior (auth, locale, timing, you name it).
+  # A middleware is anything that responds to `call(task) { ... }` and MUST
+  # yield (or call `next_link.call` from a proc) — forgetting to do so raises
+  # `CMDx::MiddlewareError` so tasks never silently disappear.
   #
   # Example — run each task under the current user's locale:
   #
@@ -59,9 +77,13 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Callbacks
+  # https://drexed.github.io/cmdx/configuration/#callbacks
   # ===========================================================================
-  # Events:
-  #   :before_validation, :before_execution,
+  # Hook into a task's lifecycle. Each callback receives the task instance.
+  #
+  # Available events:
+  #   :before_execution, :before_validation,
+  #   :around_execution, :after_execution,
   #   :on_complete, :on_interrupted,
   #   :on_success, :on_skipped, :on_failed,
   #   :on_ok, :on_ko
@@ -72,16 +94,20 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Telemetry
+  # https://drexed.github.io/cmdx/configuration/#telemetry
   # ===========================================================================
-  # Events and payloads:
-  #   :task_started      payload: {}
-  #   :task_deprecated   payload: {}
-  #   :task_retried      payload: { attempt: Integer }
-  #   :task_rolled_back  payload: {}
-  #   :task_executed     payload: { result: CMDx::Result }
+  # A tiny pub/sub bus for runtime events. Subscribe with a callable; nothing
+  # fires if nobody's listening, so unused events cost nothing.
+  #
+  # Events and their extra payload keys:
+  #   :task_started      {}
+  #   :task_deprecated   {}
+  #   :task_retried      { attempt: Integer }
+  #   :task_rolled_back  {}
+  #   :task_executed     { result: CMDx::Result }
   #
   # Every event also carries: event.cid, event.xid, event.tid, event.task,
-  # event.type, event.root, event.timestamp.
+  # event.type, event.name, event.root, event.payload, event.timestamp.
   #
   # config.telemetry.subscribe(:task_executed, proc do |event|
   #   StatsD.timing("cmdx.task", event.payload[:result].duration)
@@ -89,8 +115,11 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Coercions
+  # https://drexed.github.io/cmdx/configuration/#coercions
   # ===========================================================================
-  # Register custom type coercions. Callable receives `(value, **options)`.
+  # Teach CMDx how to convert raw input into a custom type. The callable gets
+  # `(value, **options)` and returns the coerced value (or
+  # `CMDx::Coercions::Failure.new("message")` to signal a bad value).
   #
   # config.coercions.register(:currency, proc do |value, **|
   #   BigDecimal(value.to_s.gsub(/[^\d.-]/, ""))
@@ -98,9 +127,11 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Validators
+  # https://drexed.github.io/cmdx/configuration/#validators
   # ===========================================================================
-  # Register custom validators. Callable receives `(value, options)` and
-  # returns a `CMDx::Validators::Failure.new(message)` on failure.
+  # Custom input validators. The callable gets `(value, options)` (options is
+  # a positional Hash). Return `CMDx::Validators::Failure.new(message)` to
+  # fail — anything else (even `nil`) means the value passed.
   #
   # config.validators.register(:uuid, proc do |value, _options|
   #   unless value.to_s.match?(/\A[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
@@ -108,13 +139,43 @@ CMDx.configure do |config|
   #   end
   # end)
 
+  # ===========================================================================
+  # Retriers
+  # https://drexed.github.io/cmdx/retries/
+  # ===========================================================================
+  # Retriers decide how long to wait between `retry_on` attempts. A callable
+  # gets `(attempt, delay, prev_delay)` and returns the next sleep in seconds.
+  #
+  # Built-ins: :exponential (default), :linear, :fibonacci, :half_random,
+  # :full_random, :bounded_random, :decorrelated_jitter.
+  #
+  # config.retriers.register(:capped_exponential, proc do |attempt, delay, _prev|
+  #   [delay * (2**(attempt - 1)), 30.0].min
+  # end)
+
+  # ===========================================================================
+  # Deprecators
+  # https://drexed.github.io/cmdx/deprecation/
+  # ===========================================================================
+  # Decide what happens when a task with a `deprecation` declaration runs —
+  # log a warning, raise, ping your error tracker, whatever you like. The
+  # callable receives the task instance.
+  #
+  # Built-ins: :log, :warn, :error.
+  #
+  # config.deprecators.register(:notify, proc do |task|
+  #   Bugsnag.notify("Deprecated task invoked: #{task.class.name}")
+  # end)
+
   # ===========================================================================
   # Executors
+  # https://drexed.github.io/cmdx/workflows/#parallel-execution
   # ===========================================================================
-  # Registered executors drive `:parallel` workflow groups. Built-ins:
-  # `:threads` (default), `:fibers`. A callable receives
-  # `call(jobs:, concurrency:, on_job:)` and must invoke `on_job.call(job)`
-  # for each job, blocking until every job is done.
+  # Executors power `:parallel` workflow groups. The callable gets
+  # `(jobs:, concurrency:, on_job:)`, runs `on_job.call(job)` for every job,
+  # and blocks until every job is done.
+  #
+  # Built-ins: :threads (default), :fibers.
   #
   # config.executors.register(:ractors, proc do |jobs:, concurrency:, on_job:|
   #   jobs.each_slice(concurrency) do |slice|
@@ -124,10 +185,12 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Mergers
+  # https://drexed.github.io/cmdx/workflows/#parallel-execution
   # ===========================================================================
-  # Merge strategies fold successful parallel task contexts back into the
-  # workflow context. Built-ins: `:last_write_wins` (default), `:deep_merge`,
-  # `:no_merge`. A callable receives `call(workflow_context, result)`.
+  # After parallel branches succeed, a merger folds each branch's context back
+  # into the workflow context. The callable gets `(workflow_context, result)`.
+  #
+  # Built-ins: :last_write_wins (default), :deep_merge, :no_merge.
   #
   # config.mergers.register(:whitelist, proc do |workflow_context, result|
   #   result.context.to_h.slice(:order_id, :total).each do |key, value|

data/mkdocs.yml

@@ -189,12 +189,14 @@ nav:
       - Tips and Tricks: tips_and_tricks.md
       - Comparison: comparison.md
       - v1 → v2 Migration: v2-migration.md
+      - Examples: https://github.com/drexed/cmdx/blob/main/examples/index.md
     - References:
       - API Documentation: https://drexed.github.io/cmdx/api/index.html
       - llms.txt: https://drexed.github.io/cmdx/llms.txt
       - llms-full.txt: https://drexed.github.io/cmdx/llms-full.txt
       - AI Skills: https://github.com/drexed/cmdx/blob/main/skills
     - Ecosystem:
+      - cmdx-i18n: https://github.com/drexed/cmdx-i18n
       - cmdx-rspec: https://github.com/drexed/cmdx-rspec
   - Blog: blog/index.md
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Juan Gomez