liminal 0.1.0

data/lib/liminal/internal/schema_merge.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Internal
+    # Deterministic schema-aware merge operations.
+    module SchemaMerge
+      module_function
+
+      # Combine two conjunctive schema fragments without weakening either one.
+      def combine(left, right)
+        left = deep_copy(left)
+        right = deep_copy(right)
+        return right if left.empty?
+        return left if right.empty?
+        return left if left == right
+
+        merged = left.dup
+
+        right.each do |key, right_value|
+          unless merged.key?(key)
+            merged[key] = right_value
+            next
+          end
+
+          left_value = merged[key]
+          merged_value = combine_value(key, left_value, right_value)
+          return all_of(left, right) if merged_value.equal?(CONFLICT)
+
+          merged[key] = merged_value
+        end
+
+        merged
+      end
+
+      # Apply an enrichment override. Override values win except that required
+      # arrays are unioned and nested hashes are recursively merged.
+      def override(generated, supplied)
+        result = generated.each_with_object({}) do |(key, value), copy|
+          copy[key] = deep_copy(value)
+        end
+
+        supplied.each do |key, value|
+          result[key] = if key == "required" && result[key].is_a?(Array) && value.is_a?(Array)
+                          ordered_union(result[key], value)
+                        elsif result[key].is_a?(Hash) && value.is_a?(Hash)
+                          override(result[key], value)
+                        else
+                          deep_copy(value)
+                        end
+        end
+
+        result
+      end
+
+      def deep_copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, item), copy| copy[key] = deep_copy(item) }
+        when Array
+          value.map { |item| deep_copy(item) }
+        else
+          value
+        end
+      end
+
+      def ordered_union(left, right)
+        (left + right).each_with_object([]) do |value, values|
+          values << value unless values.include?(value)
+        end
+      end
+
+      def combine_value(key, left, right)
+        return left if left == right
+        return combine(left, right) if left.is_a?(Hash) && right.is_a?(Hash)
+        return ordered_union(left, right) if key == "required" && left.is_a?(Array) && right.is_a?(Array)
+        return left + right if key == Normalizer::CONSTRAINTS_KEY && left.is_a?(Array) && right.is_a?(Array)
+
+        CONFLICT
+      end
+      private_class_method :combine_value
+
+      def all_of(left, right)
+        alternatives = [left, right].flat_map do |fragment|
+          fragment.keys == ["allOf"] ? fragment.fetch("allOf") : [fragment]
+        end
+
+        {"allOf" => alternatives.each_with_object([]) { |item, list| list << item unless list.include?(item) }}
+      end
+      private_class_method :all_of
+
+      CONFLICT = Object.new.freeze
+      private_constant :CONFLICT
+    end
+  end
+end

data/lib/liminal/path.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Liminal
+  # Utilities for canonical property paths.
+  module Path
+    module_function
+
+    # Convert an array path, dotted convenience string, or single segment to
+    # a frozen array of strings.
+    def normalize(path)
+      segments = case path
+                 when Array then path
+                 when String then path.split(".", -1)
+                 when Symbol then [path]
+                 else
+                   raise ArgumentError, "path must be an Array, String, or Symbol"
+                 end
+
+      raise ArgumentError, "path cannot be empty" if segments.empty?
+
+      segments.map do |segment|
+        unless segment.is_a?(String) || segment.is_a?(Symbol)
+          raise ArgumentError, "path segments must be strings or symbols"
+        end
+
+        segment.to_s.dup.freeze
+      end.freeze
+    end
+
+    # Render a path for diagnostics. Arrays remain the canonical API form.
+    def display(path)
+      path.empty? ? "<root>" : path.join(".")
+    end
+  end
+end

