Refactor reference resolution for OpenAPI 3.1

Sorry - this is way too big for a single commit.

This changes the approach for handling references to be one where data
can be merged between a chain of references. Previously the approach was
to only allow a single $ref field (as per OpenAPI 3.0)

The reason for making this change is based on aspects in the
specification notably the reference object [1] that allows title and
summary fields to be overridden through the referencing process.

As far as I could tell schemas also share this property as per the newer
JSON Schema specifications (most applicable one for OpenAPI 3.1 is
2020-12) though I found it quite hard to find a clear source on
behaviour [2].

The approach taken to implementing this

[1]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject
[2]: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-8.2.3.1

Author: kevindew

lib/openapi3_parser/node/array.rb

@@ -40,7 +40,7 @@ def each(&block)
       # @return [Boolean]
       def ==(other)
         other.instance_of?(self.class) &&
-          node_context.same_data_and_source?(other.node_context)
+          node_context.same_data_inputs?(other.node_context)
       end
 
       # Used to access a node relative to this node

lib/openapi3_parser/node/context.rb

@@ -20,10 +20,15 @@ class Context
       # @param  [NodeFactory::Context]  factory_context
       # @return [Node::Context]
       def self.root(factory_context)
-        location = Source::Location.new(factory_context.source, [])
+        document_location = Source::Location.new(factory_context.source, [])
+
+        source_location = factory_context.source_location
+        input_locations = input_location?(factory_context.input) ? [source_location] : []
+
         new(factory_context.input,
-            document_location: location,
-            source_location: factory_context.source_location)
+            document_location: document_location,
+            source_locations: [source_location],
+            input_locations: input_locations)
       end
 
       # Create a context for the child of a previous context
@@ -38,9 +43,16 @@ def self.next_field(parent_context, field, factory_context)
           field
         )
 
+        input_locations = if input_location?(factory_context.input)
+                            [factory_context.source_location]
+                          else
+                            []
+                          end
+
         new(factory_context.input,
             document_location: document_location,
-            source_location: factory_context.source_location)
+            source_locations: [factory_context.source_location],
+            input_locations: input_locations)
       end
 
       # Create a context for a the a field that is the result of a reference
@@ -49,36 +61,63 @@ def self.next_field(parent_context, field, factory_context)
       # @param  [NodeFactory::Context]  reference_factory_context
       # @return [Node::Context]
       def self.resolved_reference(current_context, reference_factory_context)
-        new(reference_factory_context.input,
+        input_locations = if input_location?(reference_factory_context.input)
+                            current_context.input_locations + [reference_factory_context.source_location]
+                          else
+                            current_context.input_locations
+                          end
+
+        input = merge_reference_input(current_context.input, reference_factory_context.input)
+        new(input,
             document_location: current_context.document_location,
-            source_location: reference_factory_context.source_location)
+            source_locations: current_context.source_locations + [reference_factory_context.source_location],
+            input_locations: input_locations)
+      end
+
+      def self.merge_reference_input(current_input, reference_input)
+        can_merge = reference_input.respond_to?(:merge) && current_input.respond_to?(:merge)
+
+        return reference_input unless can_merge
+
+        input = reference_input.merge(current_input)
+        input.delete("$ref")
+        input
+      end
+
+      def self.input_location?(input)
+        return true unless input.respond_to?(:keys)
+
+        input.keys != ["$ref"]
       end
 
-      attr_reader :input, :document_location, :source_location
+      attr_reader :input, :document_location, :source_locations, :input_locations
 
-      # @param                           input
-      # @param  [Source::Location]       document_location
-      # @param  [Source::Location]       source_location
-      def initialize(input, document_location:, source_location:)
+      # @param                              input
+      # @param  [Source::Location]          document_location
+      # @param  [Array<Source::Location>]   source_locations
+      # @param  [Array<Source::Location>]   input_locations
+      def initialize(input, document_location:, source_locations:, input_locations:)
         @input = input
         @document_location = document_location
-        @source_location = source_location
+        @source_locations = source_locations
+        @input_locations = input_locations
       end
 
       # @param  [Context] other
       # @return [Boolean]
       def ==(other)
         document_location == other.document_location &&
-          same_data_and_source?(other)
+          source_locations == other.source_locations &&
+          same_data_inputs?(other)
       end
 
       # Check that contexts are the same without concern for document location
       #
       # @param  [Context] other
       # @return [Boolean]
-      def same_data_and_source?(other)
+      def same_data_inputs?(other)
         input == other.input &&
-          source_location == other.source_location
+          input_locations == other.input_locations
       end
 
       # The OpenAPI document associated with this context
