liminal 0.1.0

data/lib/liminal/compiler.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Liminal
+  # Coordinates AST adaptation, predicate compilation, overrides, and dialect
+  # validation. Raw dry-schema AST layout is intentionally absent here.
+  class Compiler
+    NULL_FRAGMENT = Object.new.freeze
+    AUTHORITATIVE_KEYS = %w[type $ref oneOf anyOf allOf].freeze
+    OVERRIDABLE_ERRORS = [UnsupportedNodeError, UnsupportedPredicateError].freeze
+    private_constant :NULL_FRAGMENT, :AUTHORITATIVE_KEYS, :OVERRIDABLE_ERRORS
+
+    def initialize(schema, dialect:, source_name:, exclude:, overrides:, predicates:)
+      @schema = schema
+      @source_name = source_name || infer_source_name(schema)
+      @dialect = build_dialect(dialect)
+      @excluded_paths = normalize_exclusions(exclude)
+      @overrides = normalize_overrides(overrides)
+      @predicates = predicates
+      validate_predicates!
+      validate_path_configuration!
+      @adapter = Adapters::DrySchemaV1.new
+      @normalizer = Internal::Normalizer.new(source_name: @source_name)
+    end
+
+    def call
+      validate_source!
+      root = @adapter.call(@schema.to_ast)
+      @known_paths = collect_paths(root)
+
+      compiled = compile_node(root, [])
+      check_unknown_paths!
+      normalized = @normalizer.call(compiled)
+      @dialect.validate!(normalized)
+      @dialect.order(normalized)
+    rescue Dialects::OpenAPI30::InvalidFragmentError => e
+      raise Error, "Compiler produced an invalid OpenAPI 3.0 schema for #{@source_name}: #{e.message}"
+    end
+
+    private
+
+    def validate_source!
+      return if @schema.respond_to?(:to_ast)
+
+      raise InvalidSchemaSourceError,
+            "Schema source #{@source_name} must respond to to_ast."
+    end
+
+    def infer_source_name(schema)
+      name = schema.class.name if schema
+      name && !name.empty? ? name : "anonymous schema"
+    end
+
+    def build_dialect(name)
+      return Dialects::OpenAPI30.new.freeze if name == :openapi_3_0
+
+      raise UnsupportedDialectError,
+            "Unsupported dialect #{name.inspect}; only :openapi_3_0 is available."
+    end
+
+    def validate_predicates!
+      return if @predicates.respond_to?(:entry)
+
+      raise ArgumentError, "predicates must respond to entry."
+    end
+
+    def validate_path_configuration!
+      conflict = @excluded_paths.to_a.product(@overrides.keys).find do |excluded, overridden|
+        path_prefix?(excluded, overridden)
+      end
+      return unless conflict
+
+      excluded, overridden = conflict
+      raise InvalidOverrideError,
+            "Override at #{Path.display(overridden)} conflicts with exclusion at #{Path.display(excluded)}."
+    end
+
+    def path_prefix?(prefix, path)
+      path.first(prefix.length) == prefix
+    end
+
+    def normalize_exclusions(exclusions)
+      Array(exclusions).each_with_object(Set.new) do |path, paths|
+        paths << Path.normalize(path)
+      rescue ArgumentError => e
+        raise UnknownExclusionPathError, "Invalid exclusion path #{path.inspect}: #{e.message}."
+      end.freeze
+    end
+
+    def normalize_overrides(overrides)
+      raise InvalidOverrideError, "overrides must be a hash keyed by property paths." unless overrides.is_a?(Hash)
+
+      overrides.each_with_object({}) do |(path, fragment), normalized|
+        canonical = begin
+          Path.normalize(path)
+        rescue ArgumentError => e
+          raise InvalidOverrideError, "Invalid override path #{path.inspect}: #{e.message}."
+        end
+        unless fragment.is_a?(Hash)
+          raise InvalidOverrideError,
+                "Override at #{Path.display(canonical)} must be an OpenAPI fragment hash."
+        end
+
+        value = begin
+          Internal::Normalizer.normalize_keys(fragment)
+        rescue InvalidSchemaError => e
+          raise InvalidOverrideError,
+                "Invalid override at #{Path.display(canonical)}: #{e.message}."
+        end
+        if normalized.key?(canonical) && normalized.fetch(canonical) != value
+          raise InvalidOverrideError, "Conflicting overrides normalize to #{canonical.inspect}."
+        end
+
+        normalized[canonical] = value
+      end.freeze
+    end
+
+    def collect_paths(root)
+      paths = Set.new
+      walk_paths(root, [], paths)
+      paths.freeze
+    end
+
+    def walk_paths(node, path, paths)
+      case node
+      when Adapters::DrySchemaV1::FieldNode
+        field_path = (path + [node.name]).freeze
+        paths << field_path
+        walk_paths(node.rule, field_path, paths)
+      when Adapters::DrySchemaV1::SetNode, Adapters::DrySchemaV1::AndNode,
+           Adapters::DrySchemaV1::OrNode
+        node.children.each { |child| walk_paths(child, path, paths) }
+      when Adapters::DrySchemaV1::NullableNode, Adapters::DrySchemaV1::NotNode,
+           Adapters::DrySchemaV1::EachNode
+        walk_paths(node.rule, path, paths)
+      when Adapters::DrySchemaV1::ImplicationNode
+        walk_paths(node.left, path, paths)
+        walk_paths(node.right, path, paths)
+      when Adapters::DrySchemaV1::KeyNode
+        walk_paths(node.rule, path + [node.name], paths)
+      end
+    end
+
+    def compile_node(node, path)
+      case node
+      when Adapters::DrySchemaV1::SetNode then compile_set(node, path)
+      when Adapters::DrySchemaV1::FieldNode then compile_field(node, path)
+      when Adapters::DrySchemaV1::PredicateNode then compile_predicate(node, path)
+      when Adapters::DrySchemaV1::AndNode then compile_and(node, path)
+      when Adapters::DrySchemaV1::OrNode then compile_or(node, path)
+      when Adapters::DrySchemaV1::NullableNode then compile_nullable(node, path)
+      when Adapters::DrySchemaV1::EachNode then compile_each(node, path)
+      when Adapters::DrySchemaV1::ImplicationNode then unsupported_node!(:implication, path)
+      when Adapters::DrySchemaV1::NotNode then unsupported_node!(:not, path)
+      when Adapters::DrySchemaV1::KeyNode then unsupported_node!(:key, path)
+      when Adapters::DrySchemaV1::UnknownNode then unsupported_node!(node.operation, path)
+      else unsupported_node!(:invalid_ast, path)
+      end
+    end
+
+    def compile_set(node, path)
+      properties = {}
+      required = []
+      additional_fragments = []
+
+      node.children.each do |child|
+        unless child.is_a?(Adapters::DrySchemaV1::FieldNode)
+          additional_fragments << compile_node(child, path)
+          next
+        end
+
+        field_path = path + [child.name]
+        next if @excluded_paths.include?(field_path)
+
+        fragment = compile_field(child, path)
+        properties[child.name] = if properties.key?(child.name)
+                                   Internal::SchemaMerge.combine(properties.fetch(child.name), fragment)
+                                 else
+                                   fragment
+                                 end
+        required << child.name if child.required && !required.include?(child.name)
+      end
+
+      result = {"type" => "object", "properties" => properties}
+      result["required"] = required unless required.empty?
+      additional_fragments.reduce(result) do |combined, fragment|
+        Internal::SchemaMerge.combine(combined, fragment)
+      end
+    end
+
+    def compile_field(node, parent_path)
+      path = parent_path + [node.name]
+      override = @overrides[path]
+
+      fragment = begin
+        compile_node(node.rule, path)
+      rescue *OVERRIDABLE_ERRORS => e
+        raise unless override && authoritative?(override) && e.path == path
+
+        validate_override!(override, path)
+        override
+      end
+
+      unsupported_predicate!(:nil?, path, "a null-only schema is not valid in OpenAPI 3.0") if null_fragment?(fragment)
+
+      if override && fragment != override
+        validate_override!(override, path)
+        fragment = Internal::SchemaMerge.override(fragment, override)
+      end
+
+      normalize_and_validate_field(fragment, path, overridden: !override.nil?)
+    end
+
+    def normalize_and_validate_field(fragment, path, overridden:)
+      normalized = @normalizer.call(fragment, path: path)
+      @dialect.validate!(normalized)
+      normalized
+    rescue Dialects::OpenAPI30::InvalidFragmentError => e
+      if overridden
+        raise InvalidOverrideError,
+              "Invalid override at #{Path.display(path)}: #{e.message}."
+      end
+
+      raise Error,
+            "Generated invalid OpenAPI schema at #{Path.display(path)}: #{e.message}."
+    end
+
+    def validate_override!(fragment, path)
+      @dialect.validate!(fragment)
+    rescue Dialects::OpenAPI30::InvalidFragmentError => e
+      raise InvalidOverrideError,
+            "Invalid override at #{Path.display(path)}: #{e.message}."
+    end
+
+    def authoritative?(fragment)
+      fragment.keys.intersect?(AUTHORITATIVE_KEYS)
+    end
+
+    def compile_predicate(node, path)
+      return compile_nil(node, path) if node.name == :nil?
+      return unsupported_predicate!(node.name, path) if node.name == :key?
+
+      entry = @predicates.entry(node.name)
+      return unsupported_predicate!(node.name, path) unless entry
+
+      context = PredicateContext.new(path: path, dialect: @dialect)
+      result = begin
+        entry.handler.call(node.arguments, context)
+      rescue PredicateRegistry::UnsupportedValue => e
+        unsupported_predicate!(node.name, path, e.message)
+      end
+
+      unless result.is_a?(Hash)
+        raise InvalidPredicateResultError.new(
+          source_name: @source_name,
+          path: path,
+          predicate: node.name,
+          detail: "handler returned #{result.class}, expected Hash"
+        )
+      end
+
+      fragment = Internal::Normalizer.normalize_keys(result)
+      validate_predicate_fragment!(fragment, node, path) unless entry.internal
+      fragment
+    rescue InvalidSchemaError => e
+      raise InvalidPredicateResultError.new(
+        source_name: @source_name,
+        path: path,
+        predicate: node.name,
+        detail: e.message
+      )
+    end
+
+    def validate_predicate_fragment!(fragment, node, path)
+      @dialect.validate!(fragment)
+    rescue Dialects::OpenAPI30::InvalidFragmentError => e
+      raise InvalidPredicateResultError.new(
+        source_name: @source_name,
+        path: path,
+        predicate: node.name,
+        detail: e.message
+      )
+    end
+
+    def compile_nil(node, path)
+      return unsupported_predicate!(:nil?, path, "nil? does not accept semantic arguments") unless node.arguments.empty?
+
+      NULL_FRAGMENT
+    end
+
+    def compile_and(node, path)
+      fragments = node.children.map { |child| compile_node(child, path) }
+      nulls, schemas = fragments.partition { |fragment| null_fragment?(fragment) }
+      if schemas.empty? && nulls.any?
+        unsupported_predicate!(:nil?, path,
+                               "a null-only schema is not valid in OpenAPI 3.0")
+      end
+      return {"not" => {}} if nulls.any?
+
+      schemas.reduce({}) { |combined, fragment| Internal::SchemaMerge.combine(combined, fragment) }
+    end
+
+    def compile_or(node, path)
+      alternatives = node.children.flat_map do |child|
+        fragment = compile_node(child, path)
+        next [fragment] if null_fragment?(fragment)
+
+        fragment.keys == ["anyOf"] ? fragment.fetch("anyOf") : [fragment]
+      end
+      alternatives = alternatives.each_with_object([]) { |item, list| list << item unless list.include?(item) }
+      null_present = alternatives.any? { |fragment| null_fragment?(fragment) }
+      alternatives.reject! { |fragment| null_fragment?(fragment) }
+
+      unsupported_predicate!(:nil?, path, "a null-only schema is not valid in OpenAPI 3.0") if alternatives.empty?
+
+      alternatives = alternatives.map { |fragment| @dialect.nullable(fragment) } if null_present
+
+      alternatives.length == 1 ? alternatives.first : {"anyOf" => alternatives}
+    rescue Dialects::OpenAPI30::InvalidFragmentError => e
+      unsupported_predicate!(:nil?, path, e.message)
+    end
+
+    def compile_nullable(node, path)
+      fragment = compile_node(node.rule, path)
+      unsupported_predicate!(:nil?, path, "a null-only schema is not valid in OpenAPI 3.0") if null_fragment?(fragment)
+
+      @dialect.nullable(fragment)
+    rescue Dialects::OpenAPI30::InvalidFragmentError => e
+      unsupported_predicate!(:nil?, path, e.message)
+    end
+
+    def compile_each(node, path)
+      item_schema = compile_node(node.rule, path)
+      if null_fragment?(item_schema)
+        unsupported_predicate!(:nil?, path, "null-only array items are not valid in OpenAPI 3.0")
+      end
+
+      {"type" => "array", "items" => item_schema}
+    end
+
+    def null_fragment?(fragment)
+      fragment.equal?(NULL_FRAGMENT)
+    end
+
+    def unsupported_node!(operation, path)
+      raise UnsupportedNodeError.new(source_name: @source_name, path: path, operation: operation)
+    end
+
+    def unsupported_predicate!(predicate, path, detail = nil)
+      raise UnsupportedPredicateError.new(
+        source_name: @source_name,
+        path: path,
+        predicate: predicate,
+        detail: detail
+      )
+    end
+
+    def check_unknown_paths!
+      unknown_exclusions = @excluded_paths.reject { |path| @known_paths.include?(path) }
+      unless unknown_exclusions.empty?
+        raise UnknownExclusionPathError,
+              "Unknown exclusion path #{unknown_exclusions.first.inspect}."
+      end
+
+      unknown_overrides = @overrides.keys.reject { |path| @known_paths.include?(path) }
+      return if unknown_overrides.empty?
+
+      raise UnknownOverridePathError,
+            "Unknown override path #{unknown_overrides.first.inspect}."
+    end
+  end
+end

