cmdx 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a9b1cdaccb648dcffd8c5b50417b2891d2c263f922884b4e8163aa8389a7602
-  data.tar.gz: 7ab3292c7441d0a279c1609e3976c7599ae10ae4168b22aae027667578d0352a
+  metadata.gz: 5dffef0df3a8abb190fc0ca6a194383614fdd81f3eebf22ecab59d8ec047d1d7
+  data.tar.gz: 0f38ccaa12a07c41b64fb4fd3f0685bafb45b7de0b3830243f85a53de4d331c4
 SHA512:
-  metadata.gz: a3c544688dd90eb3e117460f591cd1d85dd3590a1aae8c90e37930c2728ecab5b1ff8ccce06be2cb894627d5d7beca7edebfa313667879e863c0e5338dc7bc29
-  data.tar.gz: a0b6e9c99fc46d3b4bbc627d9967acb8e39fe0fcf1ff51dcc3ab841acabc7b6d6e1bacf3cbaf4a08f0fc9381b409b2829d5f830ecadeefaab9d84647ce28c7cb
+  metadata.gz: 8649dadb0908d88f7441b80d6e3dce03e7f0d20095216d8ac24cc0bf8b1446f57b4552f021a324f47d860112e431b531695a5cd78e84a4b2cf0c3be0dff1224e
+  data.tar.gz: 5e88be6d5a3070d75abbbcb20e25d900db3a44f011f71ed55c61f748cda77e9be4297f12829ab9f28daac66a4b2c511725318ae4e1455793eef8b8f806c3864c

data/.cursor/rules/cursor-instructions.mdc

@@ -17,6 +17,11 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Ruby 3.4+
 - RSpec 3.1+
 
+## Development Guidelines
+- Performance is critical - benchmark any changes that could affect speed
+- Follow existing code patterns and conventions
+- Maintain backward compatibility for public API
+
 ## Code Style and Structure
 - Write concise, idiomatic Ruby code with accurate examples
 - Follow Ruby conventions and best practices
@@ -24,6 +29,7 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Prefer iteration and modularization over code duplication
 - Use descriptive variable and method names (e.g., user_signed_in?, calculate_total)
 - Write comprehensive code documentation using the Yardoc format
+- Minimize object allocations in hot paths
 
 ## Naming Conventions
 - Use snake_case for file names, method names, and variables
@@ -35,6 +41,7 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Use Ruby's expressive syntax (e.g., unless, ||=, &.)
 - Prefer double quotes for strings
 - Respect my Rubocop options
+- Run `bundle exec rubocop .` before finalizing any code changes
 
 ## Performance Optimization
 - Use memoization for expensive operations
@@ -50,6 +57,7 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Don't test declarative configuration
 - Use appropriate matchers
 - Update tests and update Yardocs after you write code
+- Run `bundle rspec .` before finalizing any code changes
 
 ## Documentation
 - Utilize the YARDoc format when documenting Ruby code

data/.yard-lint.yml

