easy_talk 1.0.2 → 1.0.4

data/lib/easy_talk/active_record_schema_builder.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  # This class is responsible for building a SchemaDefinition from an ActiveRecord model
+  # It analyzes the database schema and creates a SchemaDefinition that can be
+  # passed to ObjectBuilder for final schema generation
+  class ActiveRecordSchemaBuilder
+    # Mapping of ActiveRecord column types to Ruby classes
+    COLUMN_TYPE_MAP = {
+      string: String,
+      text: String,
+      integer: Integer,
+      bigint: Integer,
+      float: Float,
+      decimal: Float,
+      boolean: T::Boolean,
+      date: Date,
+      datetime: DateTime,
+      timestamp: DateTime,
+      time: Time,
+      json: Hash,
+      jsonb: Hash
+    }.freeze
+
+    # Mapping for format constraints based on column type
+    FORMAT_MAP = {
+      date: 'date',
+      datetime: 'date-time',
+      timestamp: 'date-time',
+      time: 'time'
+    }.freeze
+
+    attr_reader :model
+
+    # Initialize the builder with an ActiveRecord model
+    #
+    # @param model [Class] An ActiveRecord model class
+    # @raise [ArgumentError] If the provided class is not an ActiveRecord model
+    def initialize(model)
+      raise ArgumentError, 'Class must be an ActiveRecord model' unless model.ancestors.include?(ActiveRecord::Base)
+
+      @model = model
+    end
+
+    # Build a SchemaDefinition object from the ActiveRecord model
+    #
+    # @return [EasyTalk::SchemaDefinition] A schema definition built from the database structure
+    def build_schema_definition
+      schema_def = SchemaDefinition.new(model.name)
+
+      # Apply basic schema metadata
+      apply_schema_metadata(schema_def)
+
+      # Add all database columns as properties
+      add_column_properties(schema_def)
+
+      # Add model associations as properties
+      add_association_properties(schema_def) unless EasyTalk.configuration.exclude_associations
+
+      # Add virtual properties defined in schema_enhancements
+      add_virtual_properties(schema_def)
+
+      schema_def
+    end
+
+    private
+
+    # Set top-level schema metadata like title, description, and additionalProperties
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def apply_schema_metadata(schema_def)
+      # Set title (from enhancements or derive from model name)
+      title = schema_enhancements['title'] || model.name.demodulize.humanize
+      schema_def.title(title)
+
+      # Set description if provided
+      if (description = schema_enhancements['description'])
+        schema_def.description(description)
+      end
+
+      # Set additionalProperties (from enhancements or configuration default)
+      additional_props = if schema_enhancements.key?('additionalProperties')
+                           schema_enhancements['additionalProperties']
+                         else
+                           EasyTalk.configuration.default_additional_properties
+                         end
+      schema_def.additional_properties(additional_props)
+    end
+
+    # Add properties based on database columns
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def add_column_properties(schema_def)
+      filtered_columns.each do |column|
+        # Get column enhancement info if it exists
+        column_enhancements = schema_enhancements.dig('properties', column.name.to_s) || {}
+
+        # Map the database type to Ruby type
+        ruby_type = COLUMN_TYPE_MAP.fetch(column.type, String)
+
+        # If the column is nullable, wrap the type in a Union with NilClass
+        ruby_type = T::Types::Union.new([ruby_type, NilClass]) if column.null
+
+        # Build constraints hash for this column
+        constraints = build_column_constraints(column, column_enhancements)
+
+        # Add the property to schema definition
+        schema_def.property(column.name.to_sym, ruby_type, constraints)
+      end
+    end
+
+    # Build constraints hash for a database column
+    #
+    # @param column [ActiveRecord::ConnectionAdapters::Column] The database column
+    # @param enhancements [Hash] Any schema enhancements for this column
+    # @return [Hash] The constraints hash
+    def build_column_constraints(column, enhancements)
+      constraints = {
+        optional: enhancements['optional'],
+        description: enhancements['description'],
+        title: enhancements['title']
+      }
+
+      # Add format constraint for date/time columns
+      if (format = FORMAT_MAP[column.type])
+        constraints[:format] = format
+      end
+
+      # Add max_length for string columns with limits
+      constraints[:max_length] = column.limit if column.type == :string && column.limit
+
+      # Add precision/scale for numeric columns
+      if column.type == :decimal && column.precision
+        constraints[:precision] = column.precision
+        constraints[:scale] = column.scale if column.scale
+      end
+
+      # Add default value if present and not a proc
+      constraints[:default] = column.default if column.default && !column.default.is_a?(Proc)
+
+      # Remove nil values
+      constraints.compact
+    end
+
+    # Add properties based on ActiveRecord associations
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def add_association_properties(schema_def)
+      model.reflect_on_all_associations.each do |association|
+        # Skip if we can't determine the class or it's in the association exclusion list
+        next if association_excluded?(association)
+
+        # Get association enhancement info if it exists
+        assoc_enhancements = schema_enhancements.dig('properties', association.name.to_s) || {}
+
+        case association.macro
+        when :belongs_to, :has_one
+          schema_def.property(
+            association.name,
+            association.klass,
+            { optional: assoc_enhancements['optional'], description: assoc_enhancements['description'] }.compact
+          )
+        when :has_many, :has_and_belongs_to_many
+          schema_def.property(
+            association.name,
+            T::Array[association.klass],
+            { optional: assoc_enhancements['optional'], description: assoc_enhancements['description'] }.compact
+          )
+        end
+      end
+    end
+
+    # Add virtual properties defined in schema_enhancements
+    #
+    # @param schema_def [EasyTalk::SchemaDefinition] The schema definition to modify
+    def add_virtual_properties(schema_def)
+      return unless schema_enhancements['properties']
+
+      schema_enhancements['properties'].each do |name, options|
+        next unless options['virtual']
+
+        # Map string type name to Ruby class
+        ruby_type = map_type_string_to_ruby_class(options['type'] || 'string')
+
+        # Build constraints for virtual property
+        constraints = {
+          description: options['description'],
+          title: options['title'],
+          optional: options['optional'],
+          format: options['format'],
+          default: options['default'],
+          min_length: options['minLength'],
+          max_length: options['maxLength'],
+          enum: options['enum']
+        }.compact
+
+        # Add the virtual property
+        schema_def.property(name.to_sym, ruby_type, constraints)
+      end
+    end
+
+    # Map a type string to a Ruby class
+    #
+    # @param type_str [String] The type string (e.g., 'string', 'integer')
+    # @return [Class] The corresponding Ruby class
+    def map_type_string_to_ruby_class(type_str)
+      case type_str.to_s.downcase
+      when 'string' then String
+      when 'integer' then Integer
+      when 'number' then Float
+      when 'boolean' then T::Boolean
+      when 'object' then Hash
+      when 'array' then Array
+      when 'date' then Date
+      when 'datetime' then DateTime
+      when 'time' then Time
+      else String # Default fallback
+      end
+    end
+
+    # Get all columns that should be included in the schema
+    #
+    # @return [Array<ActiveRecord::ConnectionAdapters::Column>] Filtered columns
+    def filtered_columns
+      model.columns.reject do |column|
+        config = EasyTalk.configuration
+        excluded_columns.include?(column.name.to_sym) ||
+          (config.exclude_primary_key && column.name == model.primary_key) ||
+          (config.exclude_timestamps && timestamp_column?(column.name)) ||
+          (config.exclude_foreign_keys && foreign_key_column?(column.name))
+      end
+    end
+
+    # Check if a column is a timestamp column
+    #
+    # @param column_name [String] The column name
+    # @return [Boolean] True if the column is a timestamp column
+    def timestamp_column?(column_name)
+      %w[created_at updated_at].include?(column_name)
+    end
+
+    # Check if a column is a foreign key column
+    #
+    # @param column_name [String] The column name
+    # @return [Boolean] True if the column is a foreign key column
+    def foreign_key_column?(column_name)
+      column_name.end_with?('_id')
+    end
+
+    # Check if an association should be excluded
+    #
+    # @param association [ActiveRecord::Reflection::AssociationReflection] The association
+    # @return [Boolean] True if the association should be excluded
+    def association_excluded?(association)
+      !association.klass ||
+        excluded_associations.include?(association.name.to_sym) ||
+        association.options[:polymorphic] # Skip polymorphic associations (complex to model)
+    end
+
+    # Get schema enhancements
+    #
+    # @return [Hash] Schema enhancements
+    def schema_enhancements
+      @schema_enhancements ||= if model.respond_to?(:schema_enhancements)
+                                 model.schema_enhancements.deep_transform_keys(&:to_s)
+                               else
+                                 {}
+                               end
+    end
+
+    # Get all excluded columns
+    #
+    # @return [Array<Symbol>] Excluded column names
+    def excluded_columns
+      @excluded_columns ||= begin
+        config = EasyTalk.configuration
+        global_exclusions = config.excluded_columns || []
+        model_exclusions = schema_enhancements['ignore'] || []
+
+        # Combine and convert to symbols for consistent comparison
+        (global_exclusions + model_exclusions).map(&:to_sym)
+      end
+    end
+
+    # Get all excluded associations
+    #
+    # @return [Array<Symbol>] Excluded association names
+    def excluded_associations
+      @excluded_associations ||= begin
+        model_exclusions = schema_enhancements['ignore_associations'] || []
+        model_exclusions.map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/easy_talk/builders/base_builder.rb