data/lib/liminal/components.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Liminal
+  # Generic OpenAPI component registration with normalized collision checks.
+  module Components
+    NAME_PATTERN = /\A[A-Za-z0-9._-]+\z/
+    private_constant :NAME_PATTERN
+
+    module_function
+
+    # Register +schema+ under +name+ and return its local component reference.
+    #
+    # @param document [Hash] mutable OpenAPI document
+    # @param name [String, Symbol] logical component name
+    # @param schema [Hash] Schema Object to register
+    # @return [Hash] a string-keyed local +$ref+
+    def register(document:, name:, schema:)
+      raise ArgumentError, "document must be a Hash" unless document.is_a?(Hash)
+      raise ArgumentError, "schema must be a Hash" unless schema.is_a?(Hash)
+
+      logical_name = normalize_name(name)
+      normalized_schema = Schema.normalize(schema)
+      schemas = schema_map(document)
+      existing_keys = logical_keys(schemas, logical_name)
+      if existing_keys.length > 1
+        raise ComponentCollisionError,
+              "Component #{logical_name.inspect} is registered under both String and Symbol keys."
+      end
+
+      if existing_keys.one?
+        existing = Schema.normalize(schemas.fetch(existing_keys.first))
+        unless existing == normalized_schema
+          raise ComponentCollisionError,
+                "Component #{logical_name.inspect} is already registered with a different schema."
+        end
+      else
+        schemas[logical_name] = normalized_schema
+      end
+
+      reference(logical_name)
+    end
+
+    def reference(name)
+      logical_name = normalize_name(name)
+      {"$ref" => "#/components/schemas/#{logical_name}".freeze}.freeze
+    end
+
+    # Return the canonical, immutable OpenAPI component key for +name+.
+    def normalize_name(name)
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise InvalidComponentNameError,
+              "Component name must be a String or Symbol; received #{name.class}."
+      end
+
+      logical_name = name.to_s.dup.freeze
+      return logical_name if NAME_PATTERN.match?(logical_name)
+
+      expectation = "one or more letters, digits, periods, hyphens, or underscores"
+      raise InvalidComponentNameError,
+            "Invalid component name #{logical_name.inspect}; expected #{expectation}."
+    end
+
+    def schema_map(document)
+      components = logical_map(document, "components")
+      logical_map(components, "schemas")
+    end
+    private_class_method :schema_map
+
+    def logical_map(container, name)
+      keys = logical_keys(container, name)
+      raise ArgumentError, "#{name} cannot be present under both String and Symbol keys" if keys.length > 1
+
+      if keys.empty?
+        container[name] = {}
+        return container.fetch(name)
+      end
+
+      value = container.fetch(keys.first)
+      raise ArgumentError, "#{name} must be a Hash" unless value.is_a?(Hash)
+
+      value
+    end
+    private_class_method :logical_map
+
+    def logical_keys(container, name)
+      [name, name.to_sym].select { |key| container.key?(key) }
+    end
+    private_class_method :logical_keys
+  end
+end