data/lib/liminal/predicate_registry.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "set"
+
+module Liminal
+  # Context supplied to custom predicate handlers.
+  PredicateContext = Struct.new(:path, :dialect, keyword_init: true) do
+    def initialize(path:, dialect:)
+      immutable_path = path.map { |segment| segment.to_s.dup.freeze }.freeze
+      super(path: immutable_path, dialect: dialect)
+      freeze
+    end
+  end
+
+  # Immutable registry of declarative dry predicate handlers.
+  class PredicateRegistry
+    Entry = Struct.new(:handler, :internal, keyword_init: true)
+    class UnsupportedValue < StandardError; end
+
+    class << self
+      # Return the immutable registry containing all built-in predicates.
+      #
+      # @return [PredicateRegistry]
+      def default
+        @default ||= build_default.freeze
+      end
+
+      private
+
+      def build_default
+        registry = new
+        primitive_fragments.each do |name, fragment|
+          registry = registry.send(:register_internal, name) do |arguments, _context|
+            no_arguments!(name, arguments, fragment)
+          end
+        end
+
+        registry = add_type_handler(registry)
+        registry = add_value_handlers(registry)
+        add_size_and_numeric_handlers(registry)
+      end
+
+      def primitive_fragments
+        {
+          array?: {"type" => "array", "items" => {}},
+          bool?: {"type" => "boolean"},
+          date?: {"type" => "string", "format" => "date"},
+          date_time?: {"type" => "string", "format" => "date-time"},
+          decimal?: {"type" => "number"},
+          float?: {"type" => "number"},
+          number?: {"type" => "number"},
+          hash?: {"type" => "object"},
+          int?: {"type" => "integer"},
+          str?: {"type" => "string"},
+          time?: {"type" => "string", "format" => "time"},
+          true?: {"type" => "boolean", "enum" => [true]},
+          false?: {"type" => "boolean", "enum" => [false]}
+        }.freeze
+      end
+
+      def add_type_handler(registry)
+        registry.send(:register_internal, :type?) do |arguments, _context|
+          type = one_argument!(:type?, arguments)
+          fragment = type_fragments[type]
+          raise UnsupportedValue, "unsupported Ruby class #{type}" unless fragment
+
+          fragment
+        end
+      end
+
+      def type_fragments
+        {
+          Array => {"type" => "array", "items" => {}},
+          BigDecimal => {"type" => "number"},
+          Date => {"type" => "string", "format" => "date"},
+          DateTime => {"type" => "string", "format" => "date-time"},
+          Float => {"type" => "number"},
+          Hash => {"type" => "object"},
+          Integer => {"type" => "integer"},
+          Numeric => {"type" => "number"},
+          String => {"type" => "string"},
+          Time => {"type" => "string", "format" => "time"},
+          TrueClass => {"type" => "boolean", "enum" => [true]},
+          FalseClass => {"type" => "boolean", "enum" => [false]}
+        }.freeze
+      end
+
+      def add_value_handlers(registry)
+        registry = registry.send(:register_internal, :eql?) do |arguments, _context|
+          value = one_argument!(:eql?, arguments)
+          ensure_openapi_value!(:eql?, value)
+          {"enum" => [value]}
+        end
+        registry = registry.send(:register_internal, :included_in?) do |arguments, _context|
+          values = one_argument!(:included_in?, arguments)
+          values = values.to_a if values.is_a?(Set)
+          raise UnsupportedValue, "included_in? requires a finite array or set" unless values.is_a?(Array)
+          raise UnsupportedValue, "included_in? requires at least one value" if values.empty?
+
+          values.each { |value| ensure_openapi_value!(:included_in?, value) }
+
+          {"enum" => values.uniq}
+        end
+        registry.send(:register_internal, :format?) do |arguments, context|
+          regexp = one_argument!(:format?, arguments)
+          begin
+            {"pattern" => context.dialect.pattern(regexp)}
+          rescue Dialects::OpenAPI30::UnsupportedPatternError => e
+            raise UnsupportedValue, e.message
+          end
+        end
+      end
+
+      def add_size_and_numeric_handlers(registry)
+        registry = registry.send(:register_internal, :filled?) do |arguments, _context|
+          no_arguments!(:filled?, arguments, Internal::Normalizer.constraint(:filled?))
+        end
+
+        %i[min_size? max_size? size?].each do |name|
+          registry = registry.send(:register_internal, name) do |arguments, _context|
+            Internal::Normalizer.constraint(name, one_argument!(name, arguments))
+          end
+        end
+
+        {
+          gt?: ->(value) { {"minimum" => value, "exclusiveMinimum" => true} },
+          gteq?: ->(value) { {"minimum" => value} },
+          lt?: ->(value) { {"maximum" => value, "exclusiveMaximum" => true} },
+          lteq?: ->(value) { {"maximum" => value} }
+        }.each do |name, builder|
+          registry = registry.send(:register_internal, name) do |arguments, _context|
+            value = one_argument!(name, arguments)
+            raise UnsupportedValue, "#{name} requires a finite numeric argument" unless json_number?(value)
+
+            builder.call(value)
+          end
+        end
+
+        registry = registry.send(:register_internal, :even?) do |arguments, _context|
+          no_arguments!(:even?, arguments, {"type" => "integer", "multipleOf" => 2})
+        end
+        registry.send(:register_internal, :odd?) do |arguments, _context|
+          no_arguments!(:odd?, arguments, {"type" => "integer", "not" => {"multipleOf" => 2}})
+        end
+      end
+
+      def one_argument!(name, arguments)
+        return arguments.first if arguments.length == 1
+
+        raise UnsupportedValue, "#{name} requires exactly one semantic argument"
+      end
+
+      def no_arguments!(name, arguments, result)
+        return result if arguments.empty?
+
+        raise UnsupportedValue, "#{name} does not accept semantic arguments"
+      end
+
+      def ensure_openapi_value!(name, value)
+        return if openapi_value?(value)
+
+        raise UnsupportedValue, "#{name} value #{value.inspect} is not OpenAPI-compatible"
+      end
+
+      def openapi_value?(value)
+        case value
+        when nil, true, false, String, Symbol, Integer, Date, Time
+          true
+        when Numeric
+          json_number?(value)
+        when Array
+          value.all? { |item| openapi_value?(item) }
+        when Hash
+          keys = value.keys
+          keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) } &&
+            keys.map(&:to_s).uniq.length == keys.length && value.values.all? { |item| openapi_value?(item) }
+        else
+          false
+        end
+      end
+
+      def json_number?(value)
+        supported = value.is_a?(Integer) || value.is_a?(Float)
+        supported && (!value.respond_to?(:finite?) || value.finite?)
+      end
+    end
+
+    def initialize(entries = {})
+      @entries = entries.freeze
+      freeze
+    end
+
+    # Return a new registry containing +name+ without mutating this registry.
+    #
+    # @param name [String, Symbol] dry predicate name
+    # @param replace [Boolean] explicitly replace an existing registration
+    # @yieldparam arguments [Array] semantic arguments without input placeholders
+    # @yieldparam context [PredicateContext] canonical path and active dialect
+    # @yieldreturn [Hash] OpenAPI Schema Object fragment
+    # @return [PredicateRegistry]
+    def with(name, replace: false, &handler)
+      raise ArgumentError, "a predicate handler block is required" unless handler
+
+      add(name, handler, replace: replace, internal: false)
+    end
+
+    # Look up a predicate entry. Intended for compiler adapters.
+    #
+    # @param name [String, Symbol]
+    # @return [Entry, nil]
+    def entry(name)
+      @entries[name.to_sym]
+    end
+
+    protected
+
+    def register_internal(name, &handler)
+      add(name, handler, replace: false, internal: true)
+    end
+
+    private
+
+    def add(name, handler, replace:, internal:)
+      predicate = name.to_sym
+      if @entries.key?(predicate) && !replace
+        raise PredicateAlreadyRegisteredError,
+              "Predicate #{predicate} is already registered; pass replace: true to replace it."
+      end
+
+      self.class.new(@entries.merge(predicate => Entry.new(handler: handler, internal: internal).freeze))
+    end
+  end
+end

