easy_talk 3.1.0 → 3.3.0

data/lib/easy_talk/property.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require 'json'
 require_relative 'builders/integer_builder'
@@ -9,6 +10,7 @@ require_relative 'builders/string_builder'
 require_relative 'builders/temporal_builder'
 require_relative 'builders/composition_builder'
 require_relative 'builders/typed_array_builder'
+require_relative 'builders/tuple_builder'
 require_relative 'builders/union_builder'
 
 # EasyTalk module provides a DSL for building JSON Schema definitions.
@@ -45,28 +47,6 @@ module EasyTalk
     # @return [Hash<Symbol, Object>] Additional constraints applied to the property
     attr_reader :constraints
 
-    # Mapping of Ruby type names to their corresponding schema builder classes.
-    # Each builder knows how to convert a specific Ruby type to JSON Schema.
-    #
-    # @api private
-    TYPE_TO_BUILDER = {
-      'String' => Builders::StringBuilder,
-      'Integer' => Builders::IntegerBuilder,
-      'Float' => Builders::NumberBuilder,
-      'BigDecimal' => Builders::NumberBuilder,
-      'T::Boolean' => Builders::BooleanBuilder,
-      'TrueClass' => Builders::BooleanBuilder,
-      'NilClass' => Builders::NullBuilder,
-      'Date' => Builders::TemporalBuilder::DateBuilder,
-      'DateTime' => Builders::TemporalBuilder::DatetimeBuilder,
-      'Time' => Builders::TemporalBuilder::TimeBuilder,
-      'anyOf' => Builders::CompositionBuilder::AnyOfBuilder,
-      'allOf' => Builders::CompositionBuilder::AllOfBuilder,
-      'oneOf' => Builders::CompositionBuilder::OneOfBuilder,
-      'T::Types::TypedArray' => Builders::TypedArrayBuilder,
-      'T::Types::Union' => Builders::UnionBuilder
-    }.freeze
-
     # Initializes a new instance of the Property class.
     #
     # @param name [Symbol] The name of the property
@@ -121,20 +101,24 @@ module EasyTalk
     # @example Nested schema with $ref
     #   property = Property.new(:shipping_address, Address, ref: true)
     #   property.build  # => {"$ref"=>"#/$defs/Address", ...constraints}
+    sig { returns(T::Hash[Symbol, T.untyped]) }
     def build
       if nilable_type?
         build_nilable_schema
-      elsif should_use_ref?
-        build_ref_schema
-      elsif builder
-        args = builder.collection_type? ? [name, type, constraints] : [name, constraints]
-        builder.new(*args).build
+      elsif RefHelper.should_use_ref?(type, constraints)
+        RefHelper.build_ref_schema(type, constraints)
+      elsif (resolved = find_builder_for_type)
+        builder_class, is_collection = resolved
+        args = is_collection ? [name, type, constraints] : [name, constraints]
+        builder_class.new(*args).build
       elsif type.respond_to?(:schema)
         # merge the top-level constraints from *this* property
         # e.g. :title, :description, :default, etc
         type.schema.merge!(constraints)
       else
-        'object'
+        raise UnknownTypeError,
+              "Unknown type '#{type.inspect}' for property '#{name}'. " \
+              'Register a custom builder with EasyTalk.register_type or use a supported type.'
       end
     end
 
@@ -147,32 +131,24 @@ module EasyTalk
     #
     # @see #build
     # @see https://ruby-doc.org/stdlib-2.7.2/libdoc/json/rdoc/JSON.html#as_json-method
+    sig { params(_args: T.untyped).returns(T.untyped) }
     def as_json(*_args)
       build.as_json
     end
 
-    # Returns the builder class associated with the property type.
-    #
-    # The builder is responsible for converting the Ruby type to a JSON Schema type.
-    #
-    # @return [Class, nil] The builder class for this property's type, or nil if no dedicated builder exists
-    # @see #find_builder_for_type
-    def builder
-      @builder ||= find_builder_for_type
-    end
-
     private
 
