castkit 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d47af535f6e3f14f248ba864df4761e5ca2918f7153ec5336a932842a2329576
-  data.tar.gz: f7c5112a38faa006476b4758ad1b80be18323cbb5300c04cb5a39a92aa559fa8
+  metadata.gz: f048458a9f967984b6b590c1e6bf2348a43c90936374b4d8755c6f7151057fe8
+  data.tar.gz: 182e73cec494a329bc670999cceab4a3c1e057eb6108097c759989102232ec94
 SHA512:
-  metadata.gz: cfcb5f523b1c875af1685e9643dd19e144984cc528c6cfcc7914b8def979023905e17eddbefda4ba65eb2756098565af77226fc67ed427a084de60e476652f05
-  data.tar.gz: 3ed9aef95fd9f1634ca38544a6b3e937e4da5a88c3b99a29f93c6481e48171f9780462dbd8f41d41162a8e1b40cf657143d756c4fdcf6cc887b8d4e5dd71d02f
+  metadata.gz: 4d8bc7bdd0ed6c26f7fb7a621306995b4fbfbbe6d1d331ffa813ffc4c13a2d2795b72af9f977bc618e950c8dfdc5b017bb95563a436520e4e545efdf1a9a0b50
+  data.tar.gz: 196ed35dd105ad854ac74fa4540cbfbb04de30885069719ab80bb84d5a41b8ea8e64df1e085753477dab3bf54f998db20684b5cd6460af4c87447594c320edd3

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 ## [Unreleased]
 
+## [0.3.0] - 2025-04-16
+
+### Added
+
+- **CLI System (`castkit`)**:
+  - Introduced a full-featured CLI for generating and inspecting Castkit components.
+  - Supports:
+    - `castkit generate [component]` for scaffolding types, data objects, contracts, serializers, validators, and plugins.
+    - `castkit list [types|validators|contracts|dataobjects|serializers]` for inspecting the internal registry and available classes.
+  - Enables developer productivity and exploration through a single entry point.
+
+- **Plugin System**:
+  - Added `Castkit::Plugins` for modular runtime extensions.
+  - Plugins can be registered and activated on DTO classes via:
+
+    ```ruby
+    Castkit.configure do |config|
+      config.register_plugin(:oj, MyOjPlugin)
+    end
+
+    class MyDto < Castkit::DataObject
+      enable_plugins :oj
+    end
+    ```
+
+  - Plugins support `setup!(klass)` for optional initialization logic.
+
+- **Base Class Renames**:
+  - Introduced consistent naming conventions with `Castkit::Types::Base`, `Castkit::Serializers::Base`, `Castkit::Validators::Base`, etc.
+  - These will be excluded from list output automatically in CLI commands.
+
+---
+
 ## [0.2.0] - 2025-04-14
 
 ### Added
@@ -42,6 +75,8 @@
 
 - **Union type validation support** for both `Castkit::DataObject` and contracts, allowing attributes to accept multiple types (e.g., `[:string, :integer]`).
 
+---
+
 ## [0.1.2] - 2025-04-14
 
 ### Added
@@ -71,6 +106,8 @@
   end
   ```
 
+---
+
 ## [0.1.1] - 2025-04-13
 
 ### Added
@@ -87,6 +124,8 @@
 
   Useful when working with nested DataObject collections (e.g., for integration with ActiveRecord or serialization logic).
 
+---
+
 ## [0.1.0] - 2025-04-12
 
 - Initial release

data/README.md

@@ -215,7 +215,7 @@ class Metadata < Castkit::DataObject
 end
 
 class PageDto < Castkit::DataObject
-  dataobject :metadata, unwrapped: true, prefix: "meta"
+  dataobject :metadata, Metadata, unwrapped: true, prefix: "meta"
 end
 
 # Serializes as:
@@ -523,7 +523,7 @@ end
 
 class UserDto < Castkit::DataObject
   string :id
-  dataobject :address, of: AddressDto
+  dataobject :address, AddressDto
 end
 
 UserContract = Castkit::Contract.from_dataobject(UserDto)
@@ -576,7 +576,7 @@ Castkit.configure do |config|
 end
 
 class MyDto < Castkit::DataObject
-  Castkit::Plugins.activate(self, :my_plugin)
+  enable_plugins :my_plugin
 end
 ```
 
