easy_talk 3.1.0 → 3.3.0

data/lib/easy_talk/validation_adapters/active_model_schema_validation.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ValidationAdapters
+    # ActiveModel-specific schema-level validations for object-level constraints.
+    #
+    # This module provides ActiveModel validations for JSON Schema keywords that apply
+    # to the object as a whole rather than individual properties:
+    # - minProperties: minimum number of properties that must be present
+    # - maxProperties: maximum number of properties that can be present
+    # - dependentRequired: conditional property requirements
+    #
+    # This module is tightly coupled with ActiveModel and is used exclusively by
+    # ActiveModelAdapter. Other validation adapters should implement their own
+    # schema-level validation logic.
+    #
+    module ActiveModelSchemaValidation
+      # Apply all applicable schema-level validations.
+      #
+      # @param klass [Class] The model class to apply validations to
+      # @param schema [Hash] The full schema hash containing schema-level constraints
+      # @return [void]
+      def self.apply(klass, schema)
+        apply_min_properties_validation(klass, schema[:min_properties]) if schema[:min_properties]
+        apply_max_properties_validation(klass, schema[:max_properties]) if schema[:max_properties]
+        apply_dependent_required_validation(klass, schema[:dependent_required]) if schema[:dependent_required]
+      end
+
+      # Apply minimum properties validation.
+      #
+      # @param klass [Class] The model class
+      # @param min_count [Integer] Minimum number of properties that must be present
+      def self.apply_min_properties_validation(klass, min_count)
+        define_count_method(klass)
+
+        klass.validate do |record|
+          present_count = record.send(:count_present_properties)
+          if present_count < min_count
+            record.errors.add(:base, "must have at least #{min_count} #{min_count == 1 ? 'property' : 'properties'} present")
+          end
+        end
+      end
+
+      # Apply maximum properties validation.
+      #
+      # @param klass [Class] The model class
+      # @param max_count [Integer] Maximum number of properties that can be present
+      def self.apply_max_properties_validation(klass, max_count)
+        define_count_method(klass)
+
+        klass.validate do |record|
+          present_count = record.send(:count_present_properties)
+          if present_count > max_count
+            record.errors.add(:base, "must have at most #{max_count} #{max_count == 1 ? 'property' : 'properties'} present")
+          end
+        end
+      end
+
+      # Apply dependent required validation.
+      # When a trigger property is present, all dependent properties must also be present.
+      #
+      # @param klass [Class] The model class
+      # @param dependencies [Hash<String, Array<String>>] Map of trigger properties to required properties
+      def self.apply_dependent_required_validation(klass, dependencies)
+        dependencies.each do |trigger_property, required_properties|
+          trigger_prop = trigger_property.to_sym
+          required_props = required_properties.map(&:to_sym)
+
+          klass.validate do |record|
+            trigger_value = record.public_send(trigger_prop)
+            trigger_present = trigger_value.present? || trigger_value == false
+
+            next unless trigger_present
+
+            required_props.each do |required_prop|
+              value = record.public_send(required_prop)
+              value_present = value.present? || value == false
+
+              record.errors.add(required_prop, "is required when #{trigger_prop} is present") unless value_present
+            end
+          end
+        end
+      end
+
+      # Define the count_present_properties private instance method on the class if not already defined.
+      # The method counts how many schema properties have non-nil/non-blank values.
+      #
+      # @param klass [Class] The model class
+      def self.define_count_method(klass)
+        # Check for private methods as well with the second argument
+        return if klass.method_defined?(:count_present_properties, true)
+
+        klass.send(:define_method, :count_present_properties) do
+          schema_props = self.class.schema_definition.schema[:properties] || {}
+          schema_props.keys.count do |prop|
+            value = public_send(prop)
+            value.present? || value == false # false is a valid present value
+          end
+        end
+        klass.send(:private, :count_present_properties)
+      end
+
+      private_class_method :define_count_method
+    end
+  end
+end

