castkit 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d13b67e4f2a1e249d92cb88332e6a87724273673ddea91e6e522d7bde8fc3de6
-  data.tar.gz: 8608ab59c8bb96c9bc3d79250e5a106b025f2a09e4b18bb09ce462ea95c0f4a1
+  metadata.gz: f048458a9f967984b6b590c1e6bf2348a43c90936374b4d8755c6f7151057fe8
+  data.tar.gz: 182e73cec494a329bc670999cceab4a3c1e057eb6108097c759989102232ec94
 SHA512:
-  metadata.gz: 36d802f0842118f2f064e2a15e3fb691f263b6d609267b2d65da5a8ee6e9c844a507387c3ab60cd088616dd8ec51bc0fa768adf9ad92bf2e515c4a2b77d65e32
-  data.tar.gz: aad2e99da5cc53214faf19880eae57edf66668fdbe63147a44597f2a605962bcb22b6ec58a6f0b1aad9d79aef6f248e51e4cfe36e55fa7e60262dbc1502e080e
+  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
@@ -10,7 +43,7 @@
   - Developers may register custom types via `Castkit.configure`:
 
     ```ruby
-    class CustomType < Castkit::Types::Generic
+    class CustomType < Castkit::Types::Base
       def deserialize(value) ... end
       def validate!(value, **) ... end
     end
@@ -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

@@ -21,6 +21,8 @@ Castkit is designed to work seamlessly in service-oriented and API-driven archit
 - [DataObjects](#dataobjects)
 - [Contracts](#contracts)
 - [Advance Usage](#advanced-usage-coming-soon)
+- [Plugins](#plugins)
+- [Castkit CLI](#castkit-cli)
 - [Testing](#testing)
 - [Compatibility](#compatibility)
 - [License](#license)
@@ -58,14 +60,14 @@ Castkit comes with built-in support for primitive types and allows registration
 
 ```ruby
 {
-  array:    Castkit::Types::Collection,
-  boolean:  Castkit::Types::Boolean,
-  date:     Castkit::Types::Date,
-  datetime: Castkit::Types::DateTime,
-  float:    Castkit::Types::Float,
-  hash:     Castkit::Types::Generic,
-  integer:  Castkit::Types::Integer,
-  string:   Castkit::Types::String
+        array: Castkit::Types::Collection,
+        boolean: Castkit::Types::Boolean,
+        date: Castkit::Types::Date,
+        datetime: Castkit::Types::DateTime,
+        float: Castkit::Types::Float,
+        hash: Castkit::Types::Base,
+        integer: Castkit::Types::Integer,
+        string: Castkit::Types::String
 }
 ```
 
@@ -213,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:
@@ -374,7 +376,8 @@ from_contract = Castkit::DataObject.from_contract(contract)
 To override default serialization behavior:
 
 ```ruby
-class CustomSerializer < Castkit::Serializer
+
+class CustomSerializer < Castkit::Serializers::Base
   def call
     { payload: object.to_h }
   end
