rapitapir 0.1.0

data/lib/rapitapir/types/auto_derivation.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+
+module RapiTapir
+  module Types
+    # Auto-derivation module for creating RapiTapir type schemas from various sources
+    #
+    # This module provides automatic type inference and schema generation from:
+    # - Ruby hashes with sample values
+    # - JSON Schema documents
+    # - OpenStruct instances
+    # - Protocol Buffer message classes
+    #
+    # All methods support field filtering via only/except parameters.
+    # rubocop:disable Metrics/ModuleLength
+    module AutoDerivation
+      class << self
+        # Derive schema from a plain Hash with sample values
+        #
+        # @param hash [Hash] Hash with sample values for type inference
+        # @param only [Array<Symbol>] Only include these fields
+        # @param except [Array<Symbol>] Exclude these fields
+        # @return [RapiTapir::Types::Hash]
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def from_hash(hash, only: nil, except: nil)
+          raise ArgumentError, "Expected Hash, got #{hash.class}" unless hash.is_a?(::Hash)
+
+          schema_hash = {}
+          hash.each do |field_name, value|
+            # Apply field filtering
+            field_sym = field_name.to_sym
+            next if only && !Array(only).map(&:to_sym).include?(field_sym)
+            next if except && Array(except).map(&:to_sym).include?(field_sym)
+
+            rapitapir_type = infer_type_from_value(value)
+            schema_hash[field_name.to_s] = rapitapir_type
+          end
+
+          create_hash_type(schema_hash)
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        # Derive schema from JSON Schema object
+        #
+        # @param json_schema [Hash] JSON Schema object
+        # @param only [Array<Symbol>] Only include these fields
+        # @param except [Array<Symbol>] Exclude these fields
+        # @return [RapiTapir::Types::Hash]
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def from_json_schema(json_schema, only: nil, except: nil)
+          unless json_schema.is_a?(::Hash) && json_schema['type'] == 'object'
+            raise ArgumentError, 'JSON Schema must be an object type'
+          end
+
+          properties = json_schema['properties'] || {}
+          required_fields = Array(json_schema['required'])
+          schema_hash = {}
+
+          properties.each do |field_name, field_schema|
+            field_sym = field_name.to_sym
+            next if only && !Array(only).map(&:to_sym).include?(field_sym)
+            next if except && Array(except).map(&:to_sym).include?(field_sym)
+
+            required = required_fields.include?(field_name)
+            rapitapir_type = convert_json_schema_type(field_schema, required: required)
+            schema_hash[field_name] = rapitapir_type
+          end
+
+          RapiTapir::Types.hash(schema_hash)
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        # Derive schema from OpenStruct instance
+        #
+        # @param open_struct [OpenStruct] OpenStruct with populated fields
+        # @param only [Array<Symbol>] Only include these fields
+        # @param except [Array<Symbol>] Exclude these fields
+        # @return [RapiTapir::Types::Hash]
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Style/OpenStructUse
+        def from_open_struct(open_struct, only: nil, except: nil)
+          raise ArgumentError, "Expected OpenStruct, got #{open_struct.class}" unless open_struct.is_a?(OpenStruct)
+
+          schema_hash = {}
+          open_struct.to_h.each do |field_name, value|
+            field_sym = field_name.to_sym
+            next if only && !Array(only).map(&:to_sym).include?(field_sym)
+            next if except && Array(except).map(&:to_sym).include?(field_sym)
+
+            rapitapir_type = infer_type_from_value(value)
+            schema_hash[field_name.to_s] = rapitapir_type
+          end
+
+          create_hash_type(schema_hash)
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Style/OpenStructUse
+
+        # Derive schema from Protobuf message class
+        #
+        # @param proto_class [Class] Protobuf message class
+        # @param only [Array<Symbol>] Only include these fields
+        # @param except [Array<Symbol>] Exclude these fields
+        # @return [RapiTapir::Types::Hash]
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def from_protobuf(proto_class, only: nil, except: nil)
+          unless defined?(Google::Protobuf) && proto_class.respond_to?(:descriptor)
+            raise ArgumentError, 'Protobuf not available or invalid protobuf class'
+          end
+
+          schema_hash = {}
+          proto_class.descriptor.each do |field_descriptor|
+            field_name = field_descriptor.name
+            field_sym = field_name.to_sym
+
+            next if only && !Array(only).map(&:to_sym).include?(field_sym)
+            next if except && Array(except).map(&:to_sym).include?(field_sym)
+
+            rapitapir_type = convert_protobuf_type(field_descriptor)
+            schema_hash[field_name] = rapitapir_type
+          end
+
+          create_hash_type(schema_hash)
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        private
+
+        # Convert JSON Schema field type to RapiTapir type
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+        def convert_json_schema_type(field_schema, required: true)
+          base_type = case field_schema['type']
+                      when 'string'
+                        case field_schema['format']
+                        when 'email'
+                          create_email_type
+                        when 'uuid'
+                          create_uuid_type
+                        when 'date'
+                          create_date_type
+                        when 'date-time'
+                          create_datetime_type
+                        else
+                          create_string_type
+                        end
+                      when 'integer'
+                        create_integer_type
+                      when 'number'
+                        create_float_type
+                      when 'boolean'
+                        create_boolean_type
+                      when 'array'
+                        item_type = if field_schema['items']
+                                      convert_json_schema_type(field_schema['items'], required: true)
+                                    else
+                                      create_string_type
+                                    end
+                        create_array_type(item_type)
+                      when 'object'
+                        create_hash_type({})
+                      else
+                        create_string_type
+                      end
+
+          required ? base_type : create_optional_type(base_type)
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
+
+        # Convert protobuf field descriptor to RapiTapir type
+        def convert_protobuf_type(field_descriptor)
+          base_type = case field_descriptor.type
+                      when :TYPE_INT32, :TYPE_INT64, :TYPE_UINT32, :TYPE_UINT64
+                        create_integer_type
+                      when :TYPE_FLOAT, :TYPE_DOUBLE
+                        create_float_type
+                      when :TYPE_BOOL
+                        create_boolean_type
+                      when :TYPE_MESSAGE
+                        create_hash_type({})
+                      else
+                        # :TYPE_STRING, :TYPE_BYTES, :TYPE_ENUM, and others default to string
+                        create_string_type
+                      end
+
+          if field_descriptor.label == :LABEL_REPEATED
+            create_array_type(base_type)
+          else
+            base_type
+          end
+        end
+
+        # Infer RapiTapir type from Ruby value
+        # rubocop:disable Metrics/CyclomaticComplexity
+        def infer_type_from_value(value)
+          case value
+          when ::Integer
+            create_integer_type
+          when ::Float
+            create_float_type
+          when TrueClass, FalseClass
+            create_boolean_type
+          when ::Date
+            create_date_type
+          when ::Time, ::DateTime
+            create_datetime_type
+          when ::Array
+            item_type = value.empty? ? create_string_type : infer_type_from_value(value.first)
+            create_array_type(item_type)
+          when ::Hash
+            create_hash_type({})
+          else
+            # ::String, nil, and other unknown types default to string
+            create_string_type
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity
+
+        # Helper methods to create types without using convenience methods
+        def create_string_type
+          RapiTapir::Types::String.new
+        end
+
+        def create_integer_type
+          RapiTapir::Types::Integer.new
+        end
+
+        def create_float_type
+          RapiTapir::Types::Float.new
+        end
+
+        def create_boolean_type
+          RapiTapir::Types::Boolean.new
+        end
+
+        def create_date_type
+          RapiTapir::Types::Date.new
+        end
+
+        def create_datetime_type
+          RapiTapir::Types::DateTime.new
+        end
+
+        def create_email_type
+          RapiTapir::Types::Email.new
+        end
+
+        def create_uuid_type
+          RapiTapir::Types::UUID.new
+        end
+
+        def create_array_type(item_type)
+          RapiTapir::Types::Array.new(item_type)
+        end
+
+        def create_hash_type(field_types)
+          RapiTapir::Types::Hash.new(field_types)
+        end
+
+        def create_optional_type(base_type)
+          RapiTapir::Types::Optional.new(base_type)
+        end
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/rapitapir/types/base.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Types
+    # Base class for all RapiTapir types
+    #
+    # Provides the fundamental interface for type validation, coercion,
+    # constraint checking, and schema generation that all specific types inherit.
+    #
+    # @abstract Subclass and implement {#validate_constraints} and {#coerce_value}
+    # @example Creating a custom type
+    #   class CustomType < Base
+    #     def validate_constraints(value)
+    #       # Validation logic
+    #     end
+    #
+    #     def coerce_value(value)
+    #       # Coercion logic
+    #     end
+    #   end
+    class Base
+      attr_reader :constraints, :metadata
+
+      def initialize(**constraints)
+        @constraints = constraints.freeze
+        @metadata = {}
+      end
+
+      # Validate a value against this type
+      def validate(value)
+        errors = []
+
+        # Check if value is required but nil
+        if value.nil? && required?
+          errors << 'Value is required but got nil'
+          return validation_result(false, errors)
+        end
+
+        # Allow nil for optional types
+        return validation_result(true, []) if value.nil? && !required?
+
+        # Perform type-specific validation
+        type_errors = validate_type(value)
+        errors.concat(type_errors)
+
+        # Perform constraint validation
+        constraint_errors = validate_constraints(value)
+        errors.concat(constraint_errors)
+
+        validation_result(errors.empty?, errors)
+      end
+
+      # Coerce a value to this type
+      def coerce(value)
+        return nil if value.nil? && !required?
+
+        raise CoercionError.new(value, self.class.name, 'Required value cannot be nil') if value.nil? && required?
+
+        coerce_value(value)
+      end
+
+      # Check if this type is required
+      def required?
+        !constraints.fetch(:optional, false)
+      end
+
+      # Check if this type is optional
+      def optional?
+        constraints.fetch(:optional, false)
+      end
+
+      # Get the JSON Schema representation
+      def to_json_schema
+        schema = base_json_schema
+        apply_constraints_to_schema(schema)
+        schema
+      end
+
+      # Get a string representation
+      def to_s
+        constraint_strs = constraints.map { |k, v| "#{k}: #{v}" }
+        constraint_part = constraint_strs.empty? ? '' : "(#{constraint_strs.join(', ')})"
+        "#{self.class.name.split('::').last}#{constraint_part}"
+      end
+
+      # Add metadata to this type
+      def with_metadata(**meta)
+        dup.tap { |type| type.instance_variable_set(:@metadata, metadata.merge(meta)) }
+      end
+
+      # Add description to this type
+      def description(text)
+        with_metadata(description: text)
+      end
+
+      # Add example to this type
+      def example(value)
+        with_metadata(example: value)
+      end
+
+      protected
+
+      # Override in subclasses to implement type-specific validation
+      def validate_type(_value)
+        []
+      end
+
+      # Override in subclasses to implement constraint validation
+      def validate_constraints(_value)
+        []
+      end
+
+      # Override in subclasses to implement value coercion
+      def coerce_value(value)
+        value
+      end
+
+      # Override in subclasses to provide base JSON schema
+      def base_json_schema
+        { type: json_type }
+      end
+
+      # Override in subclasses to specify JSON type
+      def json_type
+        'object'
+      end
+
+      # Apply constraints to JSON schema
+      def apply_constraints_to_schema(schema)
+        # Add common constraint mappings here
+        schema[:description] = metadata[:description] if metadata[:description]
+        schema[:example] = metadata[:example] if metadata[:example]
+      end
+
+      private
+
+      def validation_result(valid, errors)
+        {
+          valid: valid,
+          errors: errors,
+          value_errors: errors.empty? ? [] : [ValidationError.new(nil, self, errors)]
+        }
+      end
+    end
+  end
+end

