castkit 0.2.0 → 0.3.1

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.
 #
@@ -20,12 +19,15 @@ require_relative "inflector"
 # @see Castkit::Contract
 # @see Castkit::DataObject
 module Castkit
-  # Namespace used for registering DataObjects generated from contracts.
+  # Namespace used for registering generated DataObjects.
   module DataObjects; end
 
-  # Namespace used for registering contracts generated from DataObjects.
+  # Namespace used for registering generated contracts.
   module Contracts; end
 
+  # Namespace used for registering generated plugins.
+  module Plugins; end
+
   class << self
     # Yields the global configuration object for customization.
     #
@@ -60,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.
@@ -102,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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../../generators/attribute"
+require_relative "../../generators/contract"
+require_relative "../../generators/data_object"
+require_relative "../../generators/plugin"
+require_relative "../../generators/serializer"
+require_relative "../../generators/type"
+require_relative "../../generators/validator"
+
+module Castkit
+  module CLI
+    # Thor CLI class for generating Castkit components.
+    #
+    # Provides `castkit generate` commands for each major Castkit component, including types,
+    # data objects, contracts, validators, serializers, and plugins.
+    #
+    # All generators support the `--no-spec` flag to skip spec file creation.
+    class Generate < Thor
+      desc "contract NAME", "Generates a new Castkit contract"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new contract class.
+      #
+      # @param name [String] the class name for the contract
+      # @param fields [Array<String>] optional attribute definitions
+      # @return [void]
+      def contract(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        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.
+      #
+      # @param name [String] the class name for the data object
+      # @param fields [Array<String>] optional attribute definitions
+      # @return [void]
+      def dataobject(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::DataObject.start(args)
+      end
+
+      desc "plugin NAME", "Generates a new Castkit plugin"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new plugin module.
+      #
+      # @param name [String] the module name for the plugin
+      # @param fields [Array<String>] optional stub fields
+      # @return [void]
+      def plugin(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Plugin.start(args)
+      end
+
+      desc "serializer NAME", "Generates a new Castkit serializer"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new custom serializer class.
+      #
+      # @param name [String] the class name for the serializer
+      # @param fields [Array<String>] optional stub fields
+      # @return [void]
+      def serializer(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Serializer.start(args)
+      end
+
+      desc "type NAME", "Generates a new Castkit type"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new custom type.
+      #
+      # @param name [String] the class name for the type
+      # @return [void]
+      def type(name)
+        args = [Castkit::Inflector.pascalize(name)]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Type.start(args)
+      end
+
+      desc "validator NAME", "Generates a new Castkit validator"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new validator class.
+      #
+      # @param name [String] the class name for the validator
+      # @param fields [Array<String>] optional stub fields
+      # @return [void]
+      def validator(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Validator.start(args)
+      end
+    end
+  end
+end

data/lib/castkit/cli/list.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "thor"
+require "castkit"
+require_relative "../../generators/contract"
+require_relative "../../generators/data_object"
+require_relative "../../generators/plugin"
+require_relative "../../generators/serializer"
+require_relative "../../generators/type"
+require_relative "../../generators/validator"
+
+module Castkit
+  module CLI
+    # CLI commands for listing internal Castkit registry components.
+    #
+    # Supports listing:
+    # - Registered types (`castkit list types`)
+    # - Available validators (`castkit list validators`)
+    #
+    # @example Show all available types
+    #   $ castkit list types
+    #
+    # @example Show all defined validators
+    #   $ castkit list validators
+    class List < Thor
+      desc "types", "Lists registered Castkit types"
+      # Lists registered Castkit types, grouped into native and custom-defined.
+      #
+      # @return [void]
+      def types
+        all_keys = Castkit.configuration.types
+        default_keys = Castkit::Configuration::DEFAULT_TYPES.keys
+
+        native_types(all_keys, default_keys)
+        custom_types(all_keys, default_keys)
+      end
+
+      desc "contracts", "Lists all generated Castkit contracts"
+      # Lists all Castkit contract classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def contracts
+        list_files("contracts")
+      end
+
+      desc "dataobjects", "Lists all generated Castkit DataObjects"
+      # Lists all Castkit DataObjects classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def dataobjects
+        list_files("data_objects")
+      end
+
+      desc "serializers", "Lists all generated Castkit serializers"
+      # Lists all Castkit serializers classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def serializers
+        list_files("serializers")
+      end
+
+      desc "validators", "Lists all generated Castkit validators"
+      # Lists all Castkit validator classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def validators
+        list_files("validators")
+      end
+
+      private
+
+      # Prints all native types and their aliases.
+      #
+      # @param all_types [Hash<Symbol, Object>] all registered types
+      # @param default_keys [Array<Symbol>] predefined native type keys
+      # @return [void]
+      def native_types(all_types, default_keys)
+        alias_map = reverse_grouped(Castkit::Configuration::TYPE_ALIASES)
+        native = all_types.slice(*default_keys)
+
+        say "Native Types:", :green
+        native.each do |name, type|
+          aliases = alias_map[name] || []
+          list_type(type.class, [name, *aliases].map(&:to_sym))
+        end
+      end
+
+      # Prints all custom (non-native, non-alias) registered types.
+      #
+      # @param all_types [Hash<Symbol, Object>]
+      # @param default_keys [Array<Symbol>]
+      # @return [void]
+      def custom_types(all_types, default_keys)
+        alias_keys = Castkit::Configuration::TYPE_ALIASES.keys.map(&:to_sym)
+        custom = all_types.except(*default_keys).reject { |k, _| alias_keys.include?(k) }
+
+        say "\nCustom Types:", :green
+        return no_custom_types if custom.empty?
+
+        grouped_custom_types(custom)
+      end
+
+      # Outputs a fallback message if no custom types exist.
+      #
+      # @return [void]
+      def no_custom_types
+        say "  No registered types, register with " \
+            "#{set_color("Castkit.configure { |c| c.register_type(:type, Type) }", :yellow)}"
+      end
+
+      # Groups and prints custom types by their class.
+      #
+      # @param types [Hash<Symbol, Object>]
+      # @return [void]
+      def grouped_custom_types(types)
+        types.group_by { |_, inst| inst.class }.each do |klass, group|
+          list_type(klass, group.map(&:first).map(&:to_sym))
+        end
+      end
+
+      # Reverses a hash of alias => type into type => [aliases].
+      #
+      # @param hash [Hash]
+      # @return [Hash{Symbol => Array<Symbol>}]
+      def reverse_grouped(hash)
+        hash.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(k, v), acc|
+          acc[v] << k
+        end
+      end
+
+      # Prints a type or class with all its symbol aliases.
+      #
+      # @param klass [Class]
+      # @param keys [Array<Symbol>]
+      # @return [void]
+      def list_type(klass, keys)
+        types = keys.uniq.sort.map { |k| set_color(":#{k}", :yellow) }.join(", ")
+        say "  #{(klass.name || "<AnonymousType>").ljust(34)} - #{types}"
+      end
+
+      # Lists class references for a component (e.g. validators), distinguishing by source (file or custom).
+      #
+      # @param component [String] base namespace (e.g. "validators")
+      # @return [void]
+      def list_files(component)
+        path = "lib/castkit/#{component}"
+        all_classes, file_classes = component_classes(component, path)
+        return say "No registered #{Castkit::Inflector.pascalize(component)} found." if all_classes.empty?
+
+        max_width = all_classes.map(&:length).max + 5
+        say "Castkit #{Castkit::Inflector.pascalize(component)}", :green
+
+        all_classes.each do |klass|
+          tag = file_classes.include?(klass) ? set_color("[Castkit]", :yellow) : set_color("[Custom]", :green)
+          say "  #{klass.ljust(max_width)} #{tag}"
+        end
+      end
+
+      # Gathers all registered and defined constants for a component.
+      #
+      # @param component [String]
+      # @param path [String]
+      # @return [Array<[Array<String>, Set<String>]>]
+      def component_classes(component, path)
+        namespace = Castkit.const_get(Castkit::Inflector.pascalize(component))
+        file_classes = file_classes(namespace, path)
+        defined_classes = defined_classes(namespace)
+
+        all_classes = (file_classes + defined_classes).to_a.sort
+        [all_classes, file_classes]
+      end
+
+      # Converts file names into class names for a given component.
+      #
+      # @param namespace [Module]
+      # @param path [String]
+      # @return [Set<String>]
+      def file_classes(namespace, path)
+        classes = Dir.glob("#{path}/*.rb")
+                     .map { |f| File.basename(f, ".rb") }
+                     .reject { |f| f.to_s == "base" }
+                     .map { |base| "#{namespace}::#{Castkit::Inflector.pascalize(base)}" }
+
+        classes.to_set
+      end
+
+      # Lists actual constants under a namespace, filtering out missing definitions.
+      #
+      # @param namespace [Module]
+      # @return [Set<String>]
+      def defined_classes(namespace)
+        namespace.constants
+                 .reject { |const| const.to_s == "Base" }
+                 .map { |const| "#{namespace}::#{const}" }
+                 .select { |klass| Object.const_defined?(klass) }
+                 .to_set
+      end
+    end
+  end
+end

data/lib/castkit/cli/main.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "generate"
+require_relative "list"
+
+module Castkit
+  module CLI
+    # Main CLI entry point for Castkit.
+    #
+    # Provides top-level commands for printing the gem version and generating Castkit components.
+    #
+    # @example Print the version
+    #   $ castkit version
+    #
+    # @example Generate a DataObject
+    #   $ castkit generate dataobject User name:string age:integer
+    class Main < Thor
+      desc "version", "Prints the version"
+      # Outputs the current Castkit version.
+      #
+      # @return [void]
+      def version
+        puts Castkit::VERSION
+      end
+
+      desc "generate TYPE NAME", "Generate a Castkit component"
+      # Dispatches to the `castkit generate` subcommands.
+      #
+      # Supports generating components like `type`, `dataobject`, `contract`, etc.
+      #
+      # @return [void]
+      subcommand "generate", Castkit::CLI::Generate
+
+      desc "list COMPONENT", "List registered Castkit components"
+      # Dispatches to the `castkit list` subcommands.
+      #
+      # Supports listing components like `type`, `dataobject`, `contract`, etc.
+      #
+      # @return [void]
+      subcommand "list", Castkit::CLI::List
+    end
+  end
+end