data/lib/liminal/schema.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Liminal
+  # Validation, normalization, and non-mutating composition for OpenAPI Schema
+  # Objects.
+  module Schema
+    module_function
+
+    def normalize(schema, dialect: :openapi_3_0)
+      unless schema.is_a?(Hash)
+        raise InvalidSchemaError,
+              "Schema Object must be a Hash; received #{schema.class}."
+      end
+
+      validator = build_dialect(dialect)
+      normalized = Internal::Normalizer.normalize_keys(schema)
+      validator.validate!(normalized)
+      validator.order(normalized)
+    rescue Dialects::OpenAPI30::InvalidFragmentError => e
+      raise InvalidSchemaError, "Invalid OpenAPI 3.0 Schema Object: #{e.message}."
+    end
+
+    def required(schema, *names)
+      result = normalize_composition_input(schema)
+      normalized_names = normalize_names(names, minimum: 1)
+      constraint = {"required" => normalized_names}
+
+      if result.key?("$ref")
+        all_of(result, constraint)
+      else
+        result["required"] = (Array(result["required"]) | normalized_names)
+        normalize(result)
+      end
+    end
+
+    def exactly_one(schema, *names)
+      result = normalize_composition_input(schema)
+      normalized_names = normalize_names(names, minimum: 2)
+      constraint = {
+        "oneOf" => normalized_names.map { |name| {"required" => [name]} }
+      }
+      return normalize(result.merge(constraint)) unless result.key?("oneOf") || result.key?("$ref")
+
+      all_of(result, constraint)
+    end
+
+    def all_of(*schemas)
+      if schemas.empty?
+        raise InvalidSchemaCompositionError,
+              "all_of requires at least one OpenAPI Schema Object."
+      end
+
+      normalize({"allOf" => schemas.map { |schema| normalize_composition_input(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
+    private_class_method :build_dialect
+
+    def normalize_composition_input(schema)
+      return normalize(schema) if schema.is_a?(Hash)
+
+      raise InvalidSchemaCompositionError,
+            "Schema composition requires a Hash; received #{schema.class}."
+    end
+    private_class_method :normalize_composition_input
+
+    def normalize_names(names, minimum:)
+      normalized = names.map do |name|
+        unless name.is_a?(String) || name.is_a?(Symbol)
+          raise InvalidSchemaCompositionError,
+                "Property names must be non-empty Strings or Symbols; received #{name.class}."
+        end
+
+        value = name.to_s
+        if value.strip.empty?
+          raise InvalidSchemaCompositionError,
+                "Property names must be non-empty Strings or Symbols; received #{name.inspect}."
+        end
+        value
+      end.uniq
+
+      return normalized if normalized.length >= minimum
+
+      noun = minimum == 1 ? "name" : "names"
+      raise InvalidSchemaCompositionError,
+            "Schema composition requires at least #{minimum} distinct property #{noun}."
+    end
+    private_class_method :normalize_names
+  end
+end

data/lib/liminal/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Liminal
+  VERSION = "0.1.0"
+end

data/lib/liminal.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "liminal/version"
+require "liminal/errors"
+require "liminal/path"
+require "liminal/adapters/dry_schema_v1"
+require "liminal/dialects/openapi_30"
+require "liminal/internal/normalizer"
+require "liminal/internal/schema_merge"
+require "liminal/predicate_registry"
+require "liminal/schema"
+require "liminal/compiler"
+require "liminal/components"
+
+# Strict dry-schema to OpenAPI 3.0 compilation.
+module Liminal
+  module_function
+
+  # Compile a Dry::Schema-compatible source into an OpenAPI 3.0 Schema Object.
+  #
+  # @param schema [#to_ast] declarative dry-schema source
+  # @param dialect [Symbol] currently only +:openapi_3_0+
+  # @param source_name [String, nil] label included in diagnostics
+  # @param exclude [Array<Array, String, Symbol>] property paths to omit
+  # @param overrides [Hash] property paths mapped to OpenAPI fragments
+  # @param predicates [PredicateRegistry] immutable predicate registry
+  # @return [Hash] deterministic Schema Object containing only string keys
+  def compile(schema, dialect: :openapi_3_0, source_name: nil, exclude: [], overrides: {},
+              predicates: PredicateRegistry.default)
+    Compiler.new(
+      schema,
+      dialect: dialect,
+      source_name: source_name,
+      exclude: exclude,
+      overrides: overrides,
+      predicates: predicates
+    ).call
+  end
+end

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: liminal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maurizio De Magnis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.13.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.13.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: openapi3_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.64'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.64'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: |
+  Liminal converts the documented Dry::Schema AST representation into
+  deterministic, string-keyed OpenAPI 3.0 Schema Objects.
+email: root@olisti.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- lib/liminal.rb
+- lib/liminal/adapters/dry_schema_v1.rb
+- lib/liminal/compiler.rb
+- lib/liminal/components.rb
+- lib/liminal/dialects/openapi_30.rb
+- lib/liminal/dialects/openapi_30/metadata_validator.rb
+- lib/liminal/errors.rb
+- lib/liminal/internal/normalizer.rb
+- lib/liminal/internal/schema_merge.rb
+- lib/liminal/path.rb
+- lib/liminal/predicate_registry.rb
+- lib/liminal/schema.rb
+- lib/liminal/version.rb
+homepage: https://source.olisti.co/olisti.co/liminal
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: Strictly compile dry-schema ASTs into OpenAPI 3.0 schemas
+test_files: []