-    # Finds the appropriate builder for the current type.
+    # Finds the appropriate builder for the current type using the Builders::Registry.
     #
-    # First checks if there's a builder for the class name, then falls back
-    # to checking if there's a builder for the type's name (if it responds to :name).
+    # The registry is checked for a matching builder based on the type's class name
+    # or the type's own name.
     #
-    # @return [Class, nil] The builder class for this type, or nil if none matches
+    # @return [Array(Class, Boolean), nil] A tuple of [builder_class, is_collection] or nil if none matches
     # @api private
+    # @see Builders::Registry.resolve
+    sig { returns(T.nilable(T::Array[T.untyped])) }
     def find_builder_for_type
-      TYPE_TO_BUILDER[type.class.name.to_s] ||
-        (type.respond_to?(:name) ? TYPE_TO_BUILDER[type.name.to_s] : nil)
+      Builders::Registry.resolve(type)
     end
 
     # Determines if the type is nilable (can be nil).
@@ -182,6 +158,7 @@ module EasyTalk
     #
     # @return [Boolean] true if the type is nilable, false otherwise
     # @api private
+    sig { returns(T::Boolean) }
     def nilable_type?
       return false unless type.respond_to?(:types)
       return false unless type.types.all? { |t| t.respond_to?(:raw_type) }
@@ -196,6 +173,7 @@ module EasyTalk
     # @example
     #   # For a T.nilable(String) type:
     #   {"type"=>["string", "null"]}
+    sig { returns(T::Hash[Symbol, T.untyped]) }
     def build_nilable_schema
       # Extract the non-nil type from the Union
       actual_type = T::Utils::Nilable.get_underlying_type(type)
@@ -203,7 +181,7 @@ module EasyTalk
       return { type: 'null' } unless actual_type
 
       # Check if the underlying type is an EasyTalk model that should use $ref
-      if easytalk_model?(actual_type) && should_use_ref_for_type?(actual_type)
+      if RefHelper.should_use_ref_for_type?(actual_type, constraints)
         # Use anyOf with $ref and null type
         ref_constraints = constraints.except(:ref, :optional)
         schema = { anyOf: [{ '$ref': actual_type.ref_template }, { type: 'null' }] }
@@ -218,54 +196,5 @@ module EasyTalk
         type: [non_nil_schema[:type], 'null'].compact
       )
     end
-
-    # Determines if $ref should be used for the current type.
-    #
-    # @return [Boolean] true if $ref should be used, false otherwise
-    # @api private
-    def should_use_ref?
-      return false unless easytalk_model?(type)
-
-      should_use_ref_for_type?(type)
-    end
-
-    # Determines if $ref should be used for a given type based on constraints and config.
-    #
-    # @param check_type [Class] The type to check
-    # @return [Boolean] true if $ref should be used, false otherwise
-    # @api private
-    def should_use_ref_for_type?(check_type)
-      return false unless easytalk_model?(check_type)
-
-      # Per-property constraint takes precedence
-      return constraints[:ref] if constraints.key?(:ref)
-
-      # Fall back to global configuration
-      EasyTalk.configuration.use_refs
-    end
-
-    # Checks if a type is an EasyTalk model.
-    #
-    # @param check_type [Object] The type to check
-    # @return [Boolean] true if the type is an EasyTalk model
-    # @api private
-    def easytalk_model?(check_type)
-      check_type.is_a?(Class) &&
-        check_type.respond_to?(:schema) &&
-        check_type.respond_to?(:ref_template) &&
-        defined?(EasyTalk::Model) &&
-        check_type.include?(EasyTalk::Model)
-    end
-
-    # Builds a $ref schema for an EasyTalk model.
-    #
-    # @return [Hash] A schema with $ref pointing to the model's definition
-    # @api private
-    def build_ref_schema
-      # Remove ref and optional from constraints as they're not JSON Schema keywords
-      ref_constraints = constraints.except(:ref, :optional)
-      schema = { '$ref': type.ref_template }
-      ref_constraints.empty? ? schema : schema.merge(ref_constraints)
-    end
   end
 end