@@ -427,7 +430,8 @@ end
 Or subclass directly:
 
 ```ruby
-class MyContract < Castkit::Contract::Generic
+
+class MyContract < Castkit::Contract::Base
   string :id
   integer :count, required: false
 end
@@ -519,7 +523,7 @@ end
 
 class UserDto < Castkit::DataObject
   string :id
-  dataobject :address, of: AddressDto
+  dataobject :address, AddressDto
 end
 
 UserContract = Castkit::Contract.from_dataobject(UserDto)
@@ -532,7 +536,7 @@ UserContract.validate!(id: "abc", address: { city: "Boston" })
 
 Castkit is designed to be modular and extendable. Future guides will cover:
 
-- Custom serializers (`Castkit::Serializer`)
+- Custom serializers (`Castkit::Serializers::Base`)
 - Integration layers:
     - `castkit-activerecord` for syncing with ActiveRecord models
     - `castkit-msgpack` for binary encoding
@@ -543,6 +547,286 @@ Castkit is designed to be modular and extendable. Future guides will cover:
 
 ---
 
+## Plugins
+
+Castkit supports modular extensions through a lightweight plugin system. Plugins can modify or extend the behavior of `Castkit::DataObject` classes, such as adding serialization support, transformation helpers, or framework integrations.
+
+Plugins are just Ruby modules and can be registered and activated globally or per-class.
+
+---
+
+### 📦 Activating Plugins
+
+Plugins can be activated on any DataObject or at runtime:
+
+```ruby
+module MyPlugin
+  def self.setup!(klass)
+    # Optional: called after inclusion
+    klass.string :plugin_id
+  end
+
+  def plugin_feature
+    "Enabled!"
+  end
+end
+
+Castkit.configure do |config|
+  config.register_plugin(:my_plugin, MyPlugin)
+end
+
+class MyDto < Castkit::DataObject
+  enable_plugins :my_plugin
+end
+```
+
+This includes the `MyPlugin` module into `MyDto` and calls `MyPlugin.setup!(MyDto)` if defined.
+
+---
+
+### 🧩 Registering Plugins
+
+Plugins must be registered before use:
+
+```ruby
+Castkit.configure do |config|
+  config.register_plugin(:oj, Castkit::Plugins::Oj)
+end
+```
+
+You can then activate them:
+
+```ruby
+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
+
+| Method                        | Description |
+|------------------------------|-------------|
+| `Castkit::Plugins.register(:name, mod)` | Registers a plugin under a custom name. |
+| `Castkit::Plugins.activate(klass, *names)` | Includes one or more plugins into a class. |
+| `Castkit::Plugins.lookup!(:name)`        | Looks up the plugin by name or constant. |
+
+---
+
+### 📁 Plugin Structure
+
+Castkit looks for plugins under the `Castkit::Plugins` namespace by default:
+
+```ruby
+module Castkit
+  module Plugins
+    module Oj
+      def self.setup!(klass)
+        klass.include SerializationSupport
+      end
+    end
+  end
+end
+```
+
+To activate this:
+
+```ruby
+Castkit::Plugins.activate(MyDto, :oj)
+```
+
+You can also manually register plugins not under this namespace.
+
+---
+
+### ✅ Example Use Case
+
+```ruby
+module Castkit
+  module Plugins
+    module Timestamps
+      def self.setup!(klass)
+        klass.datetime :created_at
+        klass.datetime :updated_at
+      end
+    end
+  end
+end
+
+Castkit::Plugins.activate(UserDto, :timestamps)
+```
+
+This approach allows reusable, modular feature sets across DTOs with clean setup behavior.
+
+---
+
+## Castkit CLI
+
+Castkit includes a command-line interface to help scaffold and inspect DTO components with ease.
+
+The CLI is structured around two primary commands:
+
+- `castkit generate` — scaffolds boilerplate for Castkit components.
+- `castkit list` — introspects and displays registered or defined components.
+
+---
+
+## ✨ Generate Commands
+
+The `castkit generate` command provides subcommands for creating files for all core Castkit component types.
+
+### 🧱 DataObject
+
+```bash
+castkit generate dataobject User name:string age:integer
+```
+
+Creates:
+
+- `lib/castkit/data_objects/user.rb`
+- `spec/castkit/data_objects/user_spec.rb`
+
+### 📄 Contract
+
+```bash
+castkit generate contract UserInput id:string email:string
+```
+
+Creates:
+
+- `lib/castkit/contracts/user_input.rb`
+- `spec/castkit/contracts/user_input_spec.rb`
+
+### 🔌 Plugin
+
+```bash
+castkit generate plugin Oj
+```
+
+Creates:
+
+- `lib/castkit/plugins/oj.rb`
+- `spec/castkit/plugins/oj_spec.rb`
+
+### 🧪 Validator
+
+```bash
+castkit generate validator Money
+```
+
+Creates:
+
+- `lib/castkit/validators/money.rb`
+- `spec/castkit/validators/money_spec.rb`
+
+### 🧬 Type
+
+```bash
+castkit generate type money
+```
+
+Creates:
+
+- `lib/castkit/types/money.rb`
+- `spec/castkit/types/money_spec.rb`
+
+### 📦 Serializer
+
+```bash
+castkit generate serializer Json
+```
+
+Creates:
+
+- `lib/castkit/serializers/json.rb`
+- `spec/castkit/serializers/json_spec.rb`
+
+You can disable test generation with `--no-spec`.
+
+---
+
+## 📋 List Commands
+
+The `castkit list` command provides an interface to view internal Castkit definitions or project-registered components.
+
+### 🧾 List Types
+
+```bash
+castkit list types
+```
+
+Displays a grouped list of:
+
+- Native types (defined by Castkit)
+- Custom types (registered via `Castkit.configure`)
+
+Example:
+
+```bash
+Native Types:
+  Castkit::Types::String         - :string, :str, :uuid
+
+Custom Types:
+  MyApp::Types::Money            - :money
+```
+
+### 🔍 List Validators
+
+```bash
+castkit list validators
+```
+
+Displays all validator classes defined in `lib/castkit/validators` or custom-defined under `Castkit::Validators`.
+
+Castkit validators are tagged `[Castkit]`, and others as `[Custom]`.
+
+### 📑 List Contracts
+
+```bash
+castkit list contracts
+```
+
+Lists all contracts in the `Castkit::Contracts` namespace and related files.
+
+### 📦 List DataObjects
+
+```bash
+castkit list dataobjects
+```
+
+Lists all DTOs in the `Castkit::DataObjects` namespace.
+
+### 🧪 List Serializers
+
+```bash
+castkit list serializers
+```
+
+Lists all serializer classes and their source origin.
+
+---
+
+## 🧰 Example Usage
+
+```bash
+castkit generate dataobject Product name:string price:float
+castkit generate contract ProductInput name:string
+
+castkit list types
+castkit list validators
+```
+
+The CLI is designed to provide a familiar Rails-like generator experience, tailored for Castkit’s data-first architecture.
+
+---
+
 ## Testing
 
 You can test DTOs and Contracts by treating them like plain Ruby objects:

data/castkit.gemspec

@@ -33,9 +33,12 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
+  spec.add_dependency "thor"
 
   # 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)