@@ -600,6 +600,14 @@ You can then activate them:
 Castkit::Plugins.activate(MyDto, :oj)
 ```
 
+Or by using the `enable_plugins` helper method in `Castkit::DataObject`:
+
+```ruby
+class MyDto < Castkit::DataObject
+  enable_plugins :oj, :yaml
+end
+```
+
 ---
 
 ### 🧰 Plugin API

data/castkit.gemspec

@@ -38,5 +38,7 @@ Gem::Specification.new do |spec|
   # Development dependencies
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "simplecov-cobertura"
   spec.add_development_dependency "yard"
 end

data/lib/castkit/attribute.rb

@@ -1,46 +1,103 @@
 # frozen_string_literal: true
 
+require_relative "castkit"
 require_relative "error"
-require_relative "ext/attribute/options"
-require_relative "ext/attribute/access"
-require_relative "ext/attribute/validation"
+require_relative "attributes/options"
+require_relative "dsl/attribute"
 
 module Castkit
-  # Represents a typed attribute on a Castkit::DataObject.
+  # Represents a typed attribute on a `Castkit::DataObject`.
   #
-  # Provides casting, validation, access control, and serialization behavior.
+  # This class is responsible for:
+  # - Type normalization (symbol, class, or data object)
+  # - Default and option resolution
+  # - Validation hooks
+  # - Access and serialization control
+  #
+  # Attributes are created automatically when using the DSL in `DataObject`, but
+  # can also be created manually or through reusable definitions.
+  #
+  # @see Castkit::Attributes::Definition
+  # @see Castkit::DSL::Attribute::Options
+  # @see Castkit::DSL::Attribute::Access
+  # @see Castkit::DSL::Attribute::Validation
   class Attribute
-    include Castkit::Ext::Attribute::Options
-    include Castkit::Ext::Attribute::Access
-    include Castkit::Ext::Attribute::Validation
+    include Castkit::DSL::Attribute
+
+    class << self
+      # Defines a reusable attribute definition via a DSL wrapper.
+      #
+      # @param type [Symbol, Class] The base type to define.
+      # @param options [Hash] Additional attribute options.
+      # @yield The block to configure options or transformations.
+      # @return [Array<(Symbol, Hash)>] a tuple of the final type and options hash
+      def define(type, **options, &block)
+        normalized_type = normalize_type(type)
+        Castkit::Attributes::Definition.define(normalized_type, **options, &block)
+      end
+
+      # Normalizes a declared type (symbol, class, or array) for internal usage.
+      #
+      # @param type [Symbol, Class, Array] the input type
+      # @return [Symbol, Class<Castkit::DataObject>] the normalized form
+      def normalize_type(type)
+        return type.map { |t| normalize_type(t) } if type.is_a?(Array)
+        return type if Castkit.dataobject?(type)
+
+        process_type(type).to_sym
+      end
+
+      # Converts a raw type into a normalized symbol.
+      #
+      # Recognized forms:
+      # - `TrueClass`/`FalseClass` → `:boolean`
+      # - Class → `class.name.downcase.to_sym`
+      # - Symbol → passed through
+      #
+      # @param type [Symbol, Class] the type to convert
+      # @return [Symbol] normalized type symbol
+      # @raise [Castkit::AttributeError] if the type is invalid
+      def process_type(type)
+        case type
+        when Class
+          return :boolean if [TrueClass, FalseClass].include?(type)
+
+          type.name.downcase.to_sym
+        when Symbol
+          type
+        else
+          raise Castkit::AttributeError, "Unknown type: #{type.inspect}"
+        end
+      end
+    end
 
     # @return [Symbol] the attribute name
     attr_reader :field
 
-    # @return [Symbol, Class, Array] the declared type (normalized)
+    # @return [Symbol, Class, Array] the declared or normalized type
     attr_reader :type
 
-    # @return [Hash] attribute options (including aliases, default, access, etc.)
+    # @return [Hash] full option hash, including merged defaults
     attr_reader :options
 
     # Initializes a new attribute definition.
     #
-    # @param field [Symbol] the name of the attribute
-    # @param type [Symbol, Class, Array] the type or array of types
-    # @param default [Object, Proc] optional default value
-    # @param options [Hash] additional configuration options
+    # @param field [Symbol] the attribute name
+    # @param type [Symbol, Class, Array<Symbol, Class>] the type (or list of types)
+    # @param default [Object, Proc, nil] optional static or callable default
+    # @param options [Hash] additional attribute options
     def initialize(field, type, default: nil, **options)
       @field = field
-      @type = normalize_type(type)
+      @type = self.class.normalize_type(type)
       @default = default
       @options = populate_options(options)
 
       validate!
     end
 
-    # Returns a hash representation of the attribute definition.
+    # Converts the attribute definition to a serializable hash.
     #
-    # @return [Hash]
+    # @return [Hash] the full attribute metadata
     def to_hash
       {
         field: field,
@@ -55,56 +112,22 @@ module Castkit
 
     private
 
-    # Populates default values and normalizes internal options.
+    # Populates default values and prepares internal options.
     #
-    # @param options [Hash]
-    # @return [Hash]
+    # @param options [Hash] the user-provided options
+    # @return [Hash] the merged and normalized options
     def populate_options(options)
-      options = DEFAULT_OPTIONS.merge(options)
+      options = Castkit::Attributes::Options::DEFAULTS.merge(options)
       options[:aliases] = Array(options[:aliases] || [])
-      options[:of] = normalize_type(options[:of]) if options[:of]
+      options[:of] = self.class.normalize_type(options[:of]) if options[:of]
 
       options
     end
 
-    # Normalizes a declared type to a symbol or class reference.
-    #
-    # @param type [Symbol, Class, Array]
-    # @return [Symbol, Class, Array]
-    # @raise [Castkit::AttributeError] if the type is not valid
-    def normalize_type(type)
-      return type.map { |t| normalize_type(t) } if type.is_a?(Array)
-      return type if Castkit.dataobject?(type)
-
-      process_type(type)
-    end
-
-    # Converts a single type value into a normalized internal representation.
-    #
-    # - Maps `TrueClass`/`FalseClass` to `:boolean`
-    # - Converts class names (e.g., `String`, `Integer`) to lowercase symbols
-    # - Accepts already-symbolized types (e.g., `:string`)
-    #
-    # @param type [Class, Symbol] the declared type to process
-    # @return [Symbol] the normalized type
-    # @raise [Castkit::AttributeError] if the type is not a recognized form
-    def process_type(type)
-      case type
-      when Class
-        return :boolean if [TrueClass, FalseClass].include?(type)
-
-        type.name.downcase.to_sym
-      when Symbol
-        type
-      else
-        raise_error!("Unknown type: #{type.inspect}")
-      end
-    end
-
-    # Raises a Castkit::AttributeError with optional context.
+    # Raises a standardized attribute error with context.
     #
-    # @param message [String]
-    # @param context [Hash, nil]
+    # @param message [String] the error message
+    # @param context [Hash, nil] optional override for context payload
     # @raise [Castkit::AttributeError]
     def raise_error!(message, context: nil)
       raise Castkit::AttributeError.new(message, context: context || to_h)

data/lib/castkit/attributes/definition.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "options"
+
+module Castkit
+  module Attributes
+    # Provides a class-based DSL for defining reusable attribute definitions.
+    #
+    # Extend this class in a subclass of `Castkit::Attributes::Base` to define
+    # shared attribute settings that can be reused across multiple DataObjects.
+    #
+    # @example Defining a reusable attribute
+    #   class UuidDefinition < Castkit::Attributes::Base
+    #     type :string
+    #     required true
+    #     format /\A[0-9a-f\-]{36}\z/
+    #   end
+    #
+    #   attribute :id, UuidDefinition.definition
+    #
+    class Definition
+      extend Castkit::Attributes::Options
+
+      class << self
+        # @return [Hash] the internal definition hash, containing the type and options
+        def definition
+          @definition ||= {
+            type: nil,
+            options: Castkit::Attributes::Options::DEFAULTS.dup
+          }
+        end
+
+        # @return [Hash] the attribute options defined on this class
+        def options
+          definition[:options]
+        end
+
+        # Defines the attribute's type and configuration using a DSL block.
+        #
+        # @param type [Symbol, Class<Castkit::DataObject>] the attribute type (e.g., :string, :integer)
+        # @param options [Hash] additional options to merge after the block (e.g., default:, access:)
+        # @yield DSL block used to set options like `required`, `format`, `readonly`, etc.
+        # @return [Array<(Symbol, Hash)>] a tuple of the final type and options hash
+        #
+        # @example
+        #   define :string, default: "none" do
+        #     required true
+        #     access [:read]
+        #   end
+        def define(type, **options, &block)
+          @__castkit_attribute_dsl = true
+
+          definition[:type] = type
+          instance_eval(&block)
+          definition[:options] = definition[:options].merge(options)
+
+          definition
+        ensure
+          @__castkit_attribute_dsl = false
+        end
+      end
+    end
+  end
+end

data/lib/castkit/attributes/options.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Attributes
+    # Provides a DSL for configuring attribute options within an attribute definition.
+    #
+    # This module is designed to be extended by class-level definition objects such as
+    # `Castkit::Attributes::Definition`, and is used to build reusable sets of options
+    # for attributes declared within `Castkit::DataObject` classes.
+    #
+    # @example
+    #   class OptionalString < Castkit::Attributes::Definition
+    #     type :string
+    #     required false
+    #     ignore_blank true
+    #   end
+    module Options
+      # Valid access modes for an attribute.
+      #
+      # @return [Array<Symbol>]
+      ACCESS_MODES = %i[read write].freeze
+
+      # Default configuration for attribute options.
+      #
+      # @return [Hash{Symbol => Object}]
+      DEFAULTS = {
+        required: true,
+        ignore_nil: false,
+        ignore_blank: false,
+        ignore: false,
+        composite: false,
+        transient: false,
+        unwrapped: false,
+        prefix: nil,
+        access: ACCESS_MODES,
+        force_type: !Castkit.configuration.enforce_typing
+      }.freeze
+
+      # Sets or retrieves the attribute type.
+      #
+      # @param value [Symbol, nil] The type to assign (e.g., :string), or nil to fetch.
+      # @return [Symbol]
+      def type(value = nil)
+        value.nil? ? definition[:type] : (definition[:type] = value.to_sym)
+      end
+
+      # Sets the element type for array attributes.
+      #
+      # @param value [Symbol, Class] the type of elements in the array
+      # @return [void]
+      def of(value)
+        return unless @type == :array
+
+        set_option(:of, value)
+      end
+
+      # Sets the default value or proc for the attribute.
+      #
+      # @param value [Object, Proc] the default value or lambda
+      # @return [void]
+      def default(value = nil)
+        set_option(:default, value)
+      end
+
+      # Enables or disables forced typecasting, or sets a custom flag.
+      #
+      # @param value [Boolean, nil] the forced type flag
+      # @return [void]
+      def force_type(value = nil)
+        set_option(:force_type, value || !Castkit.configuration.enforce_typing)
+      end
+
+      # Marks the attribute as required or optional.
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def required(value = nil)
+        set_option(:required, value || true)
+      end
+
+      # Marks the attribute to be ignored entirely.
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def ignore(value = nil)
+        set_option(:ignore, value || true)
+      end
+
+      # Ignores `nil` values during serialization or persistence.
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def ignore_nil(value = nil)
+        set_option(:ignore_nil, value || true)
+      end
+
+      # Ignores blank values (`""`, `[]`, `{}`) during serialization.
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def ignore_blank(value = nil)
+        set_option(:ignore_blank, value || true)
+      end
+
+      # Adds a prefix for unwrapped attribute keys.
+      #
+      # @param value [String, Symbol, nil]
+      # @return [void]
+      def prefix(value = nil)
+        set_option(:prefix, value)
+      end
+
+      # Marks the attribute as unwrapped (inline merging of nested fields).
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def unwrapped(value = nil)
+        set_option(:unwrapped, value || true)
+      end
+
+      # Sets access modes for the attribute.
+      #
+      # @param value [Array<Symbol>, Symbol] valid values: `:read`, `:write`, or both
+      # @return [void]
+      def access(value = nil)
+        value = validate_access_modes!(value)
+        set_option(:access, value)
+      end
+
+      # Shortcut to make the attribute readonly (`access: [:read]`).
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def readonly(value = nil)
+        value = value || true ? [:read] : ACCESS_MODES
+        set_option(:access, value)
+      end
+
+      # Marks the attribute as a composite (e.g., nested `DataObject`).
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def composite(value = nil)
+        set_option(:composite, value || true)
+      end
+
+      # Marks the attribute as transient (not included in persistence or serialization).
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def transient(value = nil)
+        set_option(:transient, value || true)
+      end
+
+      # Sets a format constraint (e.g., regex validation).
+      #
+      # @param value [Regexp]
+      # @return [void]
+      def format(value)
+        set_option(:format, value)
+      end
+
+      # Attaches a custom validator callable for this attribute.
+      #
+      # @param value [Proc, #call]
+      # @return [void]
+      def validator(value)
+        set_option(:validator, value)
+      end
+
+      private
+
+      # Converts class or symbol into a normalized type symbol.
+      #
+      # @param type [Class, Symbol]
+      # @return [Symbol]
+      # @raise [Castkit::AttributeError] if type cannot be resolved
+      def process_type(type)
+        case type
+        when Class
+          return :boolean if [TrueClass, FalseClass].include?(type)
+
+          type.name.downcase.to_sym
+        when Symbol
+          type
+        else
+          raise Castkit::AttributeError.new("Unknown type: #{type.inspect}", context: to_h)
+        end
+      end
+
+      # Sets an option key-value pair in the current definition.
+      #
+      # @param option [Symbol]
+      # @param value [Object, nil]
+      # @return [Object, nil]
+      def set_option(option, value)
+        value.nil? ? definition[:options][option] : (definition[:options][option] = value)
+      end
+
+      # Validates and normalizes access mode array.
+      #
+      # @param value [Array<Symbol>, Symbol, nil]
+      # @return [Array<Symbol>]
+      # @raise [Castkit::AttributeError] if invalid modes are present
+      def validate_access_modes!(value)
+        value_array = Array(value || ACCESS_MODES).compact
+        unknown_modes = value_array - ACCESS_MODES
+        return value_array if unknown_modes.empty?
+
+        raise Castkit::AttributeError.new("Unknown access flags: #{unknown_modes.inspect}", context: to_h)
+      end
+    end
+  end
+end

data/lib/castkit/castkit.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "configuration"
-require_relative "inflector"
+require_relative "core/attribute_types"
 
 # Castkit is a lightweight, type-safe data object system for Ruby.
 #
@@ -63,7 +62,10 @@ module Castkit
     # @param obj [Object] the object to test
     # @return [Boolean] true if obj is a Castkit::DataObject class
     def dataobject?(obj)
-      obj.is_a?(Class) && obj.ancestors.include?(Castkit::DataObject)
+      obj.is_a?(Class) && (
+        obj <= Castkit::DataObject ||
+          obj.ancestors.include?(Castkit::DSL::DataObject)
+      )
     end
 
     # Returns a type caster lambda for the given type.
@@ -105,3 +107,11 @@ module Castkit
     end
   end
 end
+
+require_relative "configuration"
+require_relative "plugins"
+require_relative "inflector"
+require_relative "version"
+require_relative "attribute"
+require_relative "contract"
+require_relative "data_object"

data/lib/castkit/cli/generate.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "thor"
+require_relative "../../generators/attribute"
 require_relative "../../generators/contract"
 require_relative "../../generators/data_object"
 require_relative "../../generators/plugin"
@@ -30,6 +31,19 @@ module Castkit
         Castkit::Generators::Contract.start(args)
       end
 
+      desc "attribute NAME", "Generates a new Castkit attribute"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new attribute definition class.
+      #
+      # @param name [String] the class name for the attribute
+      # @param fields [Array<String>] optional attribute options
+      # @return [void]
+      def attribute(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Attribute.start(args)
+      end
+
       desc "dataobject NAME", "Generates a new Castkit DataObject"
       method_option :spec, type: :boolean, default: true
       # Generates a new DataObject class.

data/lib/castkit/contract/base.rb

@@ -2,7 +2,6 @@
 
 require_relative "../core/config"
 require_relative "../core/attribute_types"
-require_relative "../core/registerable"
 require_relative "result"
 
 module Castkit
@@ -33,23 +32,12 @@ module Castkit
     class Base
       extend Castkit::Core::Config
       extend Castkit::Core::AttributeTypes
-      extend Castkit::Core::Registerable
 
       ATTRIBUTE_OPTIONS = %i[
         required aliases min max format of validator unwrapped prefix force_type
       ].freeze
 
       class << self
-        # Registers the current class under `Castkit::Contracts`.
-        #
-        # @param as [String, Symbol, nil] The constant name to use (PascalCase). Defaults to the name used when building
-        #   the contract. If no name was provided, an error is raised.
-        # @return [Class] the registered contract class
-        # @raise [Castkit::Error] If a name cannot be resolved.
-        def register!(as: nil)
-          super(namespace: :contracts, as: as || definition[:name])
-        end
-
         # Defines an attribute for the contract.
         #
         # Only a subset of options is allowed inside a contract.