cmdx 1.13.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b1cd7841d40aeac40b6eb36a7ff87a5ace03deae3496e1aef5cb10e34f8f42d
-  data.tar.gz: 303333d4635690575ceda40a2564be417b47f5ec4c2992af542c509710289ae3
+  metadata.gz: f23ba43366877a7e368b02f036bd98212c53ee1d52ae47c09e4d689ac305651e
+  data.tar.gz: 4b4e778baa84ae14274c8313464c979fb1be9c9d0651f45ca0483bc7f530a3c2
 SHA512:
-  metadata.gz: 18cde5cf4b6c7fa974ffb7a3827e09d0a5c2ac5f3c2c01427abbc94de71ef1bc03aee78e25032900761f09c8d39e89e52a4ea1d5fa33e07c86f060b483fe839f
-  data.tar.gz: 5ed05ecdb682ae160be47cf6399c76081486011b6143f95f9884a06b588474ba64e3e000efd72ba2dcd6abb343e3e12985d2691ca15ee7575873f90daff6e70f
+  metadata.gz: e1ea9eeebd2d84da3c8d0813dbf8739f8776adc0fb749ee9309f63bff258026b4ec9a8f53e32bca6c8a806ae135a617773709ff41d9b52fd3def07f914b2199d
+  data.tar.gz: 1dc6797d0e13aa08f900464c731f81cc5fd15672094c9ce3f02d0487d99395ce219b21ad7a9e95aa1d833b3dd36a9394a156fec503cd417109e3e08d33e41449

data/CHANGELOG.md

@@ -4,175 +4,191 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [UNRELEASED]
+## [Unreleased]
 
-## [1.13.0] - 2025-12-23
+## [1.15.0] - 2025-01-21
 
 ### Added
+- Add attribute `Absence` validator
+- Add attribute `:description` option
 
-- Added task execution rollback tracking and logging
-- Added `dry_run` option to task execution with inheritance support for nested tasks
-- Added context `delete` alias for `delete!`
-- Added context `merge` alias for `merge!`
+## [1.14.0] - 2025-01-09
 
-## [1.12.0] - 2025-12-18
+### Added
+- Add Ruby 4.0 compatibility
+- Add `Context#clear!` method to remove all context data
+- Add `Task.attribute_schema` class method for attribute introspection
+- Add `#to_h` method for attribute serialization
+
+### Changed
+- **BREAKING**: Switch license from MIT to LGPLv3
+- Replace `instance_eval` with `define_singleton_method` for attribute method definitions
+- Move retry count from metadata to result object
+- Exclude non-essential files from gem package
+
+### Removed
+- Remove public `Result#rolled_back!` method to hide internal implementation
+
+## [1.13.0] - 2025-12-23
 
 ### Added
-- Added active record database transaction example
-- Added Sentry error tracking example
-- Added Redis idempotency example
-- Added Flipper feature flag example
-
-### Updated
-- Remove `handle_*` methods and provide `on(*states_or_statuses)` method for more flexibility
-- Optimize logging ancestor lookup
-- Use chop instead of range for better string performance
-- Update boolean coercion `TRUTHY` and `FALSEY` regexp to be case insensitive
-- Improve YARD documentation with `yard-lint`
+- Add rollback tracking and logging for task execution
+- Add `dry_run` execution option with inheritance support for nested tasks
+- Add `Context#delete` alias for `Context#delete!`
+- Add `Context#merge` alias for `Context#merge!`
+
+## [1.12.0] - 2025-12-18
+
+### Changed
+- Optimize logging ancestor chain lookup performance
+- Use `String#chop` instead of range indexing for improved string performance
+- Make boolean coercion `TRUTHY` and `FALSEY` patterns case-insensitive
+- Enhance YARD documentation using `yard-lint` validation
+
+### Removed
+- Remove `handle_*` callback methods in favor of `on(*states_or_statuses)` for flexible state handling
 
 ## [1.11.0] - 2025-11-08
 
-### Updated
-- Added conditionally required attributes options
-- Update specs to use new `cmdx-rspec` matcher names
+### Changed
+- Add conditional requirement support for attribute validation
+- Update specs to use new `cmdx-rspec` matcher naming conventions
 
 ## [1.10.1] - 2025-11-06
 
 ### Added
-- Added Sidekiq async integration example
-- Added YARDoc documentation to docs site
+- Add YARDoc documentation to documentation site
 
 ### Removed
-- Removed `Executor#repeator` method (never used)
+- Remove unused `Executor#repeator` method
 
 ## [1.10.0] - 2025-10-26
 
 ### Added
