castkit 0.2.0 → 0.3.0

data/lib/generators/base.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+
+module Castkit
+  module Generators
+    # Abstract base class for all Castkit generators.
+    #
+    # Provides standard behavior for generating a component and optional spec file from
+    # ERB templates. Subclasses must define a `component` (e.g., `:type`, `:contract`)
+    # and may override `config` or `default_values`.
+    #
+    # Template variables are injected using the `config` hash, which includes:
+    # - `:name`        – underscored version of the component name
+    # - `:class_name`  – PascalCase version of the component name
+    #
+    # @abstract
+    class Base < Thor::Group
+      include Thor::Actions
+
+      class << self
+        # Sets or retrieves the component type (e.g., :type, :data_object).
+        #
+        # @param value [Symbol, nil]
+        # @return [Symbol]
+        def component(value = nil)
+          value.nil? ? @component : (@component = value)
+        end
+
+        # @return [String] the root path to look for templates
+        def source_root
+          File.expand_path("templates", __dir__)
+        end
+      end
+
+      argument :name, desc: "The name of the component to generate"
+      class_option :spec, type: :boolean, default: true, desc: "Also generate a spec file"
+
+      # Creates the main component file using a template.
+      #
+      # Template: `component.rb.tt`
+      # Target: `lib/castkit/#{component}s/#{name}.rb`
+      #
+      # @return [void]
+      def create_component
+        template(
+          "#{self.class.component}.rb.tt",
+          "lib/castkit/#{self.class.component}s/#{config[:name]}.rb", **config
+        )
+      end
+
+      # Creates the associated spec file, if enabled.
+      #
+      # Template: `component_spec.rb.tt`
+      # Target: `spec/castkit/#{component}s/#{name}_spec.rb`
+      #
+      # @return [void]
+      def create_spec
+        return unless options[:spec]
+
+        template(
+          "#{self.class.component}_spec.rb.tt",
+          "spec/castkit/#{self.class.component}s/#{config[:name]}_spec.rb", **config
+        )
+      end
+
+      private
+
+      # Default values for test inputs based on type.
+      #
+      # These are used in spec templates to provide sample data.
+      #
+      # @return [Hash{Symbol => Object}]
+      def default_values
+        {
+          string: '"example"',
+          integer: 42,
+          float: 3.14,
+          boolean: true,
+          array: [],
+          hash: {}
+        }
+      end
+
+      # Returns the default config hash passed into templates.
+      #
+      # @return [Hash{Symbol => Object}]
+      def config
+        {
+          name: Castkit::Inflector.underscore(name),
+          class_name: Castkit::Inflector.pascalize(name)
+        }
+      end
+    end
+  end
+end

data/lib/generators/contract.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+require_relative "base"
+
+module Castkit
+  module Generators
+    # Generator for creating Castkit contracts.
+    #
+    # Generates a contract class and optionally a corresponding spec file.
+    # Accepts an optional list of attribute definitions in the form `name:type`.
+    #
+    # Example:
+    #   $ castkit generate contract User name:string age:integer
+    #
+    # This will generate:
+    # - lib/castkit/contracts/user.rb
+    # - spec/castkit/contracts/user_spec.rb
+    #
+    # @see Castkit::Generators::Base
+    class Contract < Castkit::Generators::Base
+      component :contract
+
+      argument :fields, type: :array, default: [], desc: "Attribute definitions (e.g., name:string age:integer)"
+
+      private
+
+      # @return [Hash] configuration passed into templates
+      def config
+        super.merge(
+          attributes: parsed_fields,
+          default_values: default_values,
+          invalid_types: invalid_types
+        )
+      end
+
+      # Parses `name:type` fields into attribute definitions.
+      #
+      # @return [Array<Hash{Symbol => Object}>] list of parsed attribute hashes
+      def parsed_fields
+        fields.map do |field|
+          name, type = field.split(":")
+          { name: name, type: (type || "string").to_sym }
+        end
+      end
+
+      # Default "invalid" test values for each supported type.
+      #
+      # Used in generated specs to simulate bad input.
+      #
+      # @return [Hash{Symbol => Object}]
+      def invalid_types
+        {
+          string: true,
+          integer: '"invalid"',
+          float: '"bad"',
+          boolean: '"not_a_bool"',
+          date: 123,
+          datetime: [],
+          array: {},
+          hash: [],
+          uuid: 999
+        }
+      end
+    end
+  end
+end