data/lib/rapitapir/types/boolean.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RapiTapir
+  module Types
+    # Boolean type for validating true/false values
+    # Accepts true, false, and can coerce from string representations
+    class Boolean < Base
+      protected
+
+      def validate_type(value)
+        return [] if [true, false].include?(value)
+
+        ["Expected boolean (true or false), got #{value.class}"]
+      end
+
+      def validate_constraints(_value)
+        # Boolean types don't have additional constraints beyond true/false
+        []
+      end
+
+      def coerce_value(value)
+        case value
+        when true, false then value
+        when 'true', 'TRUE', '1', 1 then true
+        when 'false', 'FALSE', '0', 0 then false
+        when ::String
+          case value.strip.downcase
+          when 'true', 'yes', 'on', '1' then true
+          when 'false', 'no', 'off', '0' then false
+          else
+            raise CoercionError.new(value, 'Boolean', "Cannot convert '#{value}' to boolean")
+          end
+        else
+          # Use Ruby's truthiness as fallback
+          !!value
+        end
+      end
+
+      def json_type
+        'boolean'
+      end
+    end
+  end
+end

data/lib/rapitapir/types/date.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require 'date'
+
+module RapiTapir
+  module Types
+    # Date type for validating date values in various formats
+    # Accepts Date objects and string representations that can be parsed
+    class Date < Base
+      def initialize(format: nil, **options)
+        super
+      end
+
+      protected
+
+      def validate_type(value)
+        return [] if value.is_a?(::Date)
+        return [] if value.is_a?(::String) && parseable_date?(value)
+
+        ["Expected Date or date string, got #{value.class}"]
+      end
+
+      def validate_constraints(value)
+        errors = []
+
+        if constraints[:format] && value.is_a?(::String)
+          format_errors = validate_date_format(value, constraints[:format])
+          errors.concat(format_errors)
+        end
+
+        errors
+      end
+
+      def coerce_value(value)
+        case value
+        when ::Date then value
+        when ::DateTime, ::Time then value.to_date
+        when ::String
+          ::Date.parse(value)
+        when ::Integer
+          # Assume Unix timestamp
+          ::Time.at(value).to_date
+        else
+          raise CoercionError.new(value, 'Date', 'Value cannot be converted to Date') unless value.respond_to?(:to_date)
+
+          value.to_date
+
+        end
+      rescue ArgumentError => e
+        raise CoercionError.new(value, 'Date', e.message)
+      end
+
+      def json_type
+        'string'
+      end
+
+      def apply_constraints_to_schema(schema)
+        super
+        schema[:format] = 'date'
+        schema[:format] = constraints[:format].to_s if constraints[:format]
+      end
+
+      private
+
+      def parseable_date?(value)
+        ::Date.parse(value)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      def validate_date_format(value, format)
+        case format
+        when :iso8601, 'iso8601'
+          iso_date_pattern = /\A\d{4}-\d{2}-\d{2}\z/
+          iso_date_pattern.match?(value) ? [] : ['Date must be in ISO8601 format (YYYY-MM-DD)']
+        when String
+          # Custom format validation
+          begin
+            ::Date.strptime(value, format)
+            []
+          rescue ArgumentError
+            ["Date does not match format #{format}"]
+          end
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/types/datetime.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require 'date'
+
+module RapiTapir
+  module Types
+    # DateTime type for validating datetime values with timezone handling
+    # Accepts DateTime objects and string representations in various formats
+    class DateTime < Base
+      def initialize(format: nil, **options)
+        super
+      end
+
+      protected
+
+      def validate_type(value)
+        return [] if value.is_a?(::DateTime) || value.is_a?(::Time)
+        return [] if value.is_a?(::String) && parseable_datetime?(value)
+
+        ["Expected DateTime, Time, or datetime string, got #{value.class}"]
+      end
+
+      def validate_constraints(value)
+        errors = []
+
+        if constraints[:format] && value.is_a?(::String)
+          format_errors = validate_datetime_format(value, constraints[:format])
+          errors.concat(format_errors)
+        end
+
+        errors
+      end
+
+      def coerce_value(value)
+        case value
+        when ::DateTime then value
+        when ::Time, ::Date then value.to_datetime
+        when ::String
+          ::DateTime.parse(value)
+        when ::Integer
+          # Assume Unix timestamp
+          ::Time.at(value).to_datetime
+        else
+          unless value.respond_to?(:to_datetime)
+            raise CoercionError.new(value, 'DateTime', 'Value cannot be converted to DateTime')
+          end
+
+          value.to_datetime
+
+        end
+      rescue ArgumentError => e
+        raise CoercionError.new(value, 'DateTime', e.message)
+      end
+
+      def json_type
+        'string'
+      end
+
+      def apply_constraints_to_schema(schema)
+        super
+        schema[:format] = 'date-time'
+        schema[:format] = constraints[:format].to_s if constraints[:format]
+      end
+
+      private
+
+      def parseable_datetime?(value)
+        ::DateTime.parse(value)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      def validate_datetime_format(value, format)
+        case format
+        when :iso8601, 'iso8601'
+          iso_datetime_pattern = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+          iso_datetime_pattern.match?(value) ? [] : ['DateTime must be in ISO8601 format']
+        when :rfc3339, 'rfc3339'
+          # RFC3339 is essentially the same as ISO8601 for our purposes
+          iso_datetime_pattern = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+          iso_datetime_pattern.match?(value) ? [] : ['DateTime must be in RFC3339 format']
+        when String
+          # Custom format validation
+          begin
+            ::DateTime.strptime(value, format)
+            []
+          rescue ArgumentError
+            ["DateTime does not match format #{format}"]
+          end
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/types/email.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module RapiTapir
+  module Types
+    # Email type for validating email address strings
+    # Extends String type with email format validation
+    class Email < String
+      EMAIL_PATTERN = /\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i
+
+      def initialize(**options)
+        super(pattern: EMAIL_PATTERN, format: :email, **options)
+      end
+
+      protected
+
+      def validate_type(value)
+        return ["Expected string, got #{value.class}"] unless value.is_a?(::String)
+        return ['Invalid email format'] unless EMAIL_PATTERN.match?(value)
+
+        []
+      end
+
+      def apply_constraints_to_schema(schema)
+        super
+        schema[:format] = 'email'
+        schema[:pattern] = EMAIL_PATTERN.source
+      end
+    end
+  end
+end