@@ -15,11 +15,11 @@ module EasyTalk
         optional: { type: T.nilable(T::Boolean), key: :optional }
       }.freeze
 
-      attr_reader :name, :schema, :options
+      attr_reader :property_name, :schema, :options
 
       sig do
         params(
-          name: Symbol,
+          property_name: Symbol,
           schema: T::Hash[Symbol, T.untyped],
           options: T::Hash[Symbol, String],
           valid_options: T::Hash[Symbol, T.untyped]
@@ -27,14 +27,14 @@ module EasyTalk
       end
       # Initializes a new instance of the BaseBuilder class.
       #
-      # @param name [Symbol] The name of the property.
+      # @param property_name [Symbol] The name of the property.
       # @param schema [Hash] A hash representing a json schema object.
       # @param options [Hash] The options for the builder (default: {}).
       # @param valid_options [Hash] The acceptable options for the given property type (default: {}).
-      def initialize(name, schema, options = {}, valid_options = {})
+      def initialize(property_name, schema, options = {}, valid_options = {})
         @valid_options = COMMON_OPTIONS.merge(valid_options)
-        options.assert_valid_keys(@valid_options.keys)
-        @name = name
+        EasyTalk.assert_valid_property_options(property_name, options, @valid_options.keys)
+        @property_name = property_name
         @schema = schema
         @options = options
       end
@@ -42,16 +42,18 @@ module EasyTalk
       # Builds the schema object based on the provided options.
       sig { returns(T::Hash[Symbol, T.untyped]) }
       def build
-        @valid_options.each_with_object(schema) do |(key, value), obj|
-          next if @options[key].nil?
+        @valid_options.each_with_object(schema) do |(constraint_name, value), obj|
+          next if @options[constraint_name].nil?
 
-          # Work around for Sorbet's default inability to type check the items inside an array
+          # Use our centralized validation
+          ErrorHelper.validate_constraint_value(
+            property_name: property_name,
+            constraint_name: constraint_name,
+            value_type: value[:type],
+            value: @options[constraint_name]
+          )
 
-          if value[:type].respond_to?(:recursively_valid?) && !value[:type].recursively_valid?(@options[key])
-            raise TypeError, "Invalid type for #{key}"
-          end
-
-          obj[value[:key]] = T.let(@options[key], value[:type])
+          obj[value[:key]] = @options[constraint_name]
         end
       end
 

data/lib/easy_talk/builders/composition_builder.rb

@@ -60,6 +60,18 @@ module EasyTalk
       def items
         @type.items
       end
+
+      # Builder class for AllOf composition.
+      class AllOfBuilder < CompositionBuilder
+      end
+
+      # Builder class for AnyOf composition.
+      class AnyOfBuilder < CompositionBuilder
+      end
+
+      # Builder class for OneOf composition.
+      class OneOfBuilder < CompositionBuilder
+      end
     end
   end
 end

data/lib/easy_talk/builders/object_builder.rb

@@ -1,5 +1,6 @@
+# frozen_string_literal: true
+
 require_relative 'base_builder'
-require 'set'
 
 module EasyTalk
   module Builders
@@ -68,6 +69,9 @@ module EasyTalk
         # Populate the final "required" array from @required_properties
         merged[:required] = @required_properties.to_a if @required_properties.any?
 
+        # Add additionalProperties: false by default if not explicitly set
+        merged[:additional_properties] = false unless merged.key?(:additional_properties)
+
         # Prune empty or nil values so we don't produce stuff like "properties": {} unnecessarily
         merged.reject! { |_k, v| v.nil? || v == {} || v == [] }
 
@@ -114,6 +118,11 @@ module EasyTalk
         # Check constraints[:optional]
         return true if prop_options.dig(:constraints, :optional)
 
+        # Check for nil_optional config to determine if nilable should also mean optional
+        if prop_options[:type].respond_to?(:nilable?) && prop_options[:type].nilable?
+          return EasyTalk.configuration.nilable_is_optional
+        end
+
         false
       end
 
@@ -129,8 +138,10 @@ module EasyTalk
                                          # This indicates block-style definition => nested schema
                                          nested_schema_builder(prop_options)
                                        else
+                                         # Remove optional constraints from the property
+                                         constraints = prop_options[:constraints].except(:optional)
                                          # Normal property: e.g. { type: String, constraints: {...} }
-                                         Property.new(prop_name, prop_options[:type], prop_options[:constraints])
+                                         Property.new(prop_name, prop_options[:type], constraints)
                                        end
       end
 

data/lib/easy_talk/builders/string_builder.rb

@@ -15,8 +15,7 @@ module EasyTalk
         max_length: { type: Integer, key: :maxLength },
         enum: { type: T::Array[String], key: :enum },
         const: { type: String, key: :const },
-        default: { type: String, key: :default },
-        optional: { type: T::Boolean, key: :optional }
+        default: { type: String, key: :default }
       }.freeze
 
       sig { params(name: Symbol, constraints: Hash).void }