-- Added `rollback` ability to undo on matching status
-- Added documentation for retries
-- Added Stoplight circuit breaker integration example
+- Add `rollback` capability to undo operations based on status
+- Add retry mechanism documentation
 
-### Updated
-- Updated `retry_jitter` option to support symbol, proc, and callables on top of fixed values
+### Changed
+- Extend `retry_jitter` option to accept symbols, procs, and callable objects
 
 ## [1.9.1] - 2025-10-22
 
 ### Added
-- Added RBS inlines type signatures
-- Added YARDocs for `attr_reader` and `attr_accessor` methods
+- Add RBS inline type signatures
+- Add YARDocs for `attr_reader` and `attr_accessor` methods
 
 ## [1.9.0] - 2025-10-21
 
 ### Added
-- Added `transform` option to attributes
-- Added option to output failure backtraces
-- Added exception handling for non-bang methods
-- Added durability with automatic retries to execution
-- Added `to_h` hash coercion support
-- Added comprehensive MkDocs configuration with material theme
+- Add `transform` option for attribute value transformations
+- Add optional failure backtrace output
+- Add exception handling for non-bang execution methods
+- Add automatic retry mechanism for execution durability
+- Add `to_h` hash coercion support
+- Add MkDocs configuration with Material theme
 
 ### Changed
-- Improved performance of task settings setup
-- Improved error messages for raised exceptions
-- Improved inheritance of parent settings
-- Cleaned halt backtrace frames for better readability
+- Improve task settings initialization performance
+- Improve exception error message clarity
+- Improve parent settings inheritance behavior
+- Clean halt backtrace frames for better readability
 
 ### Removed
-- Removed `Freezer` module and moved logic into executor `freeze_execution!` method
-- Removed task parameter from callback signature
-- Removed task and workflow arguments from conditional checks
-- Removed chain persistence after execution in specs
+- Remove `Freezer` module; consolidate logic into `Executor#freeze_execution!`
+- Remove `task` parameter from callback method signatures
+- Remove `task` and `workflow` arguments from conditional checks
+- Remove chain persistence after execution in specs
 
 ## [1.8.0] - 2025-09-22
 
 ### Changed
-- Generalized locale values for fault `invalid` and `unspecified`
-- Nested attribute error messages under `error` key within metadata
-- Reordered logstash formatter keys for consistency
-- Improved error message for already defined items
-- Changed hash coercion for `nil` to return `{}`
+- Generalize locale values for `invalid` and `unspecified` faults
+- Nest attribute error messages under `error` key in metadata
+- Reorder Logstash formatter keys for consistency
+- Improve error messaging for duplicate item definitions
+- Return empty hash `{}` for `nil` hash coercion
 
 ## [1.7.5] - 2025-09-10
 
 ### Added
-- Added `fetch_or_store` method to context
-- Added `ctx` alias for context in result
-- Added `ok?` alias for `good?` in result
-- Added deconstruction values in result
+- Add `Context#fetch_or_store` method for atomic get-or-set operations
+- Add `Result#ctx` alias for `Result#context`
+- Add `Result#ok?` alias for `Result#good?`
+- Add result deconstruction support for pattern matching
 
 ## [1.7.4] - 2025-09-03
 
 ### Added
-- Added errors delegation from result object
-- Added `full_messages` and `to_hash` methods to errors
+- Add errors delegation from result object
+- Add `Errors#full_messages` and `Errors#to_hash` methods
 
 ## [1.7.3] - 2025-09-03
 
 ### Changed
-- Changed validation reasons to use generic values
-- Moved validation full message string to `:full_message` key within metadata
+- Use generic validation reason values
+- Move validation full message to `:full_message` key in metadata
 
 ## [1.7.2] - 2025-09-03
 
 ### Changed
-- Changed correlation ID to be set before continuing to further steps
+- Set correlation ID before proceeding to subsequent execution steps
 
 ## [1.7.1] - 2025-08-26
 
 ### Added
-- Added result yielding when block is given to `execute` and `execute!` methods
+- Add block yielding support to `execute` and `execute!` methods
 
 ## [1.7.0] - 2025-08-25
 
 ### Added
-- Added workflow generator
+- Add workflow generator
 
 ### Changed
-- Ported `cmdx-parallel` changes into core
-- Ported `cmdx-i18n` changes into core
+- Integrate `cmdx-parallel` functionality into core
+- Integrate `cmdx-i18n` functionality into core
 
 ## [1.6.2] - 2025-08-24
 
 ### Changed