data/lib/generators/data_object.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+require_relative "base"
+
+module Castkit
+  module Generators
+    # Generator for creating Castkit DataObject classes.
+    #
+    # Generates a DataObject class and an optional spec file with attribute definitions.
+    # Accepts a list of field definitions in the form `name:type`.
+    #
+    # Example:
+    #   $ castkit generate dataobject User name:string active:boolean
+    #
+    # This will generate:
+    # - lib/castkit/data_objects/user.rb
+    # - spec/castkit/data_objects/user_spec.rb
+    #
+    # @see Castkit::Generators::Base
+    class DataObject < Castkit::Generators::Base
+      component :data_object
+
+      argument :fields, type: :array, default: [], desc: "Attribute definitions (e.g., name:string active:boolean)"
+
+      private
+
+      # @return [Hash] configuration passed into templates
+      def config
+        super.merge(
+          attributes: parsed_fields,
+          default_values: default_values
+        )
+      end
+
+      # Parses `name:type` fields into attribute definitions.
+      #
+      # @return [Array<Hash{Symbol => Object}>] list of parsed attribute hashes
+      def parsed_fields
+        fields.map do |field|
+          name, type = field.split(":")
+          { name: name, type: (type || "string").to_sym }
+        end
+      end
+    end
+  end
+end

data/lib/generators/plugin.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+require_relative "base"
+
+module Castkit
+  module Generators
+    # Generator for creating Castkit plugin modules.
+    #
+    # This generator will produce a module under `Castkit::Plugins::<ClassName>` and an optional spec file.
+    #
+    # Example:
+    #   $ castkit generate plugin Oj
+    #
+    # This will generate:
+    # - lib/castkit/plugins/oj.rb
+    # - spec/castkit/plugins/oj_spec.rb
+    #
+    # @see Castkit::Generators::Base
+    class Plugin < Castkit::Generators::Base
+      component :plugin
+    end
+  end
+end

data/lib/generators/serializer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+require_relative "base"
+
+module Castkit
+  module Generators
+    # Generator for creating a custom Castkit serializer.
+    #
+    # Serializers inherit from `Castkit::Serializers::Base` and define a custom `#call` method
+    # for rendering a `Castkit::DataObject` into a hash representation.
+    #
+    # Example usage:
+    #   $ castkit generate serializer Custom
+    #
+    # Generates:
+    # - lib/castkit/serializers/custom.rb
+    # - spec/castkit/serializers/custom_spec.rb
+    #
+    # These files scaffold a `Castkit::Serializers::Custom` serializer with the correct base class.
+    #
+    # @see Castkit::Generators::Base
+    class Serializer < Castkit::Generators::Base
+      component :serializer
+    end
+  end
+end

data/lib/generators/templates/contract.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Contracts
+    # Contract definition for <%= config[:class_name] %>.
+    #
+    # This contract can be used to validate structured input like:
+    #
+    # @example Validating input (soft)
+    #   result = Castkit::Contracts::<%= config[:class_name] %>.validate(params)
+    #   puts result.inspect # Castkit::Contract::Result instance
+    #
+    # @example Validating input (hard)
+    #   being
+    #     result = Castkit::Contracts::<%= config[:class_name] %>.validate!(params)
+    #   rescue Castkit::ContractError => e
+    #     puts e.errors
+    #   end
+    class <%= config[:class_name] %> < Castkit::Contract::Base<% if config[:attributes].empty? %>
+      # string :id<% else %><% config[:attributes].each do |attr| %>
+      <%= attr[:type] %> :<%= attr[:name] %><% end %><% end %>
+    end
+  end
+end