@@ -0,0 +1,174 @@
+# YARD-Lint Configuration
+# See https://github.com/mensfeld/yard-lint for documentation
+
+# Global settings for all validators
+AllValidators:
+  # YARD command-line options (applied to all validators by default)
+  YardOptions:
+    - --private
+    - --protected
+
+  # Global file exclusion patterns
+  Exclude:
+    - '\.git'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'spec/**/*'
+    - 'test/**/*'
+
+  # Exit code behavior (error, warning, convention, never)
+  FailOnSeverity: warning
+
+  # Minimum documentation coverage percentage (0-100)
+  # Fails if coverage is below this threshold
+  # MinCoverage: 80.0
+
+  # Diff mode settings
+  DiffMode:
+    # Default base ref for --diff (auto-detects main/master if not specified)
+    DefaultBaseRef: ~
+
+# Documentation validators
+Documentation/UndocumentedObjects:
+  Description: 'Checks for classes, modules, and methods without documentation.'
+  Enabled: false
+  Severity: warning
+  ExcludedMethods:
+    - 'initialize/0'  # Exclude parameter-less initialize
+    - '/^_/'          # Exclude private methods (by convention)
+
+Documentation/UndocumentedMethodArguments:
+  Description: 'Checks for method parameters without @param tags.'
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedBooleanMethods:
+  Description: 'Checks that question mark methods document their boolean return.'
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedOptions:
+  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Enabled: true
+  Severity: warning
+
+Documentation/MarkdownSyntax:
+  Description: 'Detects common markdown syntax errors in documentation.'
+  Enabled: true
+  Severity: warning
+
+# Tags validators
+Tags/Order:
+  Description: 'Enforces consistent ordering of YARD tags.'
+  Enabled: true
+  Severity: convention
+  EnforcedOrder:
+    - param
+    - option
+    - return
+    - raise
+    - example
+
+Tags/InvalidTypes:
+  Description: 'Validates type definitions in @param, @return, @option tags.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: warning
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax consistency.'
+  Enabled: true
+  Severity: convention
+  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/TagTypePosition:
+  Description: 'Validates type annotation position in tags.'
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+    - param
+    - option
+  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
+  #                or 'type_first' (@param [Type] name)
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Description: 'Enforces @api tags on public objects.'
+  Enabled: false  # Opt-in validator
+  Severity: warning
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: 'Requires @option tags for methods with options parameters.'
+  Enabled: true
+  Severity: warning
+
+# Warnings validators - catches YARD parser errors
+Warnings/UnknownTag:
+  Description: 'Detects unknown YARD tags.'
+  Enabled: false
+  Severity: error
+
+Warnings/UnknownDirective:
+  Description: 'Detects unknown YARD directives.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Description: 'Detects malformed tag syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidDirectiveFormat:
+  Description: 'Detects malformed directive syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Description: 'Detects duplicate @param tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Description: 'Detects @param tags for non-existent parameters.'
+  Enabled: true
+  Severity: error
+
+# Semantic validators
+Semantic/AbstractMethods:
+  Description: 'Ensures @abstract methods do not have real implementations.'
+  Enabled: true
+  Severity: warning

data/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
+## [1.12.0] - 2025-12-18
+
+### 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`
+
 ## [1.11.0] - 2025-11-08
 
 ### Updated

data/docs/attributes/definitions.md

@@ -4,6 +4,10 @@ Attributes define your task's interface with automatic validation, type coercion
 
 ## Declarations
 
+!!! warning "Important"
+
+    Attributes are order-dependent, so if you need to reference them as a source or use them in conditions, make sure they’re defined in the correct order.
+
 !!! tip
 
     Prefer using the `required` and `optional` alias for `attributes` for brevity and to clearly signal intent.
@@ -54,7 +58,7 @@ class PublishArticle < CMDx::Task
 
   # Conditionally required
   required :publisher, if: :magazine?
-  required :approver, unless: proc { status == :published }
+  attribute :approver, required: true, unless: proc { status == :published }
 
   def work
     title     #=> "Getting Started with Ruby"

data/docs/attributes/validations.md

@@ -14,10 +14,10 @@ class ProcessSubscription < CMDx::Task
   attribute :user_id, presence: true
 
   # String with length constraints
-  attribute :preferences, length: { minimum: 10, maximum: 500 }
+  optional :preferences, length: { minimum: 10, maximum: 500 }
 
   # Numeric range validation
-  attribute :tier_level, inclusion: { in: 1..5 }
+  required :tier_level, inclusion: { in: 1..5 }
 
   # Format validation for email
   attribute :contact_email, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
