liminal 0.1.0

data/lib/liminal/dialects/openapi_30.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "set"
+require "uri"
+require "liminal/dialects/openapi_30/metadata_validator"
+
+module Liminal
+  module Dialects
+    # OpenAPI 3.0-specific schema behavior and validation.
+    class OpenAPI30
+      private_constant :MetadataValidator
+
+      class InvalidFragmentError < StandardError; end
+      class UnsupportedPatternError < StandardError; end
+
+      NAME = :openapi_3_0
+      TYPES = %w[array boolean integer number object string].freeze
+      KEYWORD_ORDER = %w[
+        $ref title type format nullable description properties required items
+        enum minimum exclusiveMinimum maximum exclusiveMaximum multipleOf
+        minLength maxLength pattern minItems maxItems uniqueItems minProperties
+        maxProperties additionalProperties allOf oneOf anyOf not default example
+        readOnly writeOnly deprecated discriminator xml externalDocs
+      ].freeze
+      ALLOWED_KEYWORDS = KEYWORD_ORDER.to_set.freeze
+      SCHEMA_ARRAY_KEYWORDS = %w[allOf oneOf anyOf].freeze
+      NUMERIC_KEYWORDS = %w[maximum minimum].freeze
+      SIZE_KEYWORDS = %w[maxLength minLength maxItems minItems maxProperties minProperties].freeze
+      BOOLEAN_KEYWORDS = %w[exclusiveMaximum exclusiveMinimum uniqueItems nullable readOnly writeOnly deprecated].freeze
+      STRING_KEYWORDS = %w[$ref title description format pattern].freeze
+      RUBY_ONLY_PATTERN_TOKENS = [
+        /\\[CEGHhKMNOPRXYZegky]/,
+        /\\[ghk]<|\\k'/,
+        /\\[pP]\{/,
+        /\\u\{/,
+        /\[\[:/,
+        /\[[^\]]*&&/,
+        /\(\?>|\(\?#|\(\?~|\(\?\(|\(\?<=[^)]|\(\?<!/,
+        /\(\?<[^=!]|\(\?'/,
+        /\(\?[imx-]+[:)]/,
+        /(?:\*|\+|\?|\{[^}]+\})\+/
+      ].freeze
+
+      attr_reader :name
+
+      def initialize
+        @name = NAME
+      end
+
+      def nullable(fragment)
+        if fragment.key?("type")
+          fragment.merge("nullable" => true)
+        elsif fragment.key?("anyOf") && fragment.keys == ["anyOf"]
+          {"anyOf" => fragment.fetch("anyOf").map { |alternative| nullable(alternative) }}
+        else
+          raise InvalidFragmentError,
+                "nullable schemas require an explicit type in the same Schema Object"
+        end
+      end
+
+      def pattern(regexp)
+        raise UnsupportedPatternError, "expected a Ruby Regexp" unless regexp.is_a?(Regexp)
+        raise UnsupportedPatternError, "Ruby regular-expression options are not supported" unless regexp.options.zero?
+
+        source = regexp.source
+        if ruby_line_anchor?(source)
+          raise UnsupportedPatternError,
+                "Ruby ^ and $ line anchors are not safely ECMA-262-compatible; use \\A and \\z"
+        end
+        if RUBY_ONLY_PATTERN_TOKENS.any? { |token| token.match?(source) }
+          raise UnsupportedPatternError, "the Ruby regular expression is not safely ECMA-262-compatible"
+        end
+
+        translate_anchors(source)
+      end
+
+      # Validate a recursively string-keyed Schema Object fragment.
+      def validate!(schema)
+        validate_schema!(schema)
+        schema
+      end
+
+      # Produce stable keyword ordering while preserving deterministic property
+      # order from the dry-schema AST.
+      def order(schema)
+        order_schema(schema)
+      end
+
+      private
+
+      def ruby_line_anchor?(source)
+        escaped = false
+        character_class = false
+
+        source.each_char do |character|
+          if escaped
+            escaped = false
+          elsif character == "\\"
+            escaped = true
+          elsif character == "["
+            character_class = true
+          elsif character == "]"
+            character_class = false
+          elsif !character_class && %w[^ $].include?(character)
+            return true
+          end
+        end
+
+        false
+      end
+
+      def translate_anchors(source)
+        translated = +""
+        index = 0
+        while index < source.length
+          unless source[index] == "\\"
+            translated << source[index]
+            index += 1
+            next
+          end
+
+          slash_start = index
+          index += 1 while index < source.length && source[index] == "\\"
+          slash_count = index - slash_start
+          anchor = source[index]
+          if slash_count.odd? && %w[A z].include?(anchor)
+            translated << ("\\" * (slash_count - 1)) << (anchor == "A" ? "^" : "$")
+            index += 1
+          else
+            translated << source[slash_start, slash_count]
+          end
+        end
+        translated
+      end
+
+      def validate_schema!(schema)
+        raise InvalidFragmentError, "schema fragments must be hashes" unless schema.is_a?(Hash)
+
+        unknown = schema.keys.reject { |key| ALLOWED_KEYWORDS.include?(key) || key.start_with?("x-") }
+        raise InvalidFragmentError, "unsupported OpenAPI 3.0 keyword #{unknown.first.inspect}" unless unknown.empty?
+
+        if schema.key?("$ref") && schema.length > 1
+          raise InvalidFragmentError, "OpenAPI 3.0 does not permit siblings beside $ref"
+        end
+
+        validate_type!(schema)
+        validate_keyword_values!(schema)
+        validate_boundaries!(schema)
+        validate_nullable!(schema)
+        validate_children!(schema)
+      end
+
+      def validate_type!(schema)
+        return unless schema.key?("type")
+
+        type = schema.fetch("type")
+        return if type.is_a?(String) && TYPES.include?(type)
+
+        raise InvalidFragmentError, "type must be one OpenAPI 3.0 type string (never null or an array)"
+      end
+
+      def validate_boundaries!(schema)
+        %w[exclusiveMinimum exclusiveMaximum].each do |keyword|
+          next unless schema.key?(keyword)
+          next if [true, false].include?(schema.fetch(keyword))
+
+          raise InvalidFragmentError, "#{keyword} must be boolean in OpenAPI 3.0"
+        end
+      end
+
+      def validate_keyword_values!(schema)
+        STRING_KEYWORDS.each do |keyword|
+          next unless schema.key?(keyword)
+          next if schema.fetch(keyword).is_a?(String)
+
+          raise InvalidFragmentError, "#{keyword} must be a string"
+        end
+
+        validate_ref!(schema)
+        NUMERIC_KEYWORDS.each { |keyword| validate_numeric_keyword!(schema, keyword) }
+        validate_multiple_of!(schema)
+        SIZE_KEYWORDS.each { |keyword| validate_size_keyword!(schema, keyword) }
+        BOOLEAN_KEYWORDS.each { |keyword| validate_boolean_keyword!(schema, keyword) }
+        validate_required!(schema)
+        validate_enum!(schema)
+        validate_json_value!(schema, "default")
+        validate_json_value!(schema, "example")
+        MetadataValidator.validate!(schema) { |value| json_value?(value) }
+        schema.each do |keyword, value|
+          next unless keyword.start_with?("x-")
+          next if json_value?(value)
+
+          raise InvalidFragmentError, "#{keyword} must be an OpenAPI-compatible value"
+        end
+
+        return unless schema["readOnly"] == true && schema["writeOnly"] == true
+
+        raise InvalidFragmentError, "readOnly and writeOnly cannot both be true"
+      end
+
+      def validate_numeric_keyword!(schema, keyword)
+        return unless schema.key?(keyword)
+
+        value = schema.fetch(keyword)
+        return if finite_number?(value)
+
+        raise InvalidFragmentError, "#{keyword} must be a finite number"
+      end
+
+      def validate_ref!(schema)
+        return unless schema.key?("$ref")
+
+        URI.parse(schema.fetch("$ref"))
+      rescue URI::InvalidURIError
+        raise InvalidFragmentError, "$ref must be a valid URI reference"
+      end
+
+      def validate_multiple_of!(schema)
+        return unless schema.key?("multipleOf")
+
+        value = schema.fetch("multipleOf")
+        return if finite_number?(value) && value.positive?
+
+        raise InvalidFragmentError, "multipleOf must be a positive finite number"
+      end
+
+      def validate_size_keyword!(schema, keyword)
+        return unless schema.key?(keyword)
+
+        value = schema.fetch(keyword)
+        return if value.is_a?(Integer) && !value.negative?
+
+        raise InvalidFragmentError, "#{keyword} must be a non-negative integer"
+      end
+
+      def validate_boolean_keyword!(schema, keyword)
+        return unless schema.key?(keyword)
+        return if [true, false].include?(schema.fetch(keyword))
+
+        raise InvalidFragmentError, "#{keyword} must be boolean"
+      end
+
+      def validate_required!(schema)
+        return unless schema.key?("required")
+
+        required = schema.fetch("required")
+        return if required.is_a?(Array) && required.all?(String) && required.uniq == required
+
+        raise InvalidFragmentError, "required must contain unique property-name strings"
+      end
+
+      def validate_enum!(schema)
+        return unless schema.key?("enum")
+
+        values = schema.fetch("enum")
+        valid = values.is_a?(Array) && !values.empty? && values.uniq == values
+        valid &&= values.all? { |value| json_value?(value) }
+        return if valid
+
+        raise InvalidFragmentError, "enum must contain unique OpenAPI-compatible values"
+      end
+
+      def validate_json_value!(schema, keyword)
+        return unless schema.key?(keyword)
+        return if json_value?(schema.fetch(keyword))
+
+        raise InvalidFragmentError, "#{keyword} must be an OpenAPI-compatible value"
+      end
+
+      def json_value?(value)
+        case value
+        when nil, true, false, String, Integer
+          true
+        when Float
+          value.finite?
+        when Array
+          value.all? { |item| json_value?(item) }
+        when Hash
+          value.all? { |key, item| key.is_a?(String) && json_value?(item) }
+        else
+          false
+        end
+      end
+
+      def finite_number?(value)
+        value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)
+      end
+
+      def validate_nullable!(schema)
+        return unless schema["nullable"] == true
+        return if schema["type"].is_a?(String)
+
+        raise InvalidFragmentError,
+              "nullable requires an explicit type in the same OpenAPI 3.0 Schema Object"
+      end
+
+      def validate_children!(schema)
+        if schema.key?("properties")
+          properties = schema.fetch("properties")
+          raise InvalidFragmentError, "properties must be a hash" unless properties.is_a?(Hash)
+
+          properties.each_value { |child| validate_schema!(child) }
+        end
+
+        if schema["type"] == "array" && !schema.key?("items")
+          raise InvalidFragmentError, "array schemas must define items"
+        end
+
+        validate_schema!(schema.fetch("items")) if schema.key?("items")
+
+        SCHEMA_ARRAY_KEYWORDS.each do |keyword|
+          next unless schema.key?(keyword)
+
+          alternatives = schema.fetch(keyword)
+          unless alternatives.is_a?(Array) && !alternatives.empty?
+            raise InvalidFragmentError, "#{keyword} must be a non-empty array of schemas"
+          end
+
+          alternatives.each { |child| validate_schema!(child) }
+        end
+
+        validate_schema!(schema.fetch("not")) if schema.key?("not")
+
+        validate_additional_properties!(schema)
+      end
+
+      def validate_additional_properties!(schema)
+        return unless schema.key?("additionalProperties")
+
+        additional = schema.fetch("additionalProperties")
+        valid = additional == true || additional == false || additional.is_a?(Hash)
+        raise InvalidFragmentError, "additionalProperties must be boolean or a schema" unless valid
+
+        validate_schema!(additional) if additional.is_a?(Hash)
+      end
+
+      def order_schema(schema)
+        ordered_keys = schema.keys.sort_by do |key|
+          index = KEYWORD_ORDER.index(key)
+          [index || KEYWORD_ORDER.length, index ? "" : key]
+        end
+
+        ordered_keys.each_with_object({}) do |key, ordered|
+          value = schema.fetch(key)
+          ordered[key] = case key
+                         when "properties"
+                           value.each_with_object({}) do |(property, child), properties|
+                             properties[property] = order_schema(child)
+                           end
+                         when "items", "not"
+                           order_schema(value)
+                         when *SCHEMA_ARRAY_KEYWORDS
+                           value.map { |child| order_schema(child) }
+                         when "additionalProperties"
+                           value.is_a?(Hash) ? order_schema(value) : value
+                         else
+                           value
+                         end
+        end
+      end
+    end
+  end
+end

data/lib/liminal/errors.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Liminal
+  # Base class for all domain errors raised by the gem.
+  class Error < StandardError; end
+
+  class InvalidSchemaSourceError < Error; end
+  class UnsupportedDialectError < Error; end
+  class InvalidOverrideError < Error; end
+  class UnknownOverridePathError < Error; end
+  class UnknownExclusionPathError < Error; end
+  class PredicateAlreadyRegisteredError < Error; end
+  class ComponentCollisionError < Error; end
+  class InvalidComponentNameError < Error; end
+  class InvalidSchemaError < Error; end
+  class InvalidSchemaCompositionError < InvalidSchemaError; end
+
+  # Raised when a dry-schema AST node cannot be represented.
+  class UnsupportedNodeError < Error
+    attr_reader :source_name, :path, :operation
+
+    def initialize(source_name:, path:, operation:)
+      @source_name = source_name
+      @path = path.map { |segment| segment.to_s.dup.freeze }.freeze
+      @operation = operation
+      super("Cannot compile #{source_name} at #{Path.display(path)}: " \
+            "unsupported AST node #{operation}.")
+    end
+  end
+
+  # Raised when a dry predicate cannot be represented.
+  class UnsupportedPredicateError < Error
+    attr_reader :source_name, :path, :predicate
+
+    def initialize(source_name:, path:, predicate:, detail: nil)
+      @source_name = source_name
+      @path = path.map { |segment| segment.to_s.dup.freeze }.freeze
+      @predicate = predicate
+      detail_text = detail ? " (#{detail})" : ""
+      super(<<~MESSAGE.chomp)
+        Cannot compile #{source_name} at #{Path.display(path)}: unsupported predicate #{predicate}#{detail_text}.
+        Add an authoritative override or register a predicate handler.
+      MESSAGE
+    end
+  end
+
+  # Raised when a predicate handler returns a non-schema value.
+  class InvalidPredicateResultError < Error
+    attr_reader :source_name, :path, :predicate
+
+    def initialize(source_name:, path:, predicate:, detail:)
+      @source_name = source_name
+      @path = path.map { |segment| segment.to_s.dup.freeze }.freeze
+      @predicate = predicate
+      super("Invalid result for predicate #{predicate} while compiling " \
+            "#{source_name} at #{Path.display(path)}: #{detail}.")
+    end
+  end
+end

data/lib/liminal/internal/normalizer.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Liminal
+  module Internal
+    # Resolves private predicate constraints after type fragments have merged.
+    class Normalizer
+      CONSTRAINTS_KEY = "__liminal_constraints__"
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      class << self
+        def constraint(name, argument = UNSET)
+          entry = argument.equal?(UNSET) ? [name] : [name, argument]
+          {CONSTRAINTS_KEY => [entry.freeze]}
+        end
+
+        def normalize_keys(value, path = [])
+          case value
+          when Hash
+            original_keys = {}
+            value.each_with_object({}) do |(key, item), normalized|
+              unless key.is_a?(String) || key.is_a?(Symbol)
+                raise InvalidSchemaError,
+                      "OpenAPI object key #{key.inspect} at #{Path.display(path)} must be a String or Symbol."
+              end
+
+              normalized_key = key.to_s.dup
+              if original_keys.key?(normalized_key)
+                raise InvalidSchemaError,
+                      "OpenAPI object keys #{original_keys.fetch(normalized_key).inspect} and #{key.inspect} " \
+                      "both normalize to #{normalized_key.inspect} at #{Path.display(path)}."
+              end
+
+              original_keys[normalized_key] = key
+              normalized[normalized_key] = normalize_keys(item, path + [normalized_key])
+            end
+          when Array
+            value.map.with_index { |item, index| normalize_keys(item, path + [index]) }
+          when String
+            value.dup
+          else
+            value
+          end
+        end
+      end
+
+      def initialize(source_name:)
+        @source_name = source_name
+      end
+
+      def call(fragment, path: [])
+        normalize_schema(self.class.normalize_keys(fragment), path)
+      end
+
+      private
+
+      def normalize_schema(schema, path)
+        constraints = schema.delete(CONSTRAINTS_KEY) || []
+        schema = apply_constraints(schema, constraints, path) unless constraints.empty?
+
+        schema["items"] = {} if (schema["type"] == "array") && !schema.key?("items")
+        schema.delete("required") if schema["required"] == []
+
+        normalize_children!(schema, path)
+        normalize_values(schema, path)
+      end
+
+      def normalize_children!(schema, path)
+        if schema["properties"].is_a?(Hash)
+          schema["properties"] = schema.fetch("properties").each_with_object({}) do |(name, child), properties|
+            properties[name.to_s] = normalize_schema(child, path + [name.to_s])
+          end
+        end
+
+        schema["items"] = normalize_schema(schema.fetch("items"), path) if schema["items"].is_a?(Hash)
+
+        %w[allOf oneOf anyOf].each do |keyword|
+          next unless schema[keyword].is_a?(Array)
+
+          schema[keyword] = schema.fetch(keyword).map { |child| normalize_schema(child, path) }
+        end
+
+        schema["not"] = normalize_schema(schema.fetch("not"), path) if schema["not"].is_a?(Hash)
+        return unless schema["additionalProperties"].is_a?(Hash)
+
+        schema["additionalProperties"] = normalize_schema(schema.fetch("additionalProperties"), path)
+      end
+
+      def apply_constraints(schema, constraints, path)
+        types = resolved_types(schema)
+        if types.length > 1 && schema["anyOf"].is_a?(Array)
+          marker = {CONSTRAINTS_KEY => constraints}
+          schema["anyOf"] = schema.fetch("anyOf").map do |alternative|
+            normalize_schema(SchemaMerge.combine(alternative, marker), path)
+          end
+          return schema
+        end
+
+        type = types.first
+        unsupported!(constraints.first.first, path, "the field type could not be resolved") unless type
+
+        apply_size_constraints(schema, constraints, type, path)
+      end
+
+      def apply_size_constraints(schema, constraints, type, path)
+        discrete_sizes = nil
+
+        constraints.each do |name, argument|
+          case name
+          when :filled?
+            apply_filled!(schema, type, path)
+          when :min_size?
+            apply_minimum_size!(schema, type, validate_size!(name, argument, path), path)
+          when :max_size?
+            apply_maximum_size!(schema, type, validate_size!(name, argument, path), path)
+          when :size?
+            discrete_sizes = apply_size!(schema, type, argument, path, discrete_sizes)
+          end
+        end
+
+        return apply_discrete_sizes(schema, type, discrete_sizes, path) if discrete_sizes
+
+        schema
+      end
+
+      def apply_filled!(schema, type, path)
+        return if %w[boolean integer number].include?(type)
+
+        minimum, = size_keywords(type, :filled?, path)
+        schema[minimum] = [schema[minimum], 1].compact.max
+      end
+
+      def apply_minimum_size!(schema, type, value, path)
+        minimum, = size_keywords(type, :min_size?, path)
+        schema[minimum] = [schema[minimum], value].compact.max
+      end
+
+      def apply_maximum_size!(schema, type, value, path)
+        _, maximum = size_keywords(type, :max_size?, path)
+        schema[maximum] = [schema[maximum], value].compact.min
+      end
+
+      def apply_size!(schema, type, argument, path, prior_discrete)
+        case argument
+        when Integer
+          value = validate_size!(:size?, argument, path)
+          set_exact_size!(schema, type, value, path)
+          prior_discrete
+        when Range
+          apply_size_range!(schema, type, argument, path)
+          prior_discrete
+        when Array
+          values = argument.map { |value| validate_size!(:size?, value, path) }.uniq.sort
+          prior_discrete ? prior_discrete & values : values
+        else
+          unsupported!(:size?, path, "unsupported size argument #{argument.inspect}")
+        end
+      end
+
+      def apply_size_range!(schema, type, range, path)
+        first = validate_size!(:size?, range.begin, path)
+        last = validate_size!(:size?, range.end, path)
+        last -= 1 if range.exclude_end?
+        unsupported!(:size?, path, "the exclusive range has no non-negative endpoint") if last.negative?
+
+        apply_minimum_size!(schema, type, first, path)
+        apply_maximum_size!(schema, type, last, path)
+      end
+
+      def set_exact_size!(schema, type, value, path)
+        minimum, maximum = size_keywords(type, :size?, path)
+        schema[minimum] = value
+        schema[maximum] = value
+      end
+
+      def apply_discrete_sizes(schema, type, values, path)
+        minimum, maximum = size_keywords(type, :size?, path)
+        values = values.select do |value|
+          (!schema[minimum] || value >= schema[minimum]) && (!schema[maximum] || value <= schema[maximum])
+        end
+
+        discrete = if values.empty?
+                     {"not" => {}}
+                   else
+                     {"anyOf" => values.map { |value| {minimum => value, maximum => value} }}
+                   end
+        SchemaMerge.combine(schema, discrete)
+      end
+
+      def validate_size!(predicate, value, path)
+        return value if value.is_a?(Integer) && !value.negative?
+
+        unsupported!(predicate, path, "size values must be non-negative integers")
+      end
+
+      def size_keywords(type, predicate, path)
+        case type
+        when "string" then %w[minLength maxLength]
+        when "array" then %w[minItems maxItems]
+        when "object" then %w[minProperties maxProperties]
+        else unsupported!(predicate, path, "size constraints do not apply to #{type}")
+        end
+      end
+
+      def resolved_types(schema)
+        return [schema.fetch("type")] if schema.key?("type")
+
+        %w[allOf anyOf oneOf].each do |keyword|
+          next unless schema[keyword].is_a?(Array)
+
+          types = schema.fetch(keyword).flat_map { |child| resolved_types(child) }.uniq
+          return types unless types.empty?
+        end
+        []
+      end
+
+      def normalize_values(value, path)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), normalized|
+            normalized[key.to_s] = normalize_values(item, path + [key.to_s])
+          end
+        when Array
+          value.map.with_index { |item, index| normalize_values(item, path + [index]) }
+        when Symbol
+          value.to_s
+        when Date, Time
+          value.iso8601
+        else
+          value
+        end
+      end
+
+      def unsupported!(predicate, path, detail)
+        raise UnsupportedPredicateError.new(
+          source_name: @source_name,
+          path: path,
+          predicate: predicate,
+          detail: detail
+        )
+      end
+    end
+  end
+end