liminal-openapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0b5af3f5911eaa775a9306325d79b09874d931c8b9c85f2d68df36a44344cd0
+  data.tar.gz: 9886a15c8ba31ab5b19cab9f6d389188594cfec9d7ba16a89554cc56ab0e64a2
+SHA512:
+  metadata.gz: ce77ab37220564aa92fb2604902095de601e7fd2434ccfd8853cbec5eb181f0d2e9a58d061db3d6b3c8692aa7439e5e2ec141070480285b8d5a568210b771463
+  data.tar.gz: 559a90a3f3a6accbb987e7f38631f0e86c6e6688e9c0a12a92dd6cf68c1aa9705dacdca44cedf5f06d8e0216fb680d6a43d79c3993bd1d6e00187b35d4f3183a

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liminal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# Liminal OpenAPI
+
+`liminal-openapi` compiles Liminal schema sources and dry-validation contracts
+into OpenAPI 3.0 Schema Objects. It also registers reusable components and
+validates generated OpenAPI documents without depending on Rswag.
+
+## Compile schemas and contracts
+
+```ruby
+require "liminal/openapi"
+
+schema = Liminal::Openapi.contract(
+  Contracts::Users::Create,
+  exclude: [[:current_user]],
+  examples: {[:name] => "Mario"}
+)
+```
+
+Both schema and contract compilation accept Liminal compiler options such as
+`exclude`, `overrides`, and `predicates`. Contract names are used as diagnostic
+context unless an explicit `source_name` is provided.
+
+Passing a Hash treats it as a precompiled Schema Object. It is validated through
+`Liminal::Schema.normalize`, copied, and deeply frozen; compiler-only options are
+rejected because there is no dry-schema source to compile.
+
+`examples` and `overrides` are path-keyed Hashes. Paths are canonicalized before
+they are merged, duplicate aliases fail fast, and an explicit override takes
+precedence over an example at the same path.
+
+## Register components
+
+```ruby
+Liminal::Openapi.enrich(document) do |components|
+  components.register_contract(:create_user, Contracts::Users::Create)
+end
+```
+
+Registration validates the OpenAPI version and component container shape needed
+for the mutation. It rejects invalid names, ambiguous string/symbol registries,
+and component collisions, and returns immutable references. Use verification
+for full-document validation.
+
+## Verify generated documents
+
+```ruby
+require "liminal/openapi/verification"
+
+Liminal::Openapi::Verification.call(
+  checked: "swagger/v1/actions.yaml",
+  generated: "v1/actions.yaml"
+) do |temporary_root|
+  generate_document(temporary_root)
+end
+```
+
+Verification validates both documents and compares their structure: object key
+order is ignored, while array order and scalar types remain significant.
+Documents must be bundled; external `$ref` targets are rejected because changes
+outside either compared file would otherwise escape drift detection.
+
+To ignore generated examples without masking unrelated changes:
+
+```ruby
+Liminal::Openapi::Verification.call(
+  checked: "swagger/v1/actions.yaml",
+  generated: "v1/actions.yaml",
+  ignore: :operation_examples
+) { |temporary_root| generate_document(temporary_root) }
+```
+
+This policy removes only inline OpenAPI-defined example fields beneath operations.
+Property names, component names, defaults, extensions, and arbitrary
+payload fields named `example` or `examples` remain part of the comparison.
+
+## Development
+
+Run `bundle exec rake` for randomized RSpec and RuboCop checks,
+`bundle exec rake coverage` for enforced line and branch coverage, and
+`bundle exec rake build` to build the gem. The suite includes a real
+`Dry::Validation::Contract` integration.
+
+Made with ❤️ by [@olistik](https://olisti.co)

data/lib/liminal/openapi/component_reference.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module ComponentReference
+      module_function
+
+      def call(name)
+        Liminal::Components.reference(name)
+      rescue Liminal::InvalidComponentNameError => e
+        raise InvalidComponentName, e.message
+      end
+
+      def display_name(name)
+        Liminal::Components.normalize_name(name)
+      rescue Liminal::InvalidComponentNameError => e
+        raise InvalidComponentName, e.message
+      end
+    end
+  end
+end

data/lib/liminal/openapi/components_builder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    class ComponentsBuilder
+      def initialize(document)
+        @document = document
+      end
+
+      def register(name, schema, **compile_options)
+        Liminal::Openapi.register(
+          document: @document,
+          name: name,
+          schema: schema,
+          **compile_options
+        )
+      end
+
+      def register_contract(name, contract, **compile_options)
+        Liminal::Openapi.register_contract(
+          document: @document,
+          name: name,
+          contract: contract,
+          **compile_options
+        )
+      end
+    end
+  end
+end

data/lib/liminal/openapi/contract_resolver.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module ContractResolver
+      module_function
+
+      def call(contract, **compile_options)
+        validate_contract!(contract)
+        source = contract.schema
+        options = options_for(source, contract, compile_options)
+        Liminal::Openapi.schema(source, **options)
+      rescue InvalidPrecompiledSchema => e
+        raise InvalidPrecompiledSchema, contextual_message(contract, e)
+      end
+
+      def validate_contract!(contract)
+        return if contract.respond_to?(:schema)
+
+        raise InvalidContractSource,
+              "Contract source must respond to schema; received #{contract.class}."
+      end
+      private_class_method :validate_contract!
+
+      def options_for(source, contract, options)
+        return options unless source.respond_to?(:to_ast)
+        return options if options.key?(:source_name)
+        return options unless contract.respond_to?(:name)
+
+        options.merge(source_name: contract.name)
+      end
+      private_class_method :options_for
+
+      def contextual_message(contract, error)
+        name = contract.name if contract.respond_to?(:name)
+        label = name.to_s unless name.nil?
+        label && !label.empty? ? "#{label}: #{error.message}" : error.message
+      end
+      private_class_method :contextual_message
+    end
+  end
+end

data/lib/liminal/openapi/document_validator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module DocumentValidator
+      OPENAPI_30_PATTERN = /\A3\.0\.(?:0|[1-9]\d*)\z/
+      VERSION_PATTERN = /\A(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\z/
+      MISSING = Object.new.freeze
+      private_constant :OPENAPI_30_PATTERN, :VERSION_PATTERN, :MISSING
+
+      module_function
+
+      def call(document, component_name:)
+        context = "Cannot register component #{component_name.inspect}"
+        unless document.is_a?(Hash)
+          raise InvalidDocument, "#{context}: document is #{typed_value(document)}, expected a Hash."
+        end
+
+        validate_version!(document, context)
+        validate_component_maps!(document, context)
+        document
+      end
+
+      def validate_version!(document, context)
+        version = single_logical_value(document, "openapi", context)
+        reject_swagger!(document, context)
+        return if version.equal?(MISSING)
+
+        validate_openapi_version!(version, context)
+      end
+      private_class_method :validate_version!
+
+      def reject_swagger!(document, context)
+        return unless document.key?("swagger") || document.key?(:swagger)
+
+        raise UnsupportedOpenapiVersion,
+              "#{context}: Swagger 2.0 documents are unsupported; only OpenAPI 3.0.x is supported."
+      end
+      private_class_method :reject_swagger!
+
+      def validate_openapi_version!(version, context)
+        return if version.is_a?(String) && OPENAPI_30_PATTERN.match?(version)
+
+        detail = if version.is_a?(String) && VERSION_PATTERN.match?(version)
+                   "OpenAPI version #{version.inspect} is unsupported"
+                 else
+                   "OpenAPI version #{version.inspect} is malformed"
+                 end
+        raise UnsupportedOpenapiVersion, "#{context}: #{detail}; only OpenAPI 3.0.x is supported."
+      end
+      private_class_method :validate_openapi_version!
+
+      def validate_component_maps!(document, context)
+        components = single_logical_value(document, "components", context)
+        return if components.equal?(MISSING)
+
+        unless components.is_a?(Hash)
+          raise InvalidDocument,
+                "#{context}: components is #{typed_value(components)}, expected a Hash."
+        end
+
+        schemas = single_logical_value(components, "schemas", context)
+        return if schemas.equal?(MISSING)
+        return if schemas.is_a?(Hash)
+
+        raise InvalidDocument,
+              "#{context}: components.schemas is #{typed_value(schemas)}, expected a Hash."
+      end
+      private_class_method :validate_component_maps!
+
+      def single_logical_value(container, name, context)
+        keys = [name, name.to_sym].select { |key| container.key?(key) }
+        if keys.length > 1
+          raise InvalidDocument,
+                "#{context}: #{name} cannot be present under both String and Symbol keys."
+        end
+
+        keys.empty? ? MISSING : container.fetch(keys.first)
+      end
+      private_class_method :single_logical_value
+
+      def typed_value(value)
+        article = value.class.to_s.match?(/\A[AEIOU]/i) ? "an" : "a"
+        "#{article} #{value.class}"
+      end
+      private_class_method :typed_value
+    end
+  end
+end

data/lib/liminal/openapi/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    class Error < Liminal::Error; end
+
+    class InvalidDocument < Error; end
+    class UnsupportedOpenapiVersion < Error; end
+    class InvalidComponentName < Error; end
+    class InvalidSchemaSource < Error; end
+    class InvalidPrecompiledSchema < InvalidSchemaSource; end
+    class InvalidContractSource < Error; end
+    class InvalidSchemaOptions < Error; end
+    class InvalidOverrideFragment < InvalidSchemaOptions; end
+    class CompileOptionsForPrecompiledSchema < Error; end
+  end
+end

data/lib/liminal/openapi/example_overrides.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module ExampleOverrides
+      module_function
+
+      def call(examples:, overrides:)
+        validate_hash!(examples, :examples)
+        validate_hash!(overrides, :overrides)
+
+        normalized_examples = normalize_paths(examples, :examples)
+        normalized_overrides = normalize_paths(overrides, :overrides) do |path, fragment|
+          unless fragment.is_a?(Hash)
+            raise InvalidOverrideFragment,
+                  "Override at #{path.inspect} must be a Hash; received #{fragment.class}."
+          end
+        end
+
+        merge(normalized_examples, normalized_overrides)
+      end
+
+      def merge(examples, overrides)
+        result = examples.to_h do |path, value|
+          [path, {"example" => value}]
+        end
+        overrides.each do |path, fragment|
+          example = result.fetch(path, {})
+          example = {} if fragment.key?("example") || fragment.key?(:example)
+          result[path] = example.merge(fragment)
+        end
+        result
+      end
+      private_class_method :merge
+
+      def validate_hash!(value, name)
+        return if value.is_a?(Hash)
+
+        raise InvalidSchemaOptions,
+              "#{name} must be a Hash of paths to values; received #{value.class}."
+      end
+      private_class_method :validate_hash!
+
+      def normalize_paths(values, name)
+        values.each_with_object({}) do |(path, value), normalized|
+          yield(path, value) if block_given?
+          canonical = Liminal::Path.normalize(path)
+          if normalized.key?(canonical)
+            raise InvalidSchemaOptions,
+                  "#{name} contains more than one entry for path #{Liminal::Path.display(canonical)}."
+          end
+
+          normalized[canonical] = value
+        rescue ArgumentError => e
+          raise InvalidSchemaOptions, "Invalid #{name} path #{path.inspect}: #{e.message}."
+        end
+      end
+      private_class_method :normalize_paths
+    end
+  end
+end

data/lib/liminal/openapi/schema_resolver.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module SchemaResolver
+      module_function
+
+      def call(source, **compile_options)
+        schema = if source.is_a?(Hash)
+                   resolve_precompiled(source, compile_options)
+                 elsif source.respond_to?(:to_ast)
+                   Liminal.compile(source, **compile_options)
+                 else
+                   raise InvalidSchemaSource,
+                         "Schema source must be a Hash or a dry-schema source responding to to_ast; " \
+                         "received #{source.class}."
+                 end
+        deep_freeze(schema)
+      end
+
+      def resolve_precompiled(source, compile_options)
+        unless compile_options.empty?
+          options = compile_options.keys.map(&:inspect).sort.join(", ")
+          raise CompileOptionsForPrecompiledSchema,
+                "Compiler options are not valid for a precompiled OpenAPI schema Hash: #{options}."
+        end
+
+        Liminal::Schema.normalize(source)
+      rescue Liminal::InvalidSchemaError => e
+        raise InvalidPrecompiledSchema, e.message
+      end
+      private_class_method :resolve_precompiled
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each do |key, item|
+            deep_freeze(key)
+            deep_freeze(item)
+          end
+        when Array
+          value.each { |item| deep_freeze(item) }
+        end
+        value.freeze
+      end
+      private_class_method :deep_freeze
+    end
+  end
+end

data/lib/liminal/openapi/verification/document.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module Verification
+      module Document
+        module_function
+
+        # rubocop:disable Naming/PredicateMethod
+        def validate!(path)
+          normalized_path, document = parse(path)
+          validate_document!(normalized_path, document)
+          true
+        end
+
+        def validate_bundled!(path)
+          normalized_path, document = parse(path)
+          sources = document.reference_sources.to_a.map(&:relative_to_root).sort
+          raise ExternalReferenceError.new(normalized_path, sources) unless sources.empty?
+
+          validate_document!(normalized_path, document)
+          true
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        def load(path)
+          document = Psych.safe_load(
+            File.read(path.to_s),
+            permitted_classes: [Date, Time],
+            aliases: true
+          )
+          return document if document.is_a?(Hash)
+
+          raise InvalidDocumentError.new(path.to_s, "document root must be an object")
+        rescue InvalidDocumentError
+          raise
+        rescue StandardError => e
+          raise InvalidDocumentError.new(path.to_s, e.message)
+        end
+
+        def parse(path)
+          normalized_path = path.to_s
+          raise MissingDocumentError, normalized_path unless File.file?(normalized_path)
+
+          [normalized_path, Openapi3Parser.load_file(normalized_path)]
+        rescue MissingDocumentError, InvalidDocumentError
+          raise
+        rescue StandardError => e
+          raise InvalidDocumentError.new(normalized_path, e.message)
+        end
+        private_class_method :parse
+
+        def validate_document!(path, document)
+          return if document.valid?
+
+          raise InvalidDocumentError.new(path, document.errors)
+        rescue InvalidDocumentError
+          raise
+        rescue StandardError => e
+          raise InvalidDocumentError.new(path, e.message)
+        end
+        private_class_method :validate_document!
+      end
+    end
+  end
+end

data/lib/liminal/openapi/verification/error.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module Verification
+      class Error < Liminal::Openapi::Error; end
+      class InvalidConfigurationError < Error; end
+
+      class ExternalReferenceError < InvalidConfigurationError
+        attr_reader :path, :sources
+
+        def initialize(path, sources)
+          @path = path
+          @sources = sources.freeze
+          super("OpenAPI verification requires bundled documents without external $ref targets; " \
+                "#{path} references #{sources.join(', ')}")
+        end
+      end
+
+      class MissingDocumentError < Error
+        attr_reader :path
+
+        def initialize(path)
+          @path = path
+          super("OpenAPI document does not exist: #{path}")
+        end
+      end
+
+      class InvalidDocumentError < Error
+        attr_reader :path, :errors
+
+        def initialize(path, errors)
+          @path = path
+          @errors = errors
+          super("OpenAPI validation failed for #{path}:\n#{format_errors(errors)}")
+        end
+
+        private
+
+        def format_errors(errors)
+          return errors unless errors.respond_to?(:to_h)
+
+          errors.to_h.map do |location, messages|
+            "#{location}: #{messages.join(', ')}"
+          end.join("\n")
+        end
+      end
+
+      class DocumentDriftError < Error
+        attr_reader :difference
+
+        def initialize(difference)
+          @difference = difference
+          super("OpenAPI documents differ at #{difference.pointer}: " \
+                "checked=#{difference.checked_label}, generated=#{difference.generated_label}")
+        end
+      end
+    end
+  end
+end

data/lib/liminal/openapi/verification/normalizer/operation_example_stripper.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module Verification
+      module Normalizer
+        # Removes only fields that OpenAPI defines as examples beneath
+        # operations. Arbitrary payload and map keys named "example" remain
+        # significant during verification.
+        module OperationExampleStripper
+          HTTP_METHODS = %w[delete get head options patch post put trace].freeze
+          private_constant :HTTP_METHODS
+
+          module_function
+
+          def call(paths)
+            return unless paths.is_a?(Hash)
+
+            paths.each_value { |path_item| visit_path_item(path_item) }
+          end
+
+          def visit_path_item(path_item)
+            return unless path_item.is_a?(Hash)
+
+            visit_parameters(path_item["parameters"])
+            HTTP_METHODS.each { |method| visit_operation(path_item[method]) }
+          end
+          private_class_method :visit_path_item
+
+          def visit_operation(operation)
+            return unless operation.is_a?(Hash)
+
+            visit_parameters(operation["parameters"])
+            visit_request_body(operation["requestBody"])
+            visit_responses(operation["responses"])
+            visit_callbacks(operation["callbacks"])
+          end
+          private_class_method :visit_operation
+
+          def visit_parameters(parameters)
+            return unless parameters.is_a?(Array)
+
+            parameters.each { |parameter| visit_parameter(parameter) }
+          end
+          private_class_method :visit_parameters
+
+          def visit_parameter(parameter)
+            return unless parameter.is_a?(Hash)
+
+            remove_examples(parameter)
+            visit_schema(parameter["schema"])
+            visit_content(parameter["content"])
+          end
+          private_class_method :visit_parameter
+
+          def visit_request_body(request_body)
+            visit_content(request_body["content"]) if request_body.is_a?(Hash)
+          end
+          private_class_method :visit_request_body
+
+          def visit_responses(responses)
+            return unless responses.is_a?(Hash)
+
+            responses.each_value do |response|
+              next unless response.is_a?(Hash)
+
+              visit_headers(response["headers"])
+              visit_content(response["content"])
+            end
+          end
+          private_class_method :visit_responses
+
+          def visit_headers(headers)
+            return unless headers.is_a?(Hash)
+
+            headers.each_value { |header| visit_parameter(header) }
+          end
+          private_class_method :visit_headers
+
+          def visit_content(content)
+            return unless content.is_a?(Hash)
+
+            content.each_value { |media_type| visit_media_type(media_type) }
+          end
+          private_class_method :visit_content
+
+          def visit_media_type(media_type)
+            return unless media_type.is_a?(Hash)
+
+            remove_examples(media_type)
+            visit_schema(media_type["schema"])
+            visit_encodings(media_type["encoding"])
+          end
+          private_class_method :visit_media_type
+
+          def visit_encodings(encodings)
+            return unless encodings.is_a?(Hash)
+
+            encodings.each_value do |encoding|
+              visit_headers(encoding["headers"]) if encoding.is_a?(Hash)
+            end
+          end
+          private_class_method :visit_encodings
+
+          def visit_callbacks(callbacks)
+            return unless callbacks.is_a?(Hash)
+
+            callbacks.each_value do |callback|
+              next unless callback.is_a?(Hash)
+
+              callback.each_value { |path_item| visit_path_item(path_item) }
+            end
+          end
+          private_class_method :visit_callbacks
+
+          def visit_schema(schema)
+            return unless schema.is_a?(Hash)
+
+            schema.delete("example")
+            visit_schema_map(schema["properties"])
+            visit_schema(schema["items"])
+            visit_schema(schema["not"])
+            visit_schema(schema["additionalProperties"])
+            %w[allOf anyOf oneOf].each do |keyword|
+              children = schema[keyword]
+              children.each { |child| visit_schema(child) } if children.is_a?(Array)
+            end
+          end
+          private_class_method :visit_schema
+
+          def visit_schema_map(schemas)
+            schemas.each_value { |schema| visit_schema(schema) } if schemas.is_a?(Hash)
+          end
+          private_class_method :visit_schema_map
+
+          def remove_examples(value)
+            value.delete("example")
+            value.delete("examples")
+          end
+          private_class_method :remove_examples
+        end
+      end
+    end
+  end
+end

data/lib/liminal/openapi/verification/normalizer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "liminal/openapi/verification/normalizer/operation_example_stripper"
+
+module Liminal
+  module Openapi
+    module Verification
+      module Normalizer
+        OPERATION_EXAMPLES = "operation_examples"
+        private_constant :OPERATION_EXAMPLES, :OperationExampleStripper
+
+        module_function
+
+        def call(document, ignore:)
+          policies = normalize_policies(ignore)
+          OperationExampleStripper.call(document.fetch("paths", {})) if policies.include?(OPERATION_EXAMPLES)
+          document
+        end
+
+        def normalize_policies(ignore)
+          Array(ignore).map do |entry|
+            unless entry.is_a?(String) || entry.is_a?(Symbol)
+              raise InvalidConfigurationError,
+                    "Verification ignore policies must be a String or Symbol; received #{entry.class}."
+            end
+
+            policy = entry.to_s
+            next policy if policy == OPERATION_EXAMPLES
+
+            raise InvalidConfigurationError, "Unsupported verification ignore policy: #{entry.inspect}"
+          end
+        end
+        private_class_method :normalize_policies
+      end
+    end
+  end
+end

data/lib/liminal/openapi/verification/runner.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module Verification
+      class Runner
+        def initialize(checked:, generated:, ignore:)
+          @checked = checked.to_s
+          @generated = generated.to_s
+          @ignore = ignore
+        end
+
+        def call(&generator)
+          validate_configuration!(generator)
+          Document.validate_bundled!(checked)
+
+          Dir.mktmpdir("liminal-openapi-verification") do |temporary_root|
+            generator.call(temporary_root)
+            generated_path = File.join(temporary_root, generated)
+            Document.validate_bundled!(generated_path)
+            compare!(generated_path)
+          end
+
+          true
+        end
+
+        private
+
+        attr_reader :checked, :generated, :ignore
+
+        def validate_configuration!(generator)
+          raise InvalidConfigurationError, "A generation block is required" unless generator
+
+          path = Pathname.new(generated)
+          if generated.empty? || path.absolute? || path.each_filename.include?("..")
+            raise InvalidConfigurationError,
+                  "Generated document path must be relative and remain below the temporary root: #{generated.inspect}"
+          end
+
+          Normalizer.call({}, ignore: ignore)
+        end
+
+        def compare!(generated_path)
+          checked_document = Normalizer.call(Document.load(checked), ignore: ignore)
+          generated_document = Normalizer.call(Document.load(generated_path), ignore: ignore)
+          difference = StructuralDifference.between(checked_document, generated_document)
+          raise DocumentDriftError, difference if difference
+        end
+      end
+    end
+  end
+end

data/lib/liminal/openapi/verification/structural_difference.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Liminal
+  module Openapi
+    module Verification
+      class StructuralDifference
+        MISSING = Object.new.freeze
+        private_constant :MISSING
+
+        attr_reader :path, :checked, :generated
+
+        def self.between(checked, generated, path = [])
+          return if checked.eql?(generated)
+          return between_hashes(checked, generated, path) if checked.is_a?(Hash) && generated.is_a?(Hash)
+          return between_arrays(checked, generated, path) if checked.is_a?(Array) && generated.is_a?(Array)
+
+          new(path, checked, generated)
+        end
+
+        def self.between_hashes(checked, generated, path)
+          (checked.keys | generated.keys).sort_by(&:to_s).each do |key|
+            difference = between(
+              checked.fetch(key, MISSING),
+              generated.fetch(key, MISSING),
+              path + [key]
+            )
+            return difference if difference
+          end
+          nil
+        end
+
+        def self.between_arrays(checked, generated, path)
+          [checked.length, generated.length].max.times do |index|
+            difference = between(
+              checked.fetch(index, MISSING),
+              generated.fetch(index, MISSING),
+              path + [index]
+            )
+            return difference if difference
+          end
+          nil
+        end
+        private_class_method :between_hashes, :between_arrays
+
+        def initialize(path, checked, generated)
+          @path = path.freeze
+          @checked = checked
+          @generated = generated
+        end
+
+        def pointer
+          return "#" if path.empty?
+
+          "#/#{path.map { |part| escape_pointer(part) }.join('/')}"
+        end
+
+        def checked_label
+          display(checked)
+        end
+
+        def generated_label
+          display(generated)
+        end
+
+        private
+
+        def escape_pointer(part)
+          part.to_s.gsub("~", "~0").gsub("/", "~1")
+        end
+
+        def display(value)
+          return "<missing>" if value.equal?(MISSING)
+
+          text = value.inspect
+          text.length > 200 ? "#{text[0, 197]}..." : text
+        end
+      end
+    end
+  end
+end

data/lib/liminal/openapi/verification.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "date"
+require "pathname"
+require "psych"
+require "tmpdir"
+require "openapi3_parser"
+require "liminal/openapi"
+require "liminal/openapi/verification/error"
+require "liminal/openapi/verification/document"
+require "liminal/openapi/verification/normalizer"
+require "liminal/openapi/verification/structural_difference"
+require "liminal/openapi/verification/runner"
+
+module Liminal
+  module Openapi
+    module Verification
+      module_function
+
+      def call(checked:, generated:, ignore: [], &generator)
+        Runner.new(checked: checked, generated: generated, ignore: ignore).call(&generator)
+      end
+
+      def validate!(path)
+        Document.validate!(path)
+      end
+    end
+  end
+end

data/lib/liminal/openapi/version.rb

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

data/lib/liminal/openapi.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "liminal"
+require "liminal/openapi/version"
+require "liminal/openapi/error"
+require "liminal/openapi/example_overrides"
+require "liminal/openapi/schema_resolver"
+require "liminal/openapi/contract_resolver"
+require "liminal/openapi/component_reference"
+require "liminal/openapi/document_validator"
+require "liminal/openapi/components_builder"
+
+module Liminal
+  module Openapi
+    module_function
+
+    def schema(source, examples: nil, **compile_options)
+      if !examples.nil? || compile_options.key?(:overrides)
+        overrides = compile_options.key?(:overrides) ? compile_options.delete(:overrides) : {}
+        compile_options[:overrides] = ExampleOverrides.call(
+          examples: examples.nil? ? {} : examples,
+          overrides: overrides
+        )
+      end
+      SchemaResolver.call(source, **compile_options)
+    end
+
+    def contract(contract, **compile_options)
+      ContractResolver.call(contract, **compile_options)
+    end
+
+    def ref(name)
+      ComponentReference.call(name)
+    end
+
+    def register(document:, name:, schema:, **compile_options)
+      component_name = ComponentReference.display_name(name)
+      DocumentValidator.call(document, component_name: component_name)
+      resolved_schema = self.schema(schema, **compile_options)
+      register_resolved(document, component_name, resolved_schema)
+    end
+
+    def register_contract(document:, name:, contract:, **compile_options)
+      component_name = ComponentReference.display_name(name)
+      DocumentValidator.call(document, component_name: component_name)
+      resolved_schema = self.contract(contract, **compile_options)
+      register_resolved(document, component_name, resolved_schema)
+    end
+
+    def enrich(document)
+      yield ComponentsBuilder.new(document)
+      document
+    end
+
+    def register_resolved(document, component_name, schema)
+      Liminal::Components.register(
+        document: document,
+        name: component_name,
+        schema: schema
+      )
+    end
+    private_class_method :register_resolved
+  end
+end

data/lib/liminal-openapi.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "liminal/openapi"

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: liminal-openapi
+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: liminal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: openapi3_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+- !ruby/object:Gem::Dependency
+  name: dry-validation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !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-openapi compiles dry-schema and dry-validation contracts into
+  OpenAPI 3.0 schemas, manages schema components, and verifies generated
+  OpenAPI documents without depending on a request-spec framework.
+email: root@olisti.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/liminal-openapi.rb
+- lib/liminal/openapi.rb
+- lib/liminal/openapi/component_reference.rb
+- lib/liminal/openapi/components_builder.rb
+- lib/liminal/openapi/contract_resolver.rb
+- lib/liminal/openapi/document_validator.rb
+- lib/liminal/openapi/error.rb
+- lib/liminal/openapi/example_overrides.rb
+- lib/liminal/openapi/schema_resolver.rb
+- lib/liminal/openapi/verification.rb
+- lib/liminal/openapi/verification/document.rb
+- lib/liminal/openapi/verification/error.rb
+- lib/liminal/openapi/verification/normalizer.rb
+- lib/liminal/openapi/verification/normalizer/operation_example_stripper.rb
+- lib/liminal/openapi/verification/runner.rb
+- lib/liminal/openapi/verification/structural_difference.rb
+- lib/liminal/openapi/version.rb
+homepage: https://source.olisti.co/olisti.co/liminal-openapi
+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: Compile Liminal schemas and verify OpenAPI documents
+test_files: []