-- Prefixed railtie I18n with `::` for compatibility with `CMDx::I18n`
-- Changed to use `cmdx-rspec` for matchers support
+- Prefix railtie I18n with `::` for `CMDx::I18n` compatibility
+- Switch to `cmdx-rspec` for matcher support
 
 ## [1.6.1] - 2025-08-23
 
 ### Changed
-- Changed task results to be logged before freezing
-- Renamed `execute_tasks_sequentially` to `execute_tasks_in_sequence`
+- Log task results before freezing execution state
+- Rename `execute_tasks_sequentially` to `execute_tasks_in_sequence`
 
 ## [1.6.0] - 2025-08-22
 
 ### Added
-- Added workflow task `:breakpoints` support
+- Add workflow task `:breakpoints` support
 
 ### Changed
-- Renamed `Worker` class to `Executor`
-- Moved workflow `work` logic into `Pipeline`
+- Rename `Worker` class to `Executor`
+- Extract workflow execution logic into `Pipeline` class
 
 ## [1.5.2] - 2025-08-22
 
 ### Changed
-- Renamed workflow `execution_groups` attribute to `pipeline`
+- Rename workflow `execution_groups` attribute to `pipeline`
 
 ## [1.5.1] - 2025-08-21
 
 ### Changed
-- Prefixed locale I18n with `::` for compatibility with `CMDx::I18n`
-- Added safe navigation to length and numeric validators
-- Updated railtie file path to point to correct directory
+- Prefix locale I18n with `::` for `CMDx::I18n` compatibility
+- Add safe navigation to length and numeric validators
+- Fix railtie file path to reference correct directory
 
 ## [1.5.0] - 2025-08-21
 
 ### Changed
-- **BREAKING**: Revamped CMDx for improved clarity, transparency, and higher performance
+- **BREAKING**: Complete architecture redesign for improved clarity, transparency, and performance
 
 ## [1.1.2] - 2025-07-20
 
 ### Changed
-- All changes between versions `0.1.0` and `1.1.2` should be reviewed within their respective git tags
+- See git tags for changes between versions 0.1.0 and 1.1.2
 
 ## [0.1.0] - 2025-03-07
 

data/LICENSE.txt

@@ -1,21 +1,4 @@
-The MIT License (MIT)
+Copyright (c) Drexed
 
-Copyright (c) 2025 Juan Gomez
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+CMDx is an Open Source project licensed under the terms of the LGPLv3 license.
+Please see <http://www.gnu.org/licenses/lgpl-3.0.html> for license text.

data/README.md

@@ -1,16 +1,23 @@
 <div align="center">
-  <img src="./src/cmdx-light-logo.png#gh-light-mode-only" width="200" alt="CMDx Logo">
-  <img src="./src/cmdx-dark-logo.png#gh-dark-mode-only" width="200" alt="CMDx Logo">
+  <img src="./src/cmdx-light-logo.png#gh-light-mode-only" width="200" alt="CMDx Light Logo">
+  <img src="./src/cmdx-dark-logo.png#gh-dark-mode-only" width="200" alt="CMDx Dark Logo">
 
   ---
 
   Build business logic that’s powerful, predictable, and maintainable.
 