data/lib/liminal/dialects/openapi_30/metadata_validator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Dialects
+    class OpenAPI30
+      # Validates the fixed-field objects embedded in an OpenAPI 3.0 Schema
+      # Object. Keeping these shapes here leaves the dialect focused on schema
+      # keywords and recursive child schemas.
+      module MetadataValidator
+        module_function
+
+        def validate!(schema, &)
+          validate_discriminator!(schema, &)
+          validate_xml!(schema, &)
+          validate_external_docs!(schema, &)
+        end
+
+        def validate_discriminator!(schema, &)
+          return unless schema.key?("discriminator")
+
+          discriminator = fixed_object!(
+            schema.fetch("discriminator"),
+            "discriminator",
+            %w[propertyName mapping],
+            &
+          )
+          property_name = discriminator["propertyName"]
+          unless property_name.is_a?(String) && !property_name.empty?
+            raise InvalidFragmentError, "discriminator.propertyName must be a non-empty string"
+          end
+          return unless discriminator.key?("mapping")
+
+          mapping = discriminator.fetch("mapping")
+          valid = mapping.is_a?(Hash) &&
+                  mapping.all? { |key, value| key.is_a?(String) && value.is_a?(String) }
+          raise InvalidFragmentError, "discriminator.mapping must map strings to strings" unless valid
+        end
+        private_class_method :validate_discriminator!
+
+        def validate_xml!(schema, &)
+          return unless schema.key?("xml")
+
+          xml = fixed_object!(
+            schema.fetch("xml"),
+            "xml",
+            %w[name namespace prefix attribute wrapped],
+            &
+          )
+          validate_fields!(xml, %w[name prefix], String, "a string", "xml")
+          validate_fields!(xml, %w[attribute wrapped], [TrueClass, FalseClass], "boolean", "xml")
+          return unless xml.key?("namespace")
+
+          namespace = xml.fetch("namespace")
+          return if namespace.is_a?(String) && absolute_uri?(namespace)
+
+          raise InvalidFragmentError, "xml.namespace must be an absolute URI string"
+        end
+        private_class_method :validate_xml!
+
+        def validate_external_docs!(schema, &)
+          return unless schema.key?("externalDocs")
+
+          external_docs = fixed_object!(
+            schema.fetch("externalDocs"),
+            "externalDocs",
+            %w[description url],
+            &
+          )
+          url = external_docs["url"]
+          unless url.is_a?(String) && !url.empty? && uri_reference?(url)
+            raise InvalidFragmentError, "externalDocs.url must be a valid URI-reference string"
+          end
+
+          validate_fields!(external_docs, ["description"], String, "a string", "externalDocs")
+        end
+        private_class_method :validate_external_docs!
+
+        def fixed_object!(value, keyword, fields)
+          raise InvalidFragmentError, "#{keyword} must be an OpenAPI-compatible object" unless value.is_a?(Hash)
+
+          unknown = value.keys.reject { |key| fields.include?(key) || key.start_with?("x-") }
+          unless unknown.empty?
+            raise InvalidFragmentError, "#{keyword} contains unsupported field #{unknown.first.inspect}"
+          end
+
+          value.each do |key, extension|
+            next unless key.start_with?("x-")
+            next if yield(extension)
+
+            raise InvalidFragmentError, "#{keyword}.#{key} must be an OpenAPI-compatible value"
+          end
+          value
+        end
+        private_class_method :fixed_object!
+
+        def validate_fields!(object, fields, expected_classes, expectation, object_name)
+          fields.each do |field|
+            next unless object.key?(field)
+            next if Array(expected_classes).any? { |type| object.fetch(field).is_a?(type) }
+
+            raise InvalidFragmentError, "#{object_name}.#{field} must be #{expectation}"
+          end
+        end
+        private_class_method :validate_fields!
+
+        def absolute_uri?(value)
+          URI.parse(value).absolute?
+        rescue URI::InvalidURIError
+          false
+        end
+        private_class_method :absolute_uri?
+
+        def uri_reference?(value)
+          URI.parse(value)
+          true
+        rescue URI::InvalidURIError
+          false
+        end
+        private_class_method :uri_reference?
+      end
+    end
+  end
+end