castkit 0.1.2 → 0.3.0

data/castkit.gemspec

@@ -33,6 +33,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
+  spec.add_dependency "thor"
 
   # Development dependencies
   spec.add_development_dependency "rspec"

data/lib/castkit/attribute.rb

@@ -1,23 +1,18 @@
 # frozen_string_literal: true
 
 require_relative "error"
-require_relative "data_object"
-require_relative "attribute_extensions/options"
-require_relative "attribute_extensions/casting"
-require_relative "attribute_extensions/access"
-require_relative "attribute_extensions/validation"
-require_relative "attribute_extensions/serialization"
+require_relative "ext/attribute/options"
+require_relative "ext/attribute/access"
+require_relative "ext/attribute/validation"
 
 module Castkit
   # Represents a typed attribute on a Castkit::DataObject.
   #
   # Provides casting, validation, access control, and serialization behavior.
   class Attribute
-    include Castkit::AttributeExtensions::Options
-    include Castkit::AttributeExtensions::Casting
-    include Castkit::AttributeExtensions::Access
-    include Castkit::AttributeExtensions::Validation
-    include Castkit::AttributeExtensions::Serialization
+    include Castkit::Ext::Attribute::Options
+    include Castkit::Ext::Attribute::Access
+    include Castkit::Ext::Attribute::Validation
 
     # @return [Symbol] the attribute name
     attr_reader :field
@@ -106,19 +101,6 @@ module Castkit
       end
     end
 
-    # Validates the final value against a validator if required.
-    #
-    # @param value [Object]
-    # @param context [Symbol, String]
-    # @return [void]
-    def validate_value!(value, context:)
-      return if value.nil? && optional?
-      return if type.is_a?(Array) || dataobject?
-
-      validator = options[:validator] || Castkit.configuration.validator_for(type)
-      validator&.call(value, options: options, context: context)
-    end
-
     # Raises a Castkit::AttributeError with optional context.
     #
     # @param message [String]

data/lib/castkit/castkit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "configuration"
+require_relative "inflector"
 
 # Castkit is a lightweight, type-safe data object system for Ruby.
 #
@@ -15,42 +16,92 @@ require_relative "configuration"
 #
 #   user = UserDto.new(name: "Alice", age: 30)
 #   user.to_h #=> { name: "Alice", age: 30 }
+#
+# @see Castkit::Contract
+# @see Castkit::DataObject
 module Castkit
+  # Namespace used for registering generated DataObjects.
+  module DataObjects; end
+
+  # 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.
     #
-    # @example
+    # @example Disabling array enforcement
     #   Castkit.configure do |config|
-    #     config.enforce_boolean_casting = false
+    #     config.enforce_typing = false
     #   end
     #
-    # @yieldparam config [Castkit::Configuration]
+    # @yieldparam config [Castkit::Configuration] the mutable config object
     # @return [void]
     def configure
       yield(configuration)
     end
 
-    # Retrieves the global Castkit configuration.
+    # Retrieves the global Castkit configuration instance.
     #
-    # @return [Castkit::Configuration] the configuration instance
+    # @return [Castkit::Configuration] the configuration object
     def configuration
       @configuration ||= Configuration.new
     end
 
-    # Generates a warning message if configuration.enable_warnings == true.
+    # Emits a warning to STDERR if `enable_warnings` is enabled in config.
     #
-    # @param message [String] The warning message
+    # @param message [String] the warning message
     # @return [void]
     def warning(message)
       warn message if configuration.enable_warnings
     end
 
-    # Determine if an object is a subclass of Castkit::DataObject.
+    # Checks whether a given object is a subclass of Castkit::DataObject.
     #
-    # @param obj [Object] The object to check
-    # @return [Boolean]
+    # @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)
     end
+
+    # Returns a type caster lambda for the given type.
+    #
+    # Type casting performs both validation and deserialization on the provided value.
+    #
+    # @param type [Symbol] the registered type (e.g. :string)
+    # @return [Proc] a lambda that accepts a value and options and returns a casted result
+    def type_caster(type)
+      type_definition = configuration.fetch_type(type)
+
+      lambda do |value, validator: nil, options: {}, context: nil|
+        type_definition.class.cast!(value, validator: validator, options: options, context: context)
+      end
+    end
+
+    # Returns a serializer lambda for the given type.
+    #
+    # @param type [Symbol] the registered type (e.g. :string)
+    # @return [Proc] a lambda that calls `.serialize` on the type
+    def type_serializer(type)
+      ->(value) { configuration.fetch_type(type).serialize(value) }
+    end
+
+    # Returns a deserializer lambda for the given type.
+    #
+    # @param type [Symbol] the registered type (e.g. :string)
+    # @return [Proc] a lambda that calls `.deserialize` on the type
+    def type_deserializer(type)
+      ->(value) { configuration.fetch_type(type).deserialize(value) }
+    end
+
+    # Returns a validator lambda for the given type.
+    #
+    # @param type [Symbol] the registered type (e.g. :string)
+    # @return [Proc] a lambda that calls `.validate!` on the type
+    def type_validator(type)
+      ->(value) { configuration.fetch_type(type).validate!(value) }
+    end
   end
 end

data/lib/castkit/cli/generate.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "thor"
+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 "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

data/lib/castkit/cli.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "cli/main"
+
+module Castkit
+  # Entrypoint for Castkit’s command-line interface.
+  #
+  # Delegates to the `Castkit::CLI::Main` Thor class, which defines all CLI commands.
+  #
+  # @example Executing from a binstub
+  #   Castkit::CLI.start(ARGV)
+  #
+  module CLI
+    # Starts the Castkit CLI.
+    #
+    # @param args [Array<String>] the command-line arguments
+    # @param kwargs [Hash] additional keyword arguments passed to Thor
+    # @return [void]
+    def self.start(*args, **kwargs)
+      Castkit::CLI::Main.start(*args, **kwargs)
+    end
+  end
+end