cmdx 1.12.0 → 1.14.0

data/.yard-lint.yml

@@ -1,174 +0,0 @@
-# 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/.yardopts

@@ -1,7 +0,0 @@
---no-private
---output-dir
-docs/api
---exclude
-lib/generators/**/*.rb
-lib/cmdx/railtie.rb
-lib/**/*.rb

data/docs/assets/favicon.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="1000" height="1000"><g clip-path="url(#SvgjsClipPath1038)"><rect width="1000" height="1000" fill="#ffffff"></rect><g transform="matrix(6.235191420376605,0,0,6.235191420376605,175.46452176081812,150)"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="104.098" height="112.266"><svg width="104.098" height="112.266" viewBox="0 0 60 64.708" xmlns="http://www.w3.org/2000/svg"><path d="M29.907 17.723 26.4 23.17 13.384 3.323h3.507l9.508 14.77 1.938-3.139L18.737 0H7.291L26.4 29.262 45.045 0h-3.97L30 17.54zM9.23 61.293H6.091l18.646-29.447L4.43.093H.46l20.308 31.846L0 64.708l10.985-.092 39.138-61.2h3.323L31.57 37.754l13.662 21.415h3.97L35.445 37.754 59.537.093H48.37zm29.63-23.262 15.047 23.262H43.384l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H60L41.17 35.354l-.278-.461z" fill="#000"></path></svg></svg></g></g><defs><clipPath id="SvgjsClipPath1038"><rect width="1000" height="1000" x="0" y="0" rx="150" ry="150"></rect></clipPath></defs></svg>

data/docs/attributes/coercions.md