data/lib/easy_talk/validation_adapters/base.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ValidationAdapters
+    # Abstract base class for validation adapters.
+    #
+    # Validation adapters are responsible for converting JSON Schema constraints
+    # into validation rules for the target validation framework (e.g., ActiveModel,
+    # dry-validation, or custom validators).
+    #
+    # To create a custom adapter, subclass this class and implement the
+    # `apply_validations` method.
+    #
+    # @example Creating a custom adapter
+    #   class MyCustomAdapter < EasyTalk::ValidationAdapters::Base
+    #     def apply_validations
+    #       # Apply custom validations to @klass based on @constraints
+    #       @klass.validates @property_name, presence: true unless optional?
+    #     end
+    #   end
+    #
+    # @example Registering and using a custom adapter
+    #   EasyTalk::ValidationAdapters::Registry.register(:custom, MyCustomAdapter)
+    #
+    #   class User
+    #     include EasyTalk::Model
+    #     define_schema(validations: :custom) do
+    #       property :name, String
+    #     end
+    #   end
+    #
+    class Base
+      # Build validations for a property and apply them to the model class.
+      # This is the primary interface that adapters must implement.
+      #
+      # @param klass [Class] The model class to apply validations to
+      # @param property_name [Symbol, String] The name of the property
+      # @param type [Class, Object] The type of the property (Ruby class or Sorbet type)
+      # @param constraints [Hash] The JSON Schema constraints for the property
+      #   Possible keys: :min_length, :max_length, :minimum, :maximum, :pattern,
+      #   :format, :enum, :const, :min_items, :max_items, :unique_items, :optional
+      # @return [void]
+      def self.build_validations(klass, property_name, type, constraints)
+        new(klass, property_name, type, constraints).apply_validations
+      end
+
+      # Build schema-level validations (e.g., min_properties, max_properties, dependent_required).
+      # Subclasses can override this method to implement schema-level validations.
+      #
+      # @param klass [Class] The model class to apply validations to
+      # @param schema [Hash] The full schema hash containing schema-level constraints
+      # @return [void]
+      def self.build_schema_validations(klass, schema)
+        # Default implementation does nothing - subclasses can override
+      end
+
+      # Initialize a new validation adapter instance.
+      #
+      # @param klass [Class] The model class to apply validations to
+      # @param property_name [Symbol, String] The name of the property
+      # @param type [Class, Object] The type of the property
+      # @param constraints [Hash] The JSON Schema constraints for the property
+      def initialize(klass, property_name, type, constraints)
+        @klass = klass
+        @property_name = property_name.to_sym
+        @type = type
+        @constraints = constraints || {}
+      end
+
+      # Apply validations based on property type and constraints.
+      # Subclasses MUST implement this method.
+      #
+      # @abstract
+      # @return [void]
+      # @raise [NotImplementedError] if the subclass does not implement this method
+      def apply_validations
+        raise NotImplementedError, "#{self.class} must implement #apply_validations"
+      end
+
+      protected
+
+      attr_reader :klass, :property_name, :type, :constraints
+
+      # Check if a property is optional based on constraints and configuration.
+      #
+      # A property is considered optional if:
+      # - The :optional constraint is explicitly set to true
+      # - The type is nilable AND nilable_is_optional configuration is true
+      #
+      # @return [Boolean] true if the property is optional
+      def optional?
+        @constraints[:optional] == true ||
+          (@type.respond_to?(:nilable?) && @type.nilable? && EasyTalk.configuration.nilable_is_optional)
+      end
+
+      # Check if the type is nilable (e.g., T.nilable(String)).
+      #
+      # @param t [Class, Object] The type to check (defaults to @type)
+      # @return [Boolean] true if the type is nilable
+      def nilable_type?(type_to_check = @type)
+        type_to_check.respond_to?(:nilable?) && type_to_check.nilable?
+      end
+
+      # Extract the inner type from a complex type like T.nilable(String) or T.nilable(T::Array[Model]).
+      #
+      # @param type_to_unwrap [Class, Object] The type to unwrap (defaults to @type)
+      # @return [Class, Object] The inner type, or the original type if not wrapped
+      def extract_inner_type(type_to_unwrap = @type)
+        if type_to_unwrap.respond_to?(:unwrap_nilable)
+          unwrapped = type_to_unwrap.unwrap_nilable
+          # Return TypedArray directly (for T.nilable(T::Array[Model]))
+          return unwrapped if unwrapped.is_a?(T::Types::TypedArray)
+          # Return raw_type for simple types (for T.nilable(String))
+          return unwrapped.raw_type if unwrapped.respond_to?(:raw_type)
+        end
+
+        if type_to_unwrap.respond_to?(:types)
+          # For union types, find the non-nil type
+          # Prefer TypedArray if present, otherwise find type with raw_type
+          type_to_unwrap.types.find { |t| t.is_a?(T::Types::TypedArray) } ||
+            type_to_unwrap.types.find { |t| t.respond_to?(:raw_type) && t.raw_type != NilClass }
+        else
+          type_to_unwrap
+        end
+      end
+
+      # Determine the actual class for a type, handling Sorbet types.
+      #
+      # @param type_to_resolve [Class, Object] The type to resolve
+      # @return [Class, Array<Class>] The resolved class or classes
+      def get_type_class(type_to_resolve)
+        if type_to_resolve.is_a?(Class)
+          type_to_resolve
+        elsif type_to_resolve.respond_to?(:raw_type)
+          type_to_resolve.raw_type
+        elsif type_to_resolve.is_a?(T::Types::TypedArray)
+          Array
+        elsif type_to_resolve.is_a?(EasyTalk::Types::Tuple)
+          Array
+        elsif type_to_resolve.is_a?(Symbol) || type_to_resolve.is_a?(String)
+          begin
+            type_to_resolve.to_s.classify.constantize
+          rescue StandardError
+            String
+          end
+        elsif TypeIntrospection.boolean_type?(type_to_resolve)
+          [TrueClass, FalseClass]
+        elsif nilable_type?(type_to_resolve)
+          extract_inner_type(type_to_resolve)
+        else
+          String
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/validation_adapters/none_adapter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ValidationAdapters
+    # No-op validation adapter.
+    #
+    # This adapter does not apply any validations. Use it when you want
+    # schema generation without any validation side effects.
+    #
+    # @example Disabling validations for a model
+    #   class ApiContract
+    #     include EasyTalk::Model
+    #
+    #     define_schema(validations: :none) do
+    #       property :name, String, min_length: 5
+    #     end
+    #   end
+    #
+    #   contract = ApiContract.new(name: 'X')
+    #   contract.valid? # => true (no validations applied)
+    #
+    # @example Using globally
+    #   EasyTalk.configure do |config|
+    #     config.validation_adapter = :none
+    #   end
+    #
+    class NoneAdapter < Base
+      # Build no schema-level validations (no-op).
+      #
+      # @param klass [Class] The model class (unused)
+      # @param schema [Hash] The schema hash (unused)
+      # @return [void]
+      def self.build_schema_validations(klass, schema)
+        # Intentionally empty - no validations applied
+      end
+
+      # Apply no validations (no-op).
+      #
+      # @return [void]
+      def apply_validations
+        # Intentionally empty - no validations applied
+      end
+    end
+  end
+end