data/lib/generators/templates/contract_spec.rb.tt

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "castkit/contracts/<%= config[:name] %>"
+
+RSpec.describe Castkit::Contracts::<%= config[:class_name] %> do
+  subject(:contract) { described_class }
+<% if config[:attributes].empty? %>
+  let(:attributes) { {} }
+  <% else %>
+  let(:attributes) do
+    {<% config[:attributes].each do |attr| %>
+      <%= attr[:name] %>: <%= config[:default_values].fetch(attr[:type], "nil") %>,<% end %>
+    }
+  end
+<% end %>
+  it "is a Castkit::Contract" do
+    expect(contract).to be < Castkit::Contract::Base
+  end
+<% if config[:attributes].any? %>
+  describe ".validate" do
+    it "returns success with valid input" do
+      result = contract.validate(attributes)
+      expect(result).to be_success
+    end
+
+    it "returns failure with missing required fields" do
+      field = contract.attributes.keys.first
+      contract.attributes[field].options[:required] = true
+
+      result = contract.validate(attributes.reject { |k| k == field })
+      expect(result).to be_failure
+      expect(result.errors).to include({ field => "#{field} is required" })
+    end
+
+    it "returns failure with invalid value types" do
+      field = :<%= config[:attributes].first[:name] %>
+      field_type = :<%= config[:attributes].first[:type] %>
+
+      result = contract.validate(attributes.merge({ field => <%= config[:invalid_types].fetch(config[:attributes].first[:type], nil) %> }))
+      expect(result).to be_failure
+      expect(result.errors).to include({ field => "#{field} must be a #{field_type}" })
+    end
+  end
+
+  describe ".validate!" do
+    it "returns success with valid input" do
+      result = contract.validate!(attributes)
+      expect(result).to be_success
+    end
+
+    it "raises an error with missing required fields" do
+      field = contract.attributes.keys.first
+      contract.attributes[field].options[:required] = true
+
+      expect do
+        contract.validate!(attributes.reject { |k| k == field })
+      rescue Castkit::ContractError => e
+        expect(e.errors).to include({ field => "#{field} is required" })
+        raise e
+      end.to raise_error(Castkit::ContractError)
+    end
+
+    it "raises an error with invalid value types" do
+      field = :<%= config[:attributes].first[:name] %>
+      field_type = :<%= config[:attributes].first[:type] %>
+
+      expect do
+        contract.validate!(attributes.merge({ field => <%= config[:invalid_types].fetch(config[:attributes].first[:type], nil) %> }))
+      rescue Castkit::ContractError => e
+        expect(e.errors).to include({ field => "#{field} must be a #{field_type}" })
+        raise e
+      end.to raise_error(Castkit::ContractError)
+    end
+  end<% end %>
+end

data/lib/generators/templates/data_object.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Castkit
+  module DataObjects
+    # Data transfer object for <%= config[:class_name] %>.
+    #
+    # @example Instantiation
+    #   <%= config[:class_name] %>.new(id: "123", name: "example")
+    class <%= config[:class_name] %> < Castkit::DataObject
+<% config[:attributes].each do |attr| -%>
+      <%= attr[:type] %> :<%= attr[:name] %>
+<% end -%>
+    end
+  end
+end