-  [Documentation](https://drexed.github.io/cmdx) · [Changelog](./CHANGELOG.md) · [Report Bug](https://github.com/drexed/cmdx/issues) · [Request Feature](https://github.com/drexed/cmdx/issues) · [LLM.md](https://raw.githubusercontent.com/drexed/cmdx/refs/heads/main/LLM.md)
+  [Home](https://drexed.github.io/cmdx) ·
+  [Documentation](https://drexed.github.io/cmdx/getting_started) ·
+  [Blog](https://drexed.github.io/cmdx/blog) ·
+  [Changelog](./CHANGELOG.md) ·
+  [Report Bug](https://github.com/drexed/cmdx/issues) ·
+  [Request Feature](https://github.com/drexed/cmdx/issues) ·
+  [llms.txt](https://drexed.github.io/cmdx/llms.txt) ·
+  [llms-full.txt](https://drexed.github.io/cmdx/llms-full.txt)
 
   <img alt="Version" src="https://img.shields.io/gem/v/cmdx">
   <img alt="Build" src="https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg">
-  <img alt="License" src="https://img.shields.io/github/license/drexed/cmdx">
+  <img alt="License" src="https://img.shields.io/badge/license-LGPL%20v3-blue.svg">
 </div>
 
 # CMDx
@@ -18,13 +25,14 @@
 Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
 
 > [!NOTE]
-> Documentation reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
+> [Documentation](https://drexed.github.io/cmdx/getting_started/) reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
 
 ## Requirements
 
-- Ruby: MRI 3.1+ or JRuby 9.4+.
+- Ruby: MRI 3.1+ or JRuby 9.4+
+- Dependencies: None
 
-CMDx works with any Ruby framework. Rails support is built-in, but it's framework-agnostic at its core.
+Rails support is built-in, but it's framework-agnostic at its core.
 
 ## Installation
 
@@ -125,4 +133,4 @@ Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. W
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [LGPLv3 License](https://www.gnu.org/licenses/lgpl-3.0.html).

data/lib/cmdx/attribute.rb

@@ -72,6 +72,16 @@ module CMDx
     # @rbs @types: Array[Class]
     attr_reader :types
 
+    # Returns the description of the attribute.
+    #
+    # @return [String] The description of the attribute
+    #
+    # @example
+    #   attribute.description # => "The user's name"
+    #
+    # @rbs @description: String
+    attr_reader :description
+
     # Creates a new attribute with the specified name and configuration.
     #
     # @param name [Symbol, String] The name of the attribute
@@ -79,6 +89,7 @@ module CMDx
     # @option options [Attribute] :parent The parent attribute for nested structures
     # @option options [Boolean] :required Whether the attribute is required (default: false)
     # @option options [Array<Class>, Class] :types The expected type(s) for the attribute value
+    # @option options [String] :description The description of the attribute
     # @option options [Symbol, String, Proc] :source The source of the attribute value
     # @option options [Symbol, String] :as The method name to use for this attribute
     # @option options [Symbol, String, Boolean] :prefix The prefix to add to the method name
@@ -98,6 +109,7 @@ module CMDx
       @parent = options.delete(:parent)
       @required = options.delete(:required) || false
       @types = Array(options.delete(:types) || options.delete(:type))
+      @description = options.delete(:description) || options.delete(:desc)
 
       @name = name.to_sym
       @options = options
@@ -235,6 +247,32 @@ module CMDx
       end
     end
 
+    # @return [Hash] A hash representation of the attribute
+    #
+    # @example
+    #   attribute.to_h # => {
+    #   name: :user_id,
+    #   method_name: :current_user_id,
+    #   description: "The user's name",
+    #   required: true,
+    #   types: [:integer],
+    #   options: {},
+    #   children: []
+    # }
+    #
+    # @rbs () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        name: name,
+        method_name: method_name,
+        description: description,
+        required: required?,
+        types: types,
+        options: options.except(:if, :unless),
+        children: children.map(&:to_h)
+      }
+    end
+
     private
 
     # Creates nested attributes as children of this attribute.
@@ -312,11 +350,10 @@ module CMDx
       attribute_value.generate
       attribute_value.validate
 
-      task.instance_eval(<<~RUBY, __FILE__, __LINE__ + 1)
-        def #{method_name}
-          attributes[:#{method_name}]
-        end
-      RUBY
+      name_of_method = method_name
+      task.define_singleton_method(name_of_method) do
+        attributes[name_of_method]
+      end
     end
 
   end

data/lib/cmdx/context.rb

@@ -185,6 +185,22 @@ module CMDx
     end
     alias delete delete!
 
+    # Clears all key-value pairs from the context.
+    #
+    # @return [Context] self for method chaining
+    #
+    # @example
+    #   context = Context.new(name: "John")
+    #   context.clear!
+    #   context.to_h # => {}
+    #
+    # @rbs () -> self
+    def clear!
+      table.clear
+      self
+    end
+    alias clear clear!
+
     # Compares this context with another object for equality.
     #
     # @param other [Object] the object to compare with

data/lib/cmdx/executor.rb

@@ -138,17 +138,17 @@ module CMDx
     #
     # @rbs (Exception exception) -> bool
     def retry_execution?(exception)
-      available_retries = (task.class.settings[:retries] || 0).to_i
+      available_retries = Integer(task.class.settings[:retries] || 0)
       return false unless available_retries.positive?
 
-      current_retries = (result.metadata[:retries] ||= 0).to_i
-      remaining_retries = available_retries - current_retries
+      current_retry = result.retries
+      remaining_retries = available_retries - current_retry
       return false unless remaining_retries.positive?
 
       exceptions = Array(task.class.settings[:retry_on] || StandardError)
       return false unless exceptions.any? { |e| exception.class <= e }
 
-      result.metadata[:retries] += 1
+      result.retries += 1
 
       task.logger.warn do
         reason = "[#{exception.class}] #{exception.message}"
@@ -158,13 +158,13 @@ module CMDx
       jitter = task.class.settings[:retry_jitter]
       jitter =
         if jitter.is_a?(Symbol)
-          task.send(jitter, current_retries)
+          task.send(jitter, current_retry)
         elsif jitter.is_a?(Proc)
-          task.instance_exec(current_retries, &jitter)
+          task.instance_exec(current_retry, &jitter)
         elsif jitter.respond_to?(:call)
-          jitter.call(task, current_retries)
+          jitter.call(task, current_retry)
         else
-          jitter.to_f * current_retries
+          jitter.to_f * current_retry
         end
 
       sleep(jitter) if jitter.positive?
@@ -320,7 +320,7 @@ module CMDx
       statuses = Array(statuses).map(&:to_s).uniq
       return unless statuses.include?(result.status)
 
-      result.rolled_back!
+      result.rolled_back = true
       task.rollback
     end
 

data/lib/cmdx/result.rb

@@ -70,7 +70,7 @@ module CMDx
     # @return [Hash{Symbol => Object}] Metadata hash
     #
     # @example
-    #   result.metadata # => { duration: 1.5, retries: 2 }
+    #   result.metadata # => { duration: 1.5, code: 200, message: "Success" }
     #
     # @rbs @metadata: Hash[Symbol, untyped]
     attr_reader :metadata
@@ -95,6 +95,26 @@ module CMDx
     # @rbs @cause: (Exception | nil)
     attr_reader :cause
 
+    # Returns the number of retries attempted.
+    #
+    # @return [Integer] The number of retries attempted
+    #
+    # @example
+    #   result.retries # => 2
+    #
+    # @rbs @retries: Integer
+    attr_accessor :retries
+
+    # Returns whether the result has been rolled back.
+    #
+    # @return [Boolean] Whether the result has been rolled back
+    #
+    # @example
+    #   result.rolled_back? # => true
+    #
+    # @rbs @rolled_back: bool
+    attr_accessor :rolled_back
+
     def_delegators :task, :context, :chain, :errors, :dry_run?
     alias ctx context
 
@@ -118,6 +138,7 @@ module CMDx
       @metadata = {}
       @reason = nil
       @cause = nil
+      @retries = 0
       @rolled_back = false
     end
 
@@ -420,15 +441,14 @@ module CMDx
       failed? && !caused_failure?
     end
 
-    # @return [void]
+    # @return [Boolean] Whether the result has been retried
     #
     # @example
-    #   result.rolled_back!
-    #   result.rolled_back? # => true
+    #   result.retried? # => true
     #
-    # @rbs () -> void
-    def rolled_back!
-      @rolled_back = true
+    # @rbs () -> bool
+    def retried?
+      retries.positive?
     end
 
     # @return [Boolean] Whether the result has been rolled back

data/lib/cmdx/task.rb

@@ -217,6 +217,25 @@ module CMDx
       end
       alias remove_attribute remove_attributes
 
+      # @return [Hash] Hash of attribute names to their configurations
+      #
+      # @example
+      #   MyTask.attributes_schema #=> {
+      #     user_id: { name: :user_id, method_name: :user_id, required: true, types: [:integer], options: {}, children: [] },
+      #     email: { name: :email, method_name: :email, required: false, types: [:string], options: { default: nil }, children: [] },
+      #     profile: { name: :profile, method_name: :profile, required: false, types: [:hash], options: {}, children: [
+      #       { name: :bio, method_name: :bio, required: false, types: [:string], options: {}, children: [] },
+      #       { name: :name, method_name: :name, required: true, types: [:string], options: {}, children: [] }
+      #     ] }
+      #   }
+      #
+      # @rbs () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def attributes_schema
+        Array(settings[:attributes]).each_with_object({}) do |attr, schema|
+          schema[attr.method_name] = attr.to_h
+        end
+      end
+
       CallbackRegistry::TYPES.each do |callback|
         # @param callables [Array] Callable objects to register as callbacks
         # @param options [Hash] Options for the callback registration

data/lib/cmdx/validator_registry.rb

@@ -29,6 +29,7 @@ module CMDx
     # @rbs (?Hash[Symbol, Class]? registry) -> void
     def initialize(registry = nil)
       @registry = registry || {
+        absence: Validators::Absence,
         exclusion: Validators::Exclusion,
         format: Validators::Format,
         inclusion: Validators::Inclusion,