data/lib/easy_talk/builders/temporal_builder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'string_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for temporal properties (date, datetime, time).
+    class TemporalBuilder < StringBuilder
+      # Initializes a new instance of the TemporalBuilder class.
+      #
+      # @param property_name [Symbol] The name of the property.
+      # @param options [Hash] The options for the builder.
+      # @param format [String] The format of the temporal property (date, date-time, time).
+      def initialize(property_name, options = {}, format = nil)
+        super(property_name, options)
+        @format = format
+      end
+
+      # Modifies the schema to include the format constraint for a temporal property.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def schema
+        super.tap do |schema|
+          schema[:format] = @format if @format
+        end
+      end
+
+      # Builder class for date properties.
+      class DateBuilder < TemporalBuilder
+        def initialize(property_name, options = {})
+          super(property_name, options, 'date')
+        end
+      end
+
+      # Builder class for datetime properties.
+      class DatetimeBuilder < TemporalBuilder
+        def initialize(property_name, options = {})
+          super(property_name, options, 'date-time')
+        end
+      end
+
+      # Builder class for time properties.
+      class TimeBuilder < TemporalBuilder
+        def initialize(property_name, options = {})
+          super(property_name, options, 'time')
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  class Configuration
+    attr_accessor :exclude_foreign_keys, :exclude_associations, :excluded_columns,
+                  :exclude_primary_key, :exclude_timestamps, :default_additional_properties,
+                  :nilable_is_optional
+
+    def initialize
+      @exclude_foreign_keys = true
+      @exclude_associations = true
+      @excluded_columns = []
+      @exclude_primary_key = true  # New option, defaulting to true
+      @exclude_timestamps = true   # New option, defaulting to true
+      @default_additional_properties = false
+      @nilable_is_optional = false
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/easy_talk/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  class Error < StandardError; end
+  class ConstraintError < Error; end
+  class UnknownOptionError < Error; end
+  class InvalidPropertyNameError < Error; end
+end