data/lib/easy_talk/ref_helper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative 'model_helper'
+
+module EasyTalk
+  module RefHelper
+    extend T::Sig
+
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
+    def self.should_use_ref?(type, constraints)
+      ModelHelper.easytalk_model?(type) && should_use_ref_for_type?(type, constraints)
+    end
+
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
+    def self.should_use_ref_for_type?(type, constraints)
+      return false unless ModelHelper.easytalk_model?(type)
+
+      # Per-property constraint takes precedence
+      if constraints.key?(:ref)
+        constraints[:ref]
+      else
+        EasyTalk.configuration.use_refs
+      end
+    end
+
+    sig { params(type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def self.build_ref_schema(type, constraints)
+      # Remove ref and optional from constraints as they're not JSON Schema keywords
+      { '$ref': type.ref_template }.merge(constraints.except(:ref, :optional))
+    end
+  end
+end

data/lib/easy_talk/schema.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'json'
+require 'active_support'
+require 'active_support/core_ext'
+require 'active_support/time'
+require 'active_support/concern'
+require 'active_support/json'
+require_relative 'builders/object_builder'
+require_relative 'schema_definition'
+
+module EasyTalk
+  # A lightweight module for schema generation without ActiveModel validations.
+  #
+  # Use this module when you need JSON Schema generation without the overhead
+  # of ActiveModel validations. This is ideal for:
+  # - API documentation and OpenAPI spec generation
+  # - Schema-first design where validation happens elsewhere
+  # - High-performance scenarios where validation overhead is unwanted
+  # - Generating schemas for external systems
+  #
+  # Unlike EasyTalk::Model, this module does NOT include ActiveModel::API or
+  # ActiveModel::Validations, so instances will not respond to `valid?` or have
+  # validation errors.
+  #
+  # @example Basic usage
+  #   class ApiContract
+  #     include EasyTalk::Schema
+  #
+  #     define_schema do
+  #       title 'API Contract'
+  #       property :name, String, min_length: 2
+  #       property :age, Integer, minimum: 0
+  #     end
+  #   end
+  #
+  #   ApiContract.json_schema  # => { "type" => "object", ... }
+  #   contract = ApiContract.new(name: 'Test', age: 25)
+  #   contract.name # => 'Test'
+  #   contract.valid? # => NoMethodError (no ActiveModel)
+  #
+  # @see EasyTalk::Model For a full-featured module with validations
+  #
+  module Schema
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    # Instance methods for schema-only models.
+    module InstanceMethods
+      # Initialize the schema object with attributes.
+      #
+      # @param attributes [Hash] The attributes to set
+      def initialize(attributes = {})
+        @additional_properties = {}
+        schema_def = self.class.schema_definition
+
+        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
+
+        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
+          value = attributes[prop_name] || attributes[prop_name.to_s]
+
+          # Handle default values
+          if value.nil? && !attributes.key?(prop_name) && !attributes.key?(prop_name.to_s)
+            default_value = prop_definition.dig(:constraints, :default)
+            value = default_value unless default_value.nil?
+          end
+
+          # Handle nested EasyTalk::Schema or EasyTalk::Model objects
+          defined_type = prop_definition[:type]
+          nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
+          defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
+
+          if defined_type.is_a?(Class) &&
+             (defined_type.include?(EasyTalk::Schema) || defined_type.include?(EasyTalk::Model)) &&
+             value.is_a?(Hash)
+            value = defined_type.new(value)
+          end
+
+          instance_variable_set("@#{prop_name}", value)
+        end
+      end
+
+      # Convert defined properties to a hash.
+      #
+      # @return [Hash] The properties as a hash
+      def to_hash
+        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
+        return {} if properties_to_include.empty?
+
+        properties_to_include.each_with_object({}) do |prop, hash|
+          hash[prop.to_s] = send(prop)
+        end
+      end
+
+      # Convert to JSON-compatible hash including additional properties.
+      #
+      # @param _options [Hash] JSON options (ignored)
+      # @return [Hash] The combined hash
+      def as_json(_options = {})
+        to_hash.merge(@additional_properties)
+      end
+
+      # Convert to hash including additional properties.
+      #
+      # @return [Hash] The combined hash
+      def to_h
+        to_hash.merge(@additional_properties)
+      end
+
+      # Allow comparison with hashes.
+      #
+      # @param other [Object] The object to compare with
+      # @return [Boolean] True if equal
+      def ==(other)
+        case other
+        when Hash
+          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.each_with_object({}) do |prop, hash|
+            hash[prop] = send(prop)
+          end
+          other_normalized = other.transform_keys(&:to_sym)
+          self_hash == other_normalized
+        else
+          super
+        end
+      end
+    end
+
+    # Class methods for schema-only models.
+    module ClassMethods
+      include SchemaMethods
+
+      # Returns the schema for the model.
+      #
+      # @return [Hash] The schema for the model.
+      def schema
+        @schema ||= if defined?(@schema_definition) && @schema_definition
+                      build_schema(@schema_definition)
+                    else
+                      {}
+                    end
+      end
+
+      # Define the schema for the model using the provided block.
+      # Unlike EasyTalk::Model, this does NOT apply any validations.
+      #
+      # @yield The block to define the schema.
+      # @raise [ArgumentError] If the class does not have a name.
+      def define_schema(&)
+        raise ArgumentError, 'The class must have a name' unless name.present?
+
+        @schema_definition = SchemaDefinition.new(name)
+        @schema_definition.klass = self
+        @schema_definition.instance_eval(&)
+
+        # Define accessors for all properties
+        defined_properties = (@schema_definition.schema[:properties] || {}).keys
+        attr_accessor(*defined_properties)
+
+        # NO validations are applied - this is schema-only
+
+        @schema_definition
+      end
+
+      # Returns the schema definition for the model.
+      #
+      # @return [SchemaDefinition] The schema definition.
+      def schema_definition
+        @schema_definition ||= {}
+      end
+
+      # Check if additional properties are allowed.
+      #
+      # @return [Boolean] True if additional properties are allowed.
+      def additional_properties_allowed?
+        @schema_definition&.schema&.fetch(:additional_properties, false)
+      end
+
+      # Returns the property names defined in the schema.
+      #
+      # @return [Array<Symbol>] Array of property names as symbols.
+      def properties
+        (@schema_definition&.schema&.dig(:properties) || {}).keys
+      end
+
+      private
+
+      # Builds the schema using the provided schema definition.
+      #
+      # @param schema_definition [SchemaDefinition] The schema definition.
+      # @return [Hash] The built schema.
+      def build_schema(schema_definition)
+        Builders::ObjectBuilder.new(schema_definition).build
+      end
+    end
+  end
+end

data/lib/easy_talk/schema_definition.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'keywords'
 require_relative 'types/composer'
@@ -19,26 +20,39 @@ module EasyTalk
     attr_reader :name, :schema
     attr_accessor :klass # Add accessor for the model class
 
+    sig { params(name: String, schema: T::Hash[Symbol, T.untyped]).void }
     def initialize(name, schema = {})
-      @schema = schema
-      @schema[:additional_properties] = false unless schema.key?(:additional_properties)
+      @schema = schema.dup
+      @schema[:additional_properties] = EasyTalk.configuration.default_additional_properties unless @schema.key?(:additional_properties)
       @name = name
       @klass = nil # Initialize klass to nil
+      @property_naming_strategy = EasyTalk.configuration.property_naming_strategy
     end
 
     EasyTalk::KEYWORDS.each do |keyword|
-      define_method(keyword) do |*values|
-        @schema[keyword] = values.size > 1 ? values : values.first
+      if keyword == :additional_properties
+        # Special handling for additional_properties to support type + constraints syntax
+        define_method(keyword) do |*args|
+          value = parse_additional_properties_args(args)
+          @schema[keyword] = value
+        end
+      else
+        define_method(keyword) do |*values|
+          @schema[keyword] = values.size > 1 ? values : values.first
+        end
       end
     end
 
+    sig { params(subschemas: T.untyped).void }
     def compose(*subschemas)
       @schema[:subschemas] ||= []
       @schema[:subschemas] += subschemas
     end
 
-    def property(name, type, constraints = {}, &)
+    sig { params(name: T.any(Symbol, String), type: T.untyped, constraints: T::Hash[Symbol, T.untyped], block: T.nilable(T.proc.void)).void }
+    def property(name, type, constraints = {}, &block)
       validate_property_name(name)
+      constraints[:as] ||= @property_naming_strategy.call(name)
       @schema[:properties] ||= {}
 
       if block_given?
@@ -49,6 +63,7 @@ module EasyTalk
       @schema[:properties][name] = { type:, constraints: }
     end
 
+    sig { params(name: T.any(Symbol, String)).void }
     def validate_property_name(name)
       return if name.to_s.match?(/^[A-Za-z_][A-Za-z0-9_]*$/)
 
@@ -57,11 +72,13 @@ module EasyTalk
       raise InvalidPropertyNameError, message
     end
 
+    sig { returns(T.nilable(T::Boolean)) }
     def optional?
       @schema[:optional]
     end
 
     # Helper method for nullable and optional properties
+    sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
     def nullable_optional_property(name, type, constraints = {})
       # Ensure type is nilable
       nilable_type = if type.respond_to?(:nilable?) && type.nilable?
@@ -76,5 +93,40 @@ module EasyTalk
       # Call standard property method
       property(name, nilable_type, constraints)
     end
+
+    sig { params(strategy: T.any(Symbol, T.proc.params(arg0: T.untyped).returns(Symbol))).void }
+    def property_naming_strategy(strategy)
+      @property_naming_strategy = EasyTalk::NamingStrategies.derive_strategy(strategy)
+    end
+
+    private
+
+    # Parses arguments for additional_properties to support multiple syntaxes:
+    # - additional_properties true/false (boolean)
+    # - additional_properties String (type class)
+    # - additional_properties Integer, minimum: 0, maximum: 100 (type + constraints)
+    sig { params(args: T::Array[T.untyped]).returns(T.untyped) }
+    def parse_additional_properties_args(args)
+      return args.first if args.empty?
+
+      # Single boolean argument
+      first_arg = args.first
+      return first_arg if args.size == 1 && (first_arg.is_a?(TrueClass) || first_arg.is_a?(FalseClass))
+
+      # Single type class (String, Integer, custom model, etc.)
+      return first_arg if args.size == 1 && first_arg.is_a?(Class)
+
+      # Type + constraints: additional_properties Integer, minimum: 0, maximum: 100
+      # args = [Integer, { minimum: 0, maximum: 100 }] or [Integer, minimum: 0, maximum: 100]
+      if args.size >= 1 && args.first.is_a?(Class)
+        type = args.first
+        # Merge all hash arguments as constraints
+        constraints = args[1..].select { |arg| arg.is_a?(Hash) }.reduce({}, :merge)
+        return { type:, **constraints }
+      end
+
+      # Fallback: return as-is
+      args.first
+    end
   end
 end

data/lib/easy_talk/schema_methods.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# typed: true
+
+module EasyTalk
+  # Shared methods for JSON Schema generation.
+  #
+  # This module provides common functionality for building JSON schemas,
+  # including $schema and $id resolution. It is included in both
+  # EasyTalk::Model and EasyTalk::Schema to avoid code duplication.
+  #
+  # @note Classes including this module must define:
+  #   - `name` - The class name (used in ref_template)
+  #   - `schema` - The built schema hash (used in json_schema)
+  #   - `@schema_definition` - Instance variable with schema metadata
+  #
+  module SchemaMethods
+    # Returns the reference template for the model.
+    # When prefer_external_refs is enabled and the model has a schema ID,
+    # returns the external $id URI. Otherwise, returns the local $defs reference.
+    #
+    # @return [String] The reference template for the model.
+    def ref_template
+      config = EasyTalk.configuration
+
+      # Use external ref when configured and $id available, otherwise fall back to local $defs
+      schema_id = resolve_schema_id if config.prefer_external_refs
+      schema_id || "#/$defs/#{name}"
+    end
+
+    # Returns the JSON schema for the model.
+    # This is the final output that includes the $schema keyword if configured.
+    #
+    # @return [Hash] The JSON schema for the model.
+    def json_schema
+      @json_schema ||= build_json_schema
+    end
+
+    private
+
+    # Builds the final JSON schema with optional $schema and $id keywords.
+    #
+    # @return [Hash] The JSON schema.
+    def build_json_schema
+      result = schema.as_json
+      schema_uri = resolve_schema_uri
+      id_uri = resolve_schema_id
+
+      prefix = {}
+      prefix['$schema'] = schema_uri if schema_uri
+      prefix['$id'] = id_uri if id_uri
+
+      return result if prefix.empty?
+
+      prefix.merge(result)
+    end
+
+    # Resolves the schema URI from per-model setting or global config.
+    #
+    # @return [String, nil] The schema URI.
+    def resolve_schema_uri
+      model_version = @schema_definition&.schema&.dig(:schema_version)
+
+      if model_version
+        return nil if model_version == :none
+
+        Configuration::SCHEMA_VERSIONS[model_version] || model_version.to_s
+      else
+        EasyTalk.configuration.schema_uri
+      end
+    end
+
+    # Resolves the schema ID from per-model setting, auto-generation, or global config.
+    # Precedence order:
+    #   1. Per-model explicit schema_id (highest priority)
+    #   2. Auto-generated from base_schema_uri (middle priority)
+    #   3. Global schema_id (lowest priority)
+    #
+    # @return [String, nil] The schema ID.
+    def resolve_schema_id
+      model_id = @schema_definition&.schema&.dig(:schema_id)
+
+      # Per-model explicit ID takes precedence
+      if model_id
+        return nil if model_id == :none
+
+        return model_id.to_s
+      end
+
+      # Auto-generate from base_schema_uri if enabled
+      config = EasyTalk.configuration
+      return generate_schema_id(config.base_schema_uri, name) if config.auto_generate_ids && config.base_schema_uri && name
+
+      # Fall back to global schema_id
+      config.schema_id
+    end
+
+    # Generates a schema ID from the base URI and model name.
+    # Normalizes the base URI and converts the model name to underscore case.
+    #
+    # @param base_uri [String] The base URI for schema IDs.
+    # @param model_name [String] The model class name.
+    # @return [String] The generated schema ID.
+    def generate_schema_id(base_uri, model_name)
+      # Normalize base URI (remove trailing slash)
+      base = base_uri.to_s.chomp('/')
+      # Convert model name to lowercase with underscores for URI segment
+      segment = model_name.to_s.underscore
+      "#{base}/#{segment}"
+    end
+  end
+end

data/lib/easy_talk/sorbet_extension.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 # This module provides additional functionality for working with Sorbet types.
 module SorbetExtension

data/lib/easy_talk/tools/function_builder.rb

@@ -27,7 +27,7 @@ module EasyTalk
 
         def generate_function_description(model)
           if model.respond_to?(:instructions)
-            raise Instructor::Error, 'The instructions must be a string' unless model.instructions.is_a?(String)
+            raise InvalidInstructionsError, 'The instructions must be a string' unless model.instructions.is_a?(String)
 
             model.instructions
           else