data/lib/easy_talk/validation_adapters/registry.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module EasyTalk
+  module ValidationAdapters
+    # Registry for validation adapters.
+    #
+    # The registry allows adapters to be registered with symbolic names and
+    # resolved from various input types (symbols, classes, or nil for default).
+    #
+    # @example Registering an adapter
+    #   EasyTalk::ValidationAdapters::Registry.register(:custom, MyCustomAdapter)
+    #
+    # @example Resolving an adapter
+    #   adapter = EasyTalk::ValidationAdapters::Registry.resolve(:active_model)
+    #   adapter.build_validations(klass, :name, String, {})
+    #
+    class Registry
+      class << self
+        # Get the hash of registered adapters.
+        #
+        # @return [Hash{Symbol => Class}] The registered adapters
+        def adapters
+          @adapters ||= {}
+        end
+
+        # Register an adapter with a symbolic name.
+        #
+        # @param name [Symbol, String] The adapter identifier
+        # @param adapter_class [Class] The adapter class (must respond to .build_validations)
+        # @raise [ArgumentError] if the adapter does not respond to .build_validations
+        # @return [void]
+        def register(name, adapter_class)
+          raise ArgumentError, "Adapter must respond to .build_validations" unless adapter_class.respond_to?(:build_validations)
+
+          adapters[name.to_sym] = adapter_class
+        end
+
+        # Resolve an adapter from various input types.
+        #
+        # @param adapter [Symbol, Class, nil] The adapter identifier or class
+        #   - nil: returns the default :active_model adapter
+        #   - Symbol: looks up the adapter by name in the registry
+        #   - Class: returns the class directly (assumes it implements the adapter interface)
+        # @return [Class] The adapter class
+        # @raise [ArgumentError] if the adapter symbol is not registered or type is invalid
+        def resolve(adapter)
+          case adapter
+          when nil
+            adapters[:active_model] || raise(ArgumentError, "No default adapter registered")
+          when Symbol
+            adapters[adapter] || raise(ArgumentError, "Unknown validation adapter: #{adapter.inspect}")
+          when Class
+            adapter
+          else
+            raise ArgumentError, "Invalid adapter type: #{adapter.class}. Expected Symbol, Class, or nil."
+          end
+        end
+
+        # Check if an adapter is registered with the given name.
+        #
+        # @param name [Symbol, String] The adapter name to check
+        # @return [Boolean] true if the adapter is registered
+        def registered?(name)
+          adapters.key?(name.to_sym)
+        end
+
+        # Reset the registry (useful for testing).
+        # Re-registers the default adapters after clearing.
+        #
+        # @return [void]
+        def reset!
+          @adapters = nil
+          register_default_adapters
+        end
+
+        # Register the default validation adapters.
+        # This is called during gem initialization and after reset!
+        #
+        # @return [void]
+        def register_default_adapters
+          register(:active_model, ActiveModelAdapter)
+          register(:none, NoneAdapter)
+        end
+      end
+    end
+  end
+end