@@ -46,6 +46,42 @@ ProcessSubscription.execute(
 
 ### Common Options
 
+```ruby
+class ProcessProduct < CMDx::Task
+  # Allow nil
+  attribute :tier_level, inclusion: {
+    in: 1..5,
+    allow_nil: true
+  }
+
+  # Conditionals
+  optional :contact_email, format: {
+    with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
+    if: ->(value) { value.includes?("@") }
+  }
+  required :status, exclusion: {
+    in: %w[recalled archived],
+    unless: :product_sunsetted?
+  }
+
+  # Custom message
+  attribute :title, length: {
+    within: 5..100,
+    message: "must be in optimal size"
+  }
+
+  def work
+    # Your logic here...
+  end
+
+  private
+
+  def product_defunct?(value)
+    context.company.out_of_business? || value == "deprecated"
+  end
+end
+```
+
 This list of options is available to all validators:
 
 | Option | Description |
@@ -261,10 +297,15 @@ Validation failures provide detailed, structured error messages:
 
 ```ruby
 class CreateProject < CMDx::Task
-  attribute :project_name, presence: true, length: { minimum: 3, maximum: 50 }
-  attribute :budget, numeric: { greater_than: 1000, less_than: 1000000 }
-  attribute :priority, inclusion: { in: [:low, :medium, :high] }
-  attribute :contact_email, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+  attribute :project_name,
+    presence: true,
+    length: { minimum: 3, maximum: 50 }
+  optional :budget,
+    numeric: { greater_than: 1000, less_than: 1000000 }
+  required :priority,
+    inclusion: { in: [:low, :medium, :high] }
+  attribute :contact_email,
+    format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
 
   def work
     # Your logic here...

data/docs/outcomes/result.md

@@ -126,19 +126,20 @@ result = BuildApplication.execute(version: "1.2.3")
 
 # Status-based handlers
 result
-  .handle_success { |result| notify_deployment_ready(result) }
-  .handle_failed { |result| handle_build_failure(result) }
-  .handle_skipped { |result| log_skip_reason(result) }
+  .on(:success) { |result| notify_deployment_ready(result) }
+  .on(:failed) { |result| handle_build_failure(result) }
+  .on(:skipped) { |result| log_skip_reason(result) }
 
 # State-based handlers
 result
-  .handle_complete { |result| update_build_status(result) }
-  .handle_interrupted { |result| cleanup_partial_artifacts(result) }
+  .on(:complete) { |result| update_build_status(result) }
+  .on(:interrupted) { |result| cleanup_partial_artifacts(result) }
+  .on(:executed) { |result| alert_operations_team(result) } #=> .on(:complete, :interrupted)
 
 # Outcome-based handlers
 result
-  .handle_good { |result| increment_success_counter(result) }
-  .handle_bad { |result| alert_operations_team(result) }
+  .on(:good) { |result| increment_success_counter(result) } #=> .on(:success, :skipped)
+  .on(:bad) { |result| alert_operations_team(result) }      #=> .on(:failed, :skipped)
 ```
 
 ## Pattern Matching

data/docs/outcomes/states.md

@@ -53,14 +53,14 @@ result.executed?    #=> true (complete OR interrupted)
 
 ## Handlers
 
-Handle lifecycle events with state-based handlers. Use `handle_executed` for cleanup that runs regardless of outcome:
+Handle lifecycle events with state-based handlers. Use `on(:executed)` for cleanup that runs regardless of outcome:
 
 ```ruby
 result = ProcessVideoUpload.execute
 
 # Individual state handlers
 result
-  .handle_complete { |result| send_upload_notification(result) }
-  .handle_interrupted { |result| cleanup_temp_files(result) }
-  .handle_executed { |result| log_upload_metrics(result) }
+  .on(:complete) { |result| send_upload_notification(result) }
+  .on(:interrupted) { |result| cleanup_temp_files(result) }
+  .on(:executed) { |result| log_upload_metrics(result) } #=> .on(:complete, :interrupted)
 ```

data/docs/outcomes/statuses.md

@@ -47,19 +47,19 @@ result.bad?     #=> true if skipped OR failed (not success)
 
 ## Handlers
 
-Branch business logic with status-based handlers. Use `handle_good` and `handle_bad` for success/skip vs failed outcomes:
+Branch business logic with status-based handlers. Use `on(:good)` and `on(:bad)` for success/skip vs failed outcomes:
 
 ```ruby
 result = ProcessNotification.execute
 
 # Individual status handlers
 result
-  .handle_success { |result| mark_notification_sent(result) }
-  .handle_skipped { |result| log_notification_skipped(result) }
-  .handle_failed { |result| queue_retry_notification(result) }
+  .on(:success) { |result| mark_notification_sent(result) }
+  .on(:skipped) { |result| log_notification_skipped(result) }
+  .on(:failed){ |result| queue_retry_notification(result) }
 
 # Outcome-based handlers
 result
-  .handle_good { |result| update_message_stats(result) }
-  .handle_bad { |result| track_delivery_failure(result) }
+  .on(:good) { |result| update_message_stats(result) }  #=> .on(:success, :skipped)
+  .on(:bad) { |result| track_delivery_failure(result) } #=> .on(:failed, :skipped)
 ```

data/docs/tips_and_tricks.md

@@ -147,7 +147,11 @@ end
 
 ## Useful Examples
 
+- [Active Record Database Transaction](https://github.com/drexed/cmdx/blob/main/examples/active_record_database_transaction.md)
 - [Active Record Query Tagging](https://github.com/drexed/cmdx/blob/main/examples/active_record_query_tagging.md)
+- [Flipper Feature Flags](https://github.com/drexed/cmdx/blob/main/examples/flipper_feature_flags.md)
 - [Paper Trail Whatdunnit](https://github.com/drexed/cmdx/blob/main/examples/paper_trail_whatdunnit.md)
+- [Redis Idempotency](https://github.com/drexed/cmdx/blob/main/examples/redis_idempotency.md)
+- [Sentry Error Tracking](https://github.com/drexed/cmdx/blob/main/examples/sentry_error_tracking.md)
 - [Sidekiq Async Execution](https://github.com/drexed/cmdx/blob/main/examples/sidekiq_async_execution.md)
 - [Stoplight Circuit Breaker](https://github.com/drexed/cmdx/blob/main/examples/stoplight_circuit_breaker.md)

data/examples/active_record_database_transaction.md

@@ -0,0 +1,27 @@
+# Active Record Query Tagging
+
+Wrap task or workflow execution in a database transaction. This is essential for data integrity when multiple steps modify the database.
+
+### Setup
+
+```ruby
+# lib/cmdx_database_transaction_middleware.rb
+class CmdxDatabaseTransactionMiddleware
+  def self.call(task, **options, &)
+    ActiveRecord::Base.transaction(requires_new: true, &)
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  register :middleware, CmdxDatabaseTransactionMiddleware
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/examples/flipper_feature_flags.md

@@ -0,0 +1,50 @@
+# Flipper Feature Flags
+
+Control task execution based on Flipper feature flags.
+
+<https://github.com/flippercloud/flipper>
+
+### Setup
+
+```ruby
+# lib/cmdx_flipper_middleware.rb
+class CmdxFlipperMiddleware
+  def self.call(task, **options, &)
+    feature_name = options.fetch(:feature)
+    actor = options.fetch(:actor, -> { task.context[:user] })
+
+    # Resolve actor if it's a proc
+    actor = actor.call if actor.respond_to?(:call)
+
+    if Flipper.enabled?(feature_name, actor)
+      yield
+    else
+      # Option 1: Skip the task
+      task.skip!("Feature #{feature_name} is disabled")
+
+      # Option 2: Fail the task
+      # task.fail!("Feature #{feature_name} is disabled")
+    end
+  end
+end
+```
+
+### Usage
+
+```ruby
+class NewFeatureTask < CMDx::Task
+  # Execute only if :new_feature is enabled for the user in context
+  register :middleware, CmdxFlipperMiddleware,
+    feature: :new_feature
+
+  # Customize the actor resolution
+  register :middleware, CmdxFlipperMiddleware,
+    feature: :beta_access,
+    actor: -> { task.context[:company] }
+
+  def work
+    # ...
+  end
+end
+```
+

data/examples/redis_idempotency.md

@@ -0,0 +1,71 @@
+# Redis Idempotency
+
+Ensure tasks are executed exactly once using Redis to store execution state. This is critical for non-idempotent operations like charging a credit card or sending an email.
+
+### Setup
+
+```ruby
+# lib/cmdx_redis_idempotency_middleware.rb
+class CmdxRedisIdempotencyMiddleware
+  def self.call(task, **options, &block)
+    key = generate_key(task, options[:key])
+    ttl = options[:ttl] || 5.minutes.to_i
+
+    # Attempt to lock the key
+    if Redis.current.set(key, "processing", nx: true, ex: ttl)
+      begin
+        block.call.tap |result|
+          Redis.current.set(key, result.status, xx: true, ex: ttl)
+        end
+      rescue => e
+        Redis.current.del(key)
+        raise(e)
+      end
+    else
+      # Key exists, handle duplicate
+      status = Redis.current.get(key)
+
+      if status == "processing"
+        task.result.tap { |r| r.skip!("Duplicate request: currently processing", halt: true) }
+      else
+        task.result.tap { |r| r.skip!("Duplicate request: already processed (#{status})", halt: true) }
+      end
+    end
+  end
+
+  def self.generate_key(task, key_gen)
+    id = if key_gen.respond_to?(:call)
+           key_gen.call(task)
+         elsif key_gen.is_a?(Symbol)
+           task.send(key_gen)
+         else
+           task.context[:idempotency_key]
+         end
+
+    "cmdx:idempotency:#{task.class.name}:#{id}"
+  end
+end
+```
+
+### Usage
+
+```ruby
+class ChargeCustomer < CMDx::Task
+  # Use context[:payment_id] as the unique key
+  register :middleware, CmdxIdempotencyMiddleware,
+    key: ->(t) { t.context[:payment_id] }
+
+  def work
+    # Charge logic...
+  end
+end
+
+# First run: Executes
+ChargeCustomer.call(payment_id: "123")
+# => Success
+
+# Second run: Skips
+ChargeCustomer.call(payment_id: "123")
+# => Skipped (reason: "Duplicate request: already processed (success)")
+```
+

data/examples/sentry_error_tracking.md

@@ -0,0 +1,46 @@
+# Sentry Error Tracking
+
+Report unhandled exceptions and unexpected task failures to Sentry with detailed context.
+
+<https://github.com/getsentry/sentry-ruby>
+
+### Setup
+
+```ruby
+# lib/cmdx_sentry_middleware.rb
+class CmdxSentryMiddleware
+  def self.call(task, **options, &)
+    Sentry.with_scope do |scope|
+      scope.set_tags(task: task.class.name)
+      scope.set_context(:user, Current.user.sentry_attributes)
+
+      yield.tap do |result|
+        # Optional: Report logical failures if needed
+        if Array(options[:report_on]).include?(result.status)
+          Sentry.capture_message("Task #{result.status}: #{result.reason}", level: :warning)
+        end
+      end
+    end
+  rescue => e
+    Sentry.capture_exception(e)
+    raise(e) # Re-raise to let the task handle the error or bubble up
+  end
+end
+```
+
+### Usage
+
+```ruby
+class ProcessPayment < CMDx::Task
+  # Report exceptions only
+  register :middleware, CmdxSentryMiddleware
+
+  # Report exceptions AND logical failures (result.failure?)
+  register :middleware, CmdxSentryMiddleware, report_on: %w[failed skipped]
+
+  def work
+    # ...
+  end
+end
+```
+

data/lib/cmdx/attribute.rb

@@ -112,6 +112,7 @@ module CMDx
       #
       # @param names [Array<Symbol, String>] The names of the attributes to create
       # @param options [Hash] Configuration options for the attributes
+      # @option options [Object] :* Any attribute configuration option
       #
       # @yield [self] Block to configure nested attributes
       #
@@ -137,6 +138,7 @@ module CMDx
       #
       # @param names [Array<Symbol, String>] The names of the attributes to create
       # @param options [Hash] Configuration options for the attributes
+      # @option options [Object] :* Any attribute configuration option
       #
       # @yield [self] Block to configure nested attributes
       #
@@ -154,6 +156,7 @@ module CMDx
       #
       # @param names [Array<Symbol, String>] The names of the attributes to create
       # @param options [Hash] Configuration options for the attributes
+      # @option options [Object] :* Any attribute configuration option
       #
       # @yield [self] Block to configure nested attributes
       #
@@ -238,6 +241,7 @@ module CMDx
     #
     # @param names [Array<Symbol, String>] The names of the child attributes
     # @param options [Hash] Configuration options for the child attributes
+    # @option options [Object] :* Any attribute configuration option
     #
     # @yield [self] Block to configure the child attributes
     #
@@ -257,6 +261,7 @@ module CMDx
     #
     # @param names [Array<Symbol, String>] The names of the optional child attributes
     # @param options [Hash] Configuration options for the child attributes
+    # @option options [Object] :* Any attribute configuration option
     #
     # @yield [self] Block to configure the child attributes
     #
@@ -274,6 +279,7 @@ module CMDx
     #
     # @param names [Array<Symbol, String>] The names of the required child attributes
     # @param options [Hash] Configuration options for the child attributes
+    # @option options [Object] :* Any attribute configuration option
     #
     # @yield [self] Block to configure the child attributes
     #