data/lib/easy_talk/errors_helper.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ErrorHelper
+    def self.raise_constraint_error(property_name:, constraint_name:, expected:, got:)
+      message = "Error in property '#{property_name}': Constraint '#{constraint_name}' expects #{expected}, " \
+                "but received #{got.inspect} (#{got.class})."
+      raise ConstraintError, message
+    end
+
+    def self.raise_array_constraint_error(property_name:, constraint_name:, index:, expected:, got:)
+      message = "Error in property '#{property_name}': Constraint '#{constraint_name}' at index #{index} " \
+                "expects #{expected}, but received #{got.inspect} (#{got.class})."
+      raise ConstraintError, message
+    end
+
+    def self.raise_unknown_option_error(property_name:, option:, valid_options:)
+      option = option.keys.first if option.is_a?(Hash)
+      message = "Unknown option '#{option}' for property '#{property_name}'. " \
+                "Valid options are: #{valid_options.join(', ')}."
+      raise UnknownOptionError, message
+    end
+
+    def self.extract_inner_type(type_info)
+      # No change needed here
+      if type_info.respond_to?(:type) && type_info.type.respond_to?(:raw_type)
+        type_info.type.raw_type
+      # special boolean handling
+      elsif type_info.try(:type).try(:name) == 'T::Boolean'
+        T::Boolean
+      elsif type_info.respond_to?(:type_parameter)
+        type_info.type_parameter
+      elsif type_info.respond_to?(:raw_a) && type_info.respond_to?(:raw_b)
+        # Handle SimplePairUnion types
+        [type_info.raw_a, type_info.raw_b]
+      elsif type_info.respond_to?(:types)
+        # Handle complex union types
+        type_info.types.map { |t| t.respond_to?(:raw_type) ? t.raw_type : t }
+      else
+        # Fallback to something sensible
+        Object
+      end
+    end
+
+    def self.validate_typed_array_values(property_name:, constraint_name:, type_info:, array_value:)
+      # Skip validation if it's not actually an array
+      return unless array_value.is_a?(Array)
+
+      # Extract the inner type from the array type definition
+      inner_type = extract_inner_type(type_info)
+
+      # Check each element of the array
+      array_value.each_with_index do |element, index|
+        if inner_type.is_a?(Array)
+          # For union types, check if the element matches any of the allowed types
+          unless inner_type.any? { |t| element.is_a?(t) }
+            expected = inner_type.join(' or ')
+            raise_array_constraint_error(
+              property_name: property_name,
+              constraint_name: constraint_name,
+              index: index,
+              expected: expected,
+              got: element
+            )
+          end
+        else
+          # For single types, just check against that type
+          next if [true, false].include?(element)
+
+          unless element.is_a?(inner_type)
+            raise_array_constraint_error(
+              property_name: property_name,
+              constraint_name: constraint_name,
+              index: index,
+              expected: inner_type,
+              got: element
+            )
+          end
+        end
+      end
+    end
+
+    def self.validate_constraint_value(property_name:, constraint_name:, value_type:, value:)
+      return if value.nil?
+
+      if value_type.to_s.include?('Boolean')
+        return if value.is_a?(Array) && value.all? { |v| [true, false].include?(v) }
+
+        unless [true, false].include?(value)
+          raise_constraint_error(
+            property_name: property_name,
+            constraint_name: constraint_name,
+            expected: 'Boolean (true or false)',
+            got: value
+          )
+        end
+        return
+      end
+
+      # Handle simple scalar types (String, Integer, etc.)
+      if value_type.is_a?(Class)
+        unless value.is_a?(value_type)
+          raise_constraint_error(
+            property_name: property_name,
+            constraint_name: constraint_name,
+            expected: value_type,
+            got: value
+          )
+        end
+      # Handle array types specifically
+      elsif value_type.class.name.include?('TypedArray') ||
+            (value_type.respond_to?(:to_s) && value_type.to_s.include?('T::Array'))
+        # This is an array type, validate it
+        validate_typed_array_values(
+          property_name: property_name,
+          constraint_name: constraint_name,
+          type_info: value_type,
+          array_value: value
+        )
+      # Handle Sorbet type objects
+      elsif value_type.class.ancestors.include?(T::Types::Base)
+        # Extract the inner type
+        inner_type = extract_inner_type(value_type)
+
+        if inner_type.is_a?(Array)
+          # For union types, check if the value matches any of the allowed types
+          unless inner_type.any? { |t| value.is_a?(t) }
+            expected = inner_type.join(' or ')
+            raise_constraint_error(
+              property_name: property_name,
+              constraint_name: constraint_name,
+              expected: expected,
+              got: value
+            )
+          end
+        elsif !value.is_a?(inner_type)
+          raise_constraint_error(
+            property_name: property_name,
+            constraint_name: constraint_name,
+            expected: inner_type,
+            got: value
+          )
+        end
+      end
+    end
+  end
+end