data/lib/generators/templates/data_object_spec.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "castkit/data_objects/<%= config[:name] %>"
+
+RSpec.describe Castkit::DataObjects::<%= config[:class_name] %> do
+  subject(:instance) { described_class.new(attributes) }
+<% if config[:attributes].empty? %>
+  let(:attributes) { {} }
+  <% else %>
+  let(:attributes) do
+    {<% config[:attributes].each do |attr| %>
+      <%= attr[:name] %>: <%= config[:default_values].fetch(attr[:type], nil) %>,<% end %>
+    }
+  end
+<% end %>
+  it "is a Castkit::DataObject" do
+    expect(described_class).to be < Castkit::DataObject
+  end
+<% config[:attributes].each do |attr| %>
+  describe "#<%= attr[:name] %>" do
+    it "is defined on the DTO" do
+      expect(described_class.attributes.keys).to include(:<%= attr[:name] %>)
+    end
+
+    it "returns the attribute options" do
+      # test for options set on the attribute
+      #   `<%= attr[:type] %> :<%= attr[:name] %>, required: true`
+      # expect(described_class.attributes[:<%= attr[:name] %>).to include(required: true)
+    end
+
+    it "returns the expected value" do
+      expect(instance.<%= attr[:name] %>).to eq(attributes[:<%= attr[:name] %>])
+    end
+  end
+<% end %>end

data/lib/generators/templates/plugin.rb.tt

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Plugins
+    # <%= config[:class_name] %> plugin for Castkit::DataObject.
+    #
+    # This plugin can be enabled via:
+    #
+    #   class MyDto < Castkit::DataObject
+    #     enable_plugins :<%= config[:name] %>
+    #   end
+    #
+    # Or globally:
+    #
+    #   Castkit.configure do |config|
+    #     config.register_plugin(:<%= config[:name] %>, Castkit::Plugins::<%= config[:class_name] %>)
+    #     config.default_plugins << :<%= config[:name] %>
+    #   end
+    module <%= config[:class_name] %>
+      # Optional setup hook called during plugin activation
+      #
+      # @param klass [Class<Castkit::DataObject>]
+      # @return [void]
+      def self.setup!(klass)
+        # Custom setup logic here
+      end
+
+      # Optionally define an Extension module to be included into the DataObject class
+      #
+      # module Extension
+      #   def custom_behavior
+      #     # ...
+      #   end
+      # end
+    end
+  end
+end

data/lib/generators/templates/plugin_spec.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "castkit/plugins/<%= config[:name] %>"
+
+RSpec.describe Castkit::Plugins::<%= config[:class_name] %> do
+  let(:plugin) { described_class }
+
+  describe ".setup!" do
+    let(:klass) do
+      Class.new(Castkit::DataObject)
+    end
+
+    it "can be setup on a dataobject class" do
+      expect { plugin.setup!(klass) }.not_to raise_error
+    end
+  end
+end

data/lib/generators/templates/serializer.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "castkit/serializers/base"
+
+module Castkit
+  module Serializers
+    # Serializer for <%= config[:class_name] %> DTOs.
+    #
+    # This can be applied to a DataObject with:
+    #
+    # @example
+    #   class MyDto < Castkit::DataObject
+    #     serializer Castkit::Serializers::<%= config[:class_name] %>
+    #   end
+    class <%= config[:class_name] %> < Castkit::Serializers::Base
+      # Returns a serialized hash version of the object.
+      #
+      # @return [Hash]
+      def call
+        object.to_h
+      end
+    end
+  end
+end

data/lib/generators/templates/serializer_spec.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "castkit/serializers/<%= config[:name] %>"
+
+RSpec.describe Castkit::Serializers::<%= config[:class_name] %> do
+  let(:object) { double("Castkit::DataObject", to_h: { foo: "bar" }) }
+
+  subject(:serializer) { described_class.new(object) }
+
+  it "serializes using #call" do
+    expect(serializer.call).to eq({ foo: "bar" })
+  end
+end