@@ -88,17 +127,24 @@ def document
         document_location.source.document
       end
 
-      # The source file used to provide the data for this node
+      # The source files used to provide the data for this node
+      #
+      # @return [Array<Source>]
+      def sources
+        [source_locations].map(&:source)
+      end
+
+      # The source files used to provide the input for this node
       #
-      # @return [Source]
-      def source
-        source_location.source
+      # @return [Array<Source>]
+      def input_sources
+        [input_locations].map(&:source)
       end
 
       # @return [String]
       def inspect
         %{#{self.class.name}(document_location: #{document_location}, } +
-          %{source_location: #{source_location})}
+          %{input_locations: #{input_locations.join(', ')})}
       end
 
       # A string representing the location of the node
@@ -107,7 +153,9 @@ def inspect
       def location_summary
         summary = document_location.to_s
 
-        summary += " (#{source_location})" if document_location != source_location
+        if input_locations.length > 1 || document_location != input_locations.first
+          summary += " (#{input_locations.join(', ')})"
+        end
 
         summary
       end

lib/openapi3_parser/node/map.rb

@@ -53,7 +53,7 @@ def extension(value)
       # @return [Boolean]
       def ==(other)
         other.instance_of?(self.class) &&
-          node_context.same_data_and_source?(other.node_context)
+          node_context.same_data_inputs?(other.node_context)
       end
 
       # Iterates through the data of this node, used by Enumerable

lib/openapi3_parser/node/object.rb

@@ -53,7 +53,7 @@ def extension(value)
       # @return [Boolean]
       def ==(other)
         other.instance_of?(self.class) &&
-          node_context.same_data_and_source?(other.node_context)
+          node_context.same_data_inputs?(other.node_context)
       end
 
       # Iterates through the data of this node, used by Enumerable

lib/openapi3_parser/node/schema/oas_dialect3_1.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "openapi3_parser/node/object"
+
+module Openapi3Parser
+  module Node
+    module Schema
+      class OasDialect3_1 < Node::Object # rubocop:disable Naming/ClassAndModuleCamelCase
+      end
+    end
+  end
+end

lib/openapi3_parser/node/schema/v3_0.rb

@@ -35,7 +35,7 @@ class V3_0 < Node::Object # rubocop:disable Naming/ClassAndModuleCamelCase
         #
         # @return [String, nil]
         def name
-          segments = node_context.source_location.pointer.segments
+          segments = node_context.source_locations.first.pointer.segments
           segments[-1] if segments[-2] == "schemas"
         end
 

lib/openapi3_parser/node_factory/array.rb

@@ -61,6 +61,10 @@ def use_default?
         raw_input.empty?
       end
 
+      def build_node(data, node_context)
+        Node::Array.new(data, node_context) if data
+      end
+
       private
 
       def build_data(raw_input)
@@ -87,15 +91,17 @@ def initialize_value_factory(field_context)
         end
       end
 
-      def build_node(data, node_context)
-        Node::Array.new(data, node_context) if data
-      end
-
       def build_resolved_input
         return unless data
 
         data.map do |value|
-          value.respond_to?(:resolved_input) ? value.resolved_input : value
+          if value.respond_to?(:in_recursive_loop?) && value.in_recursive_loop?
+            RecursiveResolvedInput.new(value)
+          elsif value.respond_to?(:resolved_input)
+            value.resolved_input
+          else
+            value
+          end
         end
       end
 

lib/openapi3_parser/node_factory/callback.rb

@@ -11,8 +11,6 @@ def initialize(context)
               value_factory: NodeFactory::PathItem)
       end
 
-      private
-
       def build_node(data, node_context)
         Node::Callback.new(data, node_context)
       end

lib/openapi3_parser/node_factory/components.rb

@@ -16,12 +16,12 @@ class Components < NodeFactory::Object
       field "links", factory: :links_factory
       field "callbacks", factory: :callbacks_factory
 
-      private
-
-      def build_object(data, context)
-        Node::Components.new(data, context)
+      def build_node(data, node_context)
+        Node::Components.new(data, node_context)
       end
 
+      private
+
       def schemas_factory(context)
         NodeFactory::Map.new(
           context,

lib/openapi3_parser/node_factory/contact.rb

@@ -18,10 +18,8 @@ class Contact < NodeFactory::Object
             input_type: String,
             validate: Validation::InputValidator.new(Validators::Email)
 
-      private
-
-      def build_object(data, context)
-        Node::Contact.new(data, context)
+      def build_node(data, node_context)
+        Node::Contact.new(data, node_context)
       end
     end
   end