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].

To support this there are now some new concepts:

- A node context now has multiple source_locations - as data can be
  combined from multiple places
- A node context has a concept, input_locations, which record all of the
  data involved in a node that aren't purely references (i.e. all the
  source locations that contributed to the node data)
- There is now a Referenceable module that can be mixed into NodeFactory
  classes, this allows NodeFactories to act more as the mediator in
  charge of a reference, whereas previously more went through a
  Reference field (this is to reflect the nature of merging)
- Aspects of the ObjectFactory::NodeBuilder class have been separated
  into ObjectFactory::NodeErrors, ObjectFactory::ResolvedInputBuilder
  and a new iteration of it's namesake. This is to reflect an increase
  in complexity in node building due to the node data merging
- As part of the new NodeBuilder class the building of node objects is
  now done by the NodeBuilder class calling public methods on node
  factories. This has led to them having their #build_object methods
  replaced with #build_node methods that need a public interface

[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