@@ -1,155 +0,0 @@
-# Attributes - Coercions
-
-Automatically convert inputs to expected types. Coercions handle everything from simple string-to-integer conversions to JSON parsing.
-
-See [Global Configuration](../getting_started.md#coercions) for custom coercion setup.
-
-## Usage
-
-Define attribute types to enable automatic coercion:
-
-```ruby
-class ParseMetrics < CMDx::Task
-  # Coerce into a symbol
-  attribute :measurement_type, type: :symbol
-
-  # Coerce into a rational fallback to big decimal
-  attribute :value, type: [:rational, :big_decimal]
-
-  # Coerce with options
-  attribute :recorded_at, type: :date, strptime: "%m-%d-%Y"
-
-  def work
-    measurement_type #=> :temperature
-    recorded_at      #=> <Date 2024-01-23>
-    value            #=> 98.6 (Float)
-  end
-end
-
-ParseMetrics.execute(
-  measurement_type: "temperature",
-  recorded_at: "01-23-2020",
-  value: "98.6"
-)
-```
-
-!!! tip
-
-    Specify multiple coercion types for attributes that could be a variety of value formats. CMDx attempts each type in order until one succeeds.
-
-## Built-in Coercions
-
-| Type | Options | Description | Examples |
-|------|---------|-------------|----------|
-| `:array` | | Array conversion with JSON support | `"val"` → `["val"]`<br>`"[1,2,3]"` → `[1, 2, 3]` |
-| `:big_decimal` | `:precision` | High-precision decimal | `"123.456"` → `BigDecimal("123.456")` |
-| `:boolean` | | Boolean with text patterns | `"yes"` → `true`, `"no"` → `false` |
-| `:complex` | | Complex numbers | `"1+2i"` → `Complex(1, 2)` |
-| `:date` | `:strptime` | Date objects | `"2024-01-23"` → `Date.new(2024, 1, 23)` |
-| `:datetime` | `:strptime` | DateTime objects | `"2024-01-23 10:30"` → `DateTime.new(2024, 1, 23, 10, 30)` |
-| `:float` | | Floating-point numbers | `"123.45"` → `123.45` |
-| `:hash` | | Hash conversion with JSON support | `'{"a":1}'` → `{"a" => 1}` |
-| `:integer` | | Integer with hex/octal support | `"0xFF"` → `255`, `"077"` → `63` |
-| `:rational` | | Rational numbers | `"1/2"` → `Rational(1, 2)` |
-| `:string` | | String conversion | `123` → `"123"` |
-| `:symbol` | | Symbol conversion | `"abc"` → `:abc` |
-| `:time` | `:strptime` | Time objects | `"10:30:00"` → `Time.new(2024, 1, 23, 10, 30)` |
-
-## Declarations
-
-!!! warning "Important"
-
-    Custom coercions must raise `CMDx::CoercionError` with a descriptive message.
-
-### Proc or Lambda
-
-Use anonymous functions for simple coercion logic:
-
-```ruby
-class TransformCoordinates < CMDx::Task
-  # Proc
-  register :callback, :geolocation, proc do |value, options = {}|
-    begin
-      Geolocation(value)
-    rescue StandardError
-      raise CMDx::CoercionError, "could not convert into a geolocation"
-    end
-  end
-
-  # Lambda
-  register :callback, :geolocation, ->(value, options = {}) {
-    begin
-      Geolocation(value)
-    rescue StandardError
-      raise CMDx::CoercionError, "could not convert into a geolocation"
-    end
-  }
-end
-```
-
-### Class or Module
-
-Register custom coercion logic for specialized type handling:
-
-```ruby
-class GeolocationCoercion
-  def self.call(value, options = {})
-    Geolocation(value)
-  rescue StandardError
-    raise CMDx::CoercionError, "could not convert into a geolocation"
-  end
-end
-
-class TransformCoordinates < CMDx::Task
-  register :coercion, :geolocation, GeolocationCoercion
-
-  attribute :latitude, type: :geolocation
-end
-```
-
-## Removals
-
-Remove unwanted coercions:
-
-!!! warning
-
-    Each `deregister` call removes one coercion. Use multiple calls for batch removals.
-
-```ruby
-class TransformCoordinates < CMDx::Task
-  deregister :coercion, :geolocation
-end
-```
-
-## Error Handling
-
-Coercion failures provide detailed error information including attribute paths, attempted types, and specific failure reasons:
-
-```ruby
-class AnalyzePerformance < CMDx::Task
-  attribute  :iterations, type: :integer
-  attribute  :score, type: [:float, :big_decimal]
-
-  def work
-    # Your logic here...
-  end
-end
-
-result = AnalyzePerformance.execute(
-  iterations: "not-a-number",
-  score: "invalid-float"
-)
-
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.reason   #=> "Invalid"
-result.metadata #=> {
-                #     errors: {
-                #       full_message: "iterations could not coerce into an integer. score could not coerce into one of: float, big_decimal.",
-                #       messages: {
-                #         iterations: ["could not coerce into an integer"],
-                #         score: ["could not coerce into one of: float, big_decimal"]
-                #       }
-                #     }
-                #   }
-```

data/docs/attributes/defaults.md

@@ -1,77 +0,0 @@
-# Attributes - Defaults
-
-Provide fallback values for optional attributes. Defaults kick in when values aren't provided or are `nil`.
-
-## Declarations
-
-Defaults work seamlessly with coercions, validations, and nested attributes:
-
-### Static Values
-
-```ruby
-class OptimizeDatabase < CMDx::Task
-  attribute :strategy, default: :incremental
-  attribute :level, default: "basic"
-  attribute :notify_admin, default: true
-  attribute :timeout_minutes, default: 30
-  attribute :indexes, default: []
-  attribute :options, default: {}
-
-  def work
-    strategy        #=> :incremental
-    level           #=> "basic"
-    notify_admin    #=> true
-    timeout_minutes #=> 30
-    indexes         #=> []
-    options         #=> {}
-  end
-end
-```
-
-### Symbol References
-
-Reference instance methods by symbol for dynamic default values:
-
-```ruby
-class ProcessAnalytics < CMDx::Task
-  attribute :granularity, default: :default_granularity
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def default_granularity
-    Current.user.premium? ? "hourly" : "daily"
-  end
-end
-```
-
-### Proc or Lambda
-
-Use anonymous functions for dynamic default values:
-
-```ruby
-class CacheContent < CMDx::Task
-  # Proc
-  attribute :expire_hours, default: proc { Current.tenant.cache_duration || 24 }
-
-  # Lambda
-  attribute :compression, default: -> { Current.tenant.premium? ? "gzip" : "none" }
-end
-```
-
-## Coercions and Validations
-
-Defaults follow the same coercion and validation rules as provided values:
-
-```ruby
-class ScheduleBackup < CMDx::Task
-  # Coercions
-  attribute :retention_days, default: "7", type: :integer
-
-  # Validations
-  optional :frequency, default: "daily", inclusion: { in: %w[hourly daily weekly monthly] }
-end
-```

data/docs/attributes/definitions.md

@@ -1,283 +0,0 @@
-# Attributes - Definitions
-
-Attributes define your task's interface with automatic validation, type coercion, and accessor generation. They're the contract between callers and your business logic.
-
-## 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.
-
-### Optional
-
-Optional attributes return `nil` when not provided.
-
-```ruby
-class ScheduleEvent < CMDx::Task
-  attribute :title
-  attributes :duration, :location
-
-  # Alias for attributes (preferred)
-  optional :description
-  optional :visibility, :attendees
-
-  def work
-    title       #=> "Team Standup"
-    duration    #=> 30
-    location    #=> nil
-    description #=> nil
-    visibility  #=> nil
-    attendees   #=> ["alice@company.com", "bob@company.com"]
-  end
-end
-
-# Attributes passed as keyword arguments
-ScheduleEvent.execute(
-  title: "Team Standup",
-  duration: 30,
-  attendees: ["alice@company.com", "bob@company.com"]
-)
-```
-
-### Required
-
-Required attributes must be provided in call arguments or task execution will fail.
-
-```ruby
-class PublishArticle < CMDx::Task
-  attribute :title, required: true
-  attributes :content, :author_id, required: true
-
-  # Alias for attributes => required: true (preferred)
-  required :category
-  required :status, :tags
-
-  # Conditionally required
-  required :publisher, if: :magazine?
-  attribute :approver, required: true, unless: proc { status == :published }
-
-  def work
-    title     #=> "Getting Started with Ruby"
-    content   #=> "This is a comprehensive guide..."
-    author_id #=> 42
-    category  #=> "programming"
-    status    #=> :published
-    tags      #=> ["ruby", "beginner"]
-    publisher #=> "Eastbay"
-    approver  #=> #<Editor ...>
-  end
-
-  private
-
-  def magazine?
-    context.title.ends_with?("[M]")
-  end
-end
-```
-
-!!! note
-
-    When a required attribute's condition evaluates to `false`, the attribute behaves as optional. All other attribute features such as coercions, validations, defaults, and transformations still apply normally.
-
-## Sources
-
-Attributes read from any accessible object—not just context. Use sources to pull data from models, services, or any callable:
-
-### Context
-
-```ruby
-class BackupDatabase < CMDx::Task
-  # Default source is :context
-  required :database_name
-  optional :compression_level
-
-  # Explicitly specify context source
-  attribute :backup_path, source: :context
-
-  def work
-    database_name     #=> context.database_name
-    backup_path       #=> context.backup_path
-    compression_level #=> context.compression_level
-  end
-end
-```
-
-### Symbol References
-
-Reference instance methods by symbol for dynamic source values:
-
-```ruby
-class BackupDatabase < CMDx::Task
-  attributes :host, :credentials, source: :database_config
-
-  # Access from declared attributes
-  attribute :connection_string, source: :credentials
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def database_config
-    @database_config ||= DatabaseConfig.find(context.database_name)
-  end
-end
-```
-
-### Proc or Lambda
-
-Use anonymous functions for dynamic source values:
-
-```ruby
-class BackupDatabase < CMDx::Task
-  # Proc
-  attribute :timestamp, source: proc { Time.current }
-
-  # Lambda
-  attribute :server, source: -> { Current.server }
-end
-```
-
-### Class or Module
-
-For complex source logic, use classes or modules:
-
-```ruby
-class DatabaseResolver
-  def self.call(task)
-    Database.find(task.context.database_name)
-  end
-end
-
-class BackupDatabase < CMDx::Task
-  # Class or Module
-  attribute :schema, source: DatabaseResolver
-
-  # Instance
-  attribute :metadata, source: DatabaseResolver.new
-end
-```
-
-## Nesting
-
-Build complex structures with nested attributes. Children inherit their parent as source and support all attribute options:
-
-!!! note
-
-    Nested attributes support all features: naming, coercions, validations, defaults, and more.
-
-```ruby
-class ConfigureServer < CMDx::Task
-  # Required parent with required children
-  required :network_config do
-    required :hostname, :port, :protocol, :subnet
-    optional :load_balancer
-    attribute :firewall_rules
-  end
-
-  # Optional parent with conditional children
-  optional :ssl_config do
-    required :certificate_path, :private_key # Only required if ssl_config provided
-    optional :enable_http2, prefix: true
-  end
-
-  # Multi-level nesting
-  attribute :monitoring do
-    required :provider
-
-    optional :alerting do
-      required :threshold_percentage
-      optional :notification_channel
-    end
-  end
-
-  def work
-    network_config   #=> { hostname: "api.company.com" ... }
-    hostname         #=> "api.company.com"
-    load_balancer    #=> nil
-  end
-end
-
-ConfigureServer.execute(
-  server_id: "srv-001",
-  network_config: {
-    hostname: "api.company.com",
-    port: 443,
-    protocol: "https",
-    subnet: "10.0.1.0/24",
-    firewall_rules: "allow_web_traffic"
-  },
-  monitoring: {
-    provider: "datadog",
-    alerting: {
-      threshold_percentage: 85.0,
-      notification_channel: "slack"
-    }
-  }
-)
-```
-
-!!! warning "Important"
-
-    Child requirements only apply when the parent is provided—perfect for optional structures.
-
-## Error Handling
-
-Validation failures provide detailed, structured error messages:
-
-!!! note
-
-    Nested attributes are only validated when their parent is present and valid.
-
-```ruby
-class ConfigureServer < CMDx::Task
-  required :server_id, :environment
-  required :network_config do
-    required :hostname, :port
-  end
-
-  def work
-    # Your logic here...
-  end
-end
-
-# Missing required top-level attributes
-result = ConfigureServer.execute(server_id: "srv-001")
-
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.reason   #=> "Invalid"
-result.metadata #=> {
-                #     errors: {
-                #       full_message: "environment is required. network_config is required.",
-                #       messages: {
-                #         environment: ["is required"],
-                #         network_config: ["is required"]
-                #       }
-                #     }
-                #   }
-
-# Missing required nested attributes
-result = ConfigureServer.execute(
-  server_id: "srv-001",
-  environment: "production",
-  network_config: { hostname: "api.company.com" } # Missing port
-)
-
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-result.reason   #=> "Invalid"
-result.metadata #=> {
-                #     errors: {
-                #       full_message: "port is required.",
-                #       messages: {
-                #         port: ["is required"]
-                #       }
-                #     }
-                #   }
-```