data/lib/generators/templates/type.rb.tt

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Types
+    # Type definition for <%= config[:class_name] %> (:<%= config[:name] %>) attributes.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #
+    # @example Registering <%= config[:class_name] %> as a valid type
+    #   Castkit.configure do |config|
+    #     config.register_type(:<%= config[:name] %>, Castkit::Types::<%= config[:class_name] %>, aliases: %i[custom_alias])
+    #   end
+    #
+    # @example Defining an attribute
+    #   class Data < Castkit::DataObject
+    #     <%= config[:name] %> :attribute_name
+    #     attribute :attribute_name, :<%= config[:name] %>
+    #   end
+    #
+    # @example Defining an attribute using an alias
+    #   class Data < Castkit::DataObject
+    #     custom_alias: :attribute_name
+    #     attribute :attribute_name, :custom_alias
+    #   end
+    class <%= config[:class_name] %> < Castkit::Types::Base
+      # Deserializes the input value to a <%= config[:class_name] %> instance.
+      #
+      # @param value [Object, nil] the value to deserialize
+      # @return [<%= config[:class_name] %>] the deserialized value
+      def deserialize(value)
+        # deserialization logic
+        # value.to_s
+      end
+
+      # Serializes the <%= config[:class_name] %> value.
+      #
+      # @param value [<%= config[:class_name] %>] the value to serialize
+      # @return [Object] the serialized value
+      def serialize(value)
+        # serialization logic
+        # value.to_s
+      end
+
+      # Validates the input value with a custom Castkit::Validators::<%= config[:class_name] %> validator.
+      #
+      # @param value [Object, nil] the value to validate
+      # @param options [Hash] the validation options
+      # @param context [Hash] the validation context
+      def validate!(value, options = {}, context = {})
+        # validation logic
+        # Castkit::Validators::<%= config[:class_name] %>.call(value, options: options, context: context)
+      end
+    end
+  end
+end

data/lib/generators/templates/type_spec.rb.tt

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "castkit/types/<%= config[:name] %>"
+
+# Spec for Castkit::Types::<%= config[:class_name] %>
+RSpec.describe Castkit::Types::<%= config[:class_name] %> do
+  subject(:type) { described_class.new }
+
+  it "is a subclass of Castkit::Types::Base" do
+    expect(described_class).to be < Castkit::Types::Base
+  end
+
+  describe "#deserialize" do
+    let(:input) { "input" }
+
+    it "converts a valid input" do
+      # expect(type.deserialize(input)).to eq(expected_value)
+    end
+  end
+
+  describe "#serialize" do
+    let(:value) { "value" }
+
+    it "converts the value to a serializable format" do
+      # expect(type.serialize(value)).to eq(expected_output)
+    end
+  end
+
+  describe "#validate!" do
+    let(:valid_value) { "valid" }
+    let(:invalid_value) { nil }
+
+    it "does not raise for valid input" do
+      # expect { type.validate!(valid_value) }.not_to raise_error
+    end
+
+    it "raises for invalid input" do
+      # expect { type.validate!(invalid_value) }.to raise_error(Castkit::AttributeError)
+    end
+  end
+end

data/lib/generators/templates/validator.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Castkit
+  module Validators
+    # Validator for :<%= config[:name] %> attributes.
+    #
+    # Subclass of Castkit::Validators::Base. Used automatically by attributes or types that declare it.
+    #
+    # @example Manual use:
+    #   Castkit::Validators::<%= config[:class_name] %>.call(value, context: :my_field)
+    class <%= config[:class_name] %> < Castkit::Validators::Base
+      # Validates the value and raises a Castkit::AttributeError if invalid.
+      #
+      # @param value [Object] The value to validate
+      # @param options [Hash] Optional validation options
+      # @param context [Symbol] The attribute or context key for error messages
+      def call(value, options: {}, context: nil)
+        raise Castkit::AttributeError, "#{context} must be present" if value.nil?
+
+        value
+      end
+    end
+  end
+end

data/lib/generators/templates/validator_spec.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "castkit/validators/<%= config[:name] %>"
+
+RSpec.describe Castkit::Validators::<%= config[:class_name] %> do
+  subject(:validator) { described_class.new }
+
+  let(:context) { :<%= config[:name] %> }
+
+  describe "#call" do
+    it "returns the value if valid" do
+      valid = "example"
+      expect(validator.call(valid, context: context)).to eq(valid)
+    end
+
+    it "raises for invalid values" do
+      expect {
+        validator.call(nil, context: context)
+      }.to raise_error(Castkit::AttributeError, /#{context} must be present/)
+    end
+  end
+end