rspec-openapi 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64afa135a6f5a64d96bf01dbf50457b98964a0875a21f0e85c159dc16cbd6a11
-  data.tar.gz: '048bab9ffc8d6c6876a3c2aeb03e7cf68ba992db9da6953d50dfef9106fe5acd'
+  metadata.gz: dbbe2720c2fa2a498263a4c54a017982e17bf9aa7f34f422b8ccb2737c2b3ac1
+  data.tar.gz: 5725ab9fe452d6aa465d431597ab5f47b218b302b7222a7495fb1423bbf6087b
 SHA512:
-  metadata.gz: 9967fb54526fc7d743f4ba7d1de62c5a65b8a47ccc4350a55c575eef27d38110dfcc4ff2614fc02664d4eb622fb302422e1352cc2bbdb28e955989bc051609b7
-  data.tar.gz: b407e68dee10bf81a9b4ced14e8b767ce9099fd3ebedbecb67f43fd0f994fb06fb10868b422ba0fef9c6d4bbeaca2c06db5f58758f8ac09953c608949a6574ff
+  metadata.gz: 9783bfa40b973043bb0f1c1f4fc2d2ddaccde0371a43762024a8f1a7fddeb4245635e6c478ebc70949da2ebe3b5e5fdd53dc97327735eac8ce8c101c1302a78f
+  data.tar.gz: bed996f8f40811638b55338d652ec4483a583a631e5defaf3bd67e01d8eadd64533b68340ef28491b57f96fb52bc518acad34845d5e41f26b4fe9f3e50b6c71d

data/README.md

@@ -986,6 +986,13 @@ Run minitest with OPENAPI=1 to generate `doc/openapi.yaml` for your request spec
 $ OPENAPI=1 bundle exec rails t
 ```
 
+### Parallel test execution
+
+Minitest's parallel execution is supported, both thread-based (`parallelize_me!`) and
+process-based (Rails' `parallelize`). With forked workers, each worker dumps its
+records to a temporary directory on exit and the main process merges them back
+before writing the schema. No configuration is needed.
+
 ## Links
 
 Existing RSpec plugins which have OpenAPI integration:

data/lib/rspec/openapi/components_updater.rb

@@ -32,12 +32,12 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
       # Skip if the property using $ref is not found in the parent schema. The property may be removed.
       next if nested_schema.nil?
 
-      schema_name = extract_schema_name(base.dig(*paths))&.to_sym
+      schema_name = extract_schema_name(base.dig(*paths)).to_sym
       fresh_schemas[schema_name] ||= {}
-      RSpec::OpenAPI::SchemaMerger.merge!(fresh_schemas[schema_name], nested_schema)
+      RSpec::OpenAPI::SchemaMerger.merge_normalized!(fresh_schemas[schema_name], nested_schema)
     end
 
-    RSpec::OpenAPI::SchemaMerger.merge!(base, { components: { schemas: fresh_schemas } })
+    RSpec::OpenAPI::SchemaMerger.merge_normalized!(base, { components: { schemas: fresh_schemas } })
     RSpec::OpenAPI::SchemaCleaner.cleanup_components_schemas!(base, { components: { schemas: fresh_schemas } })
   end
 
@@ -49,7 +49,7 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
       schema_name = extract_schema_name(ref_link)
       schema_body = dig_schema(fresh, paths.grep_v(Integer))
 
-      RSpec::OpenAPI::SchemaMerger.merge!(acc, { schema_name => schema_body })
+      RSpec::OpenAPI::SchemaMerger.merge_normalized!(acc, { schema_name => schema_body })
     end
   end
 
@@ -101,8 +101,9 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
     [paths] if schema_ref?(dig_schema(base, paths)&.dig(:$ref))
   end
 
+  # Only ever given the value at a path ending in $ref, which is the link itself.
   def extract_schema_name(ref_link)
-    ref_link&.delete_prefix(SCHEMA_REF_PREFIX)
+    ref_link.delete_prefix(SCHEMA_REF_PREFIX)
   end
 
   def schema_ref?(ref_link)

data/lib/rspec/openapi/exchange_recorder.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+# Records every request/response exchange issued in an example so that
+# the exchange matching `request_pattern` can be looked up afterwards.
 module RSpec::OpenAPI::ExchangeRecorder
   THREAD_KEY = :rspec_openapi_exchanges
   VERBS = [:get, :post, :put, :patch, :delete, :head, :options].freeze
 
+  # Wraps HTTP verb methods to capture the exchange right after each request.
   module VerbTracking
     VERBS.each do |verb|
       define_method(verb) do |*args, &block|

data/lib/rspec/openapi/extractors/rails.rb

@@ -12,10 +12,10 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
 
     route, path = find_rails_route(fixed_request)
 
+    # find_rails_route yields nil, [route, nil] or [route, path]; a path always
+    # comes with the route it was taken from.
     return RSpec::OpenAPI::Extractors::Rack.request_attributes(request, example) unless path
 
-    raise "No route matched for #{fixed_request.request_method} #{fixed_request.path_info}" if route.nil?
-
     attrs = SharedExtractor.attributes(example)
     # :controller and :action always exist. :format is added when routes is configured as such.
     # TODO: Use .except(:controller, :action, :format) when we drop support for Ruby 2.x

data/lib/rspec/openapi/hash_helper.rb

@@ -1,43 +1,62 @@
 # frozen_string_literal: true
 
 class << RSpec::OpenAPI::HashHelper = Object.new
-  def paths_to_all_fields(obj)
-    case obj
-    when Hash
-      obj.each.flat_map do |k, v|
-        k = k.to_sym
-        [[k]] + paths_to_all_fields(v).map { |x| [k, *x] }
-      end
-    when Array
-      obj.flat_map.with_index do |value, i|
-        [[i]] + paths_to_all_fields(value).map { |x| [i, *x] }
-      end
-    else
-      []
-    end
-  end
-
+  # Paths in obj matching a dot separated selector, where `*` is any one key or
+  # array index. Only paths of exactly the selector's length can match, so this
+  # descends the branches that still match rather than listing every path in the
+  # document and filtering. A document built from a large suite holds tens of
+  # thousands of nodes and these selectors run dozens of times per build.
   def matched_paths(obj, selector)
     selector_parts = selector.split('.').map(&:to_sym)
-    paths_to_all_fields(obj).select do |key_parts|
-      key_parts.size == selector_parts.size && key_parts.zip(selector_parts).all? do |kp, sp|
-        kp == sp || (sp == :* && !kp.nil?)
-      end
-    end
+    matches = []
+    collect_matches(obj, selector_parts, 0, [], matches)
+    matches
   end
 
   def matched_paths_deeply_nested(obj, begin_selector, end_selector)
-    path_depth_sizes = paths_to_all_fields(obj).map(&:size).uniq
-    path_depth_sizes.map do |depth|
-      begin_selector_count = begin_selector.is_a?(Symbol) ? 0 : begin_selector.count('.')
-      end_selector_count = end_selector.is_a?(Symbol) ? 0 : end_selector.count('.')
-      diff = depth - begin_selector_count - end_selector_count
-      if diff >= 0
-        selector = "#{begin_selector}.#{'*.' * diff}#{end_selector}"
-        matched_paths(obj, selector)
+    begin_depth = begin_selector.to_s.count('.')
+    end_depth = end_selector.to_s.count('.')
+
+    # Every path in obj has all of its prefixes in obj too, so the depths that
+    # occur are exactly 1 up to the deepest one.
+    (1..max_depth(obj)).flat_map do |depth|
+      gap = depth - begin_depth - end_depth
+      next [] if gap.negative?
+
+      matched_paths(obj, "#{begin_selector}.#{'*.' * gap}#{end_selector}")
+    end
+  end
+
+  private
+
+  def collect_matches(obj, selector_parts, depth, prefix, matches)
+    part = selector_parts[depth]
+    last = depth == selector_parts.size - 1
+
+    each_child(obj) do |key, value|
+      next unless part == :* || part == key
+
+      path = [*prefix, key]
+      if last
+        matches << path
       else
-        []
+        collect_matches(value, selector_parts, depth + 1, path, matches)
       end
-    end.flatten(1)
+    end
+  end
+
+  def each_child(obj)
+    case obj
+    when Hash then obj.each { |key, value| yield key.to_sym, value }
+    when Array then obj.each_with_index { |value, index| yield index, value }
+    end
+  end
+
+  def max_depth(obj)
+    case obj
+    when Hash then obj.empty? ? 0 : 1 + obj.each_value.map { |value| max_depth(value) }.max
+    when Array then obj.empty? ? 0 : 1 + obj.map { |value| max_depth(value) }.max
+    else 0
+    end
   end
 end

data/lib/rspec/openapi/key_transformer.rb

@@ -18,18 +18,16 @@ class << RSpec::OpenAPI::KeyTransformer = Object.new
     end
   end
 
+  # `examples` is a map of named examples under a media type, whose names are
+  # normalized here. Under a schema it is a JSON Schema keyword holding a plain
+  # array instead, which has no names to normalize.
   def symbolize_examples(value)
-    case value
-    when Hash
-      value.to_h do |k, v|
-        k = k.downcase.tr(' ', '_') unless k.is_a?(Symbol)
+    return symbolize(value) unless value.is_a?(Hash)
 
-        [k.to_sym, symbolize(v)]
-      end
-    when Array
-      value.map { |v| symbolize(v) }
-    else
-      value
+    value.to_h do |k, v|
+      k = k.downcase.tr(' ', '_') unless k.is_a?(Symbol)
+
+      [k.to_sym, symbolize(v)]
     end
   end
 

data/lib/rspec/openapi/minitest_hooks.rb

@@ -5,6 +5,10 @@ require 'minitest'
 module RSpec::OpenAPI::Minitest
   Example = Struct.new(:context, :description, :metadata, :file_path)
 
+  # Guards path_records against concurrent appends from Minitest's
+  # thread-based parallel executor (parallelize_me!).
+  RECORD_MUTEX = Mutex.new
+
   module RunPatch
     def run(*args)
       result = super
@@ -14,7 +18,12 @@ module RSpec::OpenAPI::Minitest
         example = Example.new(self, human_name, {}, file_path)
         path = RSpec::OpenAPI.path.then { |p| p.is_a?(Proc) ? p.call(example) : p }
         record = RSpec::OpenAPI::RecordBuilder.build(self, example: example, extractor: SharedHooks.find_extractor)
-        RSpec::OpenAPI.path_records[path] << record if record
+        if record
+          RECORD_MUTEX.synchronize do
+            RSpec::OpenAPI::ParallelRecords.schedule_dump!
+            RSpec::OpenAPI.path_records[path] << record
+          end
+        end
       end
       result
     end
@@ -43,6 +52,7 @@ if ENV['OPENAPI']
   Minitest::Test.prepend RSpec::OpenAPI::Minitest::RunPatch
 
   Minitest.after_run do
+    RSpec::OpenAPI::ParallelRecords.merge!
     result_recorder = RSpec::OpenAPI::ResultRecorder.new(RSpec::OpenAPI.path_records)
     result_recorder.record_results!
     puts result_recorder.error_message if result_recorder.errors?

data/lib/rspec/openapi/parallel_records.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+require 'stringio'
+require 'tmpdir'
+require 'yaml'
+
+# Collects records across processes when the test framework forks parallel
+# workers, like Rails' `parallelize`. Records accumulate in each worker's own
+# memory, so without this the main process would write the schema from an empty
+# set. Each worker dumps its records to a shared directory on exit, and the
+# main process merges every dump back in before recording results.
+#
+# The dumps go through YAML.safe_load with an allowlist rather than Marshal,
+# so reading them cannot instantiate arbitrary objects even if the directory
+# were tampered with.
+module RSpec::OpenAPI::ParallelRecords
+  # The pid of the process that loaded this gem. Forked workers inherit the
+  # constant, which is how they know they are not the main process.
+  MAIN_PID = Process.pid
+
+  # Unpredictable per-run token. Workers inherit it across fork, while other
+  # local users cannot guess it to pre-create or plant files in the dump
+  # directory, which lives in the world-writable system tmpdir.
+  RUN_ID = SecureRandom.hex(16)
+
+  # Marks the stand-in a multipart upload leaves in a dump. The schema
+  # builder only ever asks an upload for its class and metadata, never for
+  # its content, so the file itself does not need to survive the trip.
+  UPLOADED_FILE_MARKER = '__rspec_openapi_uploaded_file'
+
+  class << self
+    def worker?
+      Process.pid != MAIN_PID
+    end
+
+    # Called when a worker records an example. Registered lazily from inside
+    # the worker because an at_exit inherited from the main process has already
+    # run there by the time workers fork: minitest executes the whole suite
+    # from an at_exit hook, so handlers the gem registered at load time are
+    # popped before any fork happens.
+    def schedule_dump!
+      return if @dump_scheduled || !worker?
+
+      @dump_scheduled = true
+      at_exit { dump! }
+    end
+
+    def dump!
+      return if RSpec::OpenAPI.path_records.empty?
+
+      FileUtils.mkdir_p(dump_dir, mode: 0o700)
+      encoded = RSpec::OpenAPI.path_records.transform_values do |records|
+        records.map { |record| transform_record(record) { |value| encode(value) } }
+      end
+      File.write(File.join(dump_dir, "#{Process.pid}.yaml"), YAML.dump(encoded))
+    end
+
+    def merge!
+      Dir.glob(File.join(dump_dir, '*.yaml')).sort.each do |file|
+        records_by_path = YAML.safe_load(File.read(file), permitted_classes: permitted_classes, aliases: true)
+        records_by_path.each do |path, records|
+          decoded = records.map { |record| transform_record(record) { |value| decode(value) } }
+          RSpec::OpenAPI.path_records[path].concat(decoded)
+        end
+      end
+    ensure
+      FileUtils.rm_rf(dump_dir)
+    end
+
+    private
+
+    def dump_dir
+      File.join(Dir.tmpdir, "rspec-openapi-records-#{RUN_ID}")
+    end
+
+    # Built lazily because ActiveSupport is not loaded in every setup. Rails
+    # request objects hand back HashWithIndifferentAccess for parameters.
+    def permitted_classes
+      classes = [Symbol, RSpec::OpenAPI::Record]
+      classes << ActiveSupport::HashWithIndifferentAccess if defined?(ActiveSupport::HashWithIndifferentAccess)
+      classes
+    end
+
+    def transform_record(record, &block)
+      RSpec::OpenAPI::Record.new(**record.to_h.transform_values(&block))
+    end
+
+    # Uploads hold an open Tempfile, which no serializer can represent, so
+    # dump their metadata instead.
+    def encode(value)
+      case value
+      when Array then value.map { |item| encode(item) }
+      when Hash then value.transform_values { |item| encode(item) }
+      when defined?(ActionDispatch::Http::UploadedFile) && ActionDispatch::Http::UploadedFile
+        { UPLOADED_FILE_MARKER => { 'filename' => value.original_filename, 'type' => value.content_type } }
+      else value
+      end
+    end
+
+    # Rebuilds a real UploadedFile so the schema builder's class checks match,
+    # backed by an empty StringIO in place of the worker's Tempfile.
+    def decode(value)
+      return value unless value.is_a?(Array) || value.is_a?(Hash)
+      return value.map { |item| decode(item) } if value.is_a?(Array)
+
+      meta = value[UPLOADED_FILE_MARKER]
+      if meta && value.size == 1 && defined?(ActionDispatch::Http::UploadedFile)
+        ActionDispatch::Http::UploadedFile.new(tempfile: StringIO.new, filename: meta['filename'], type: meta['type'])
+      else
+        value.transform_values { |item| decode(item) }
+      end
+    end
+  end
+end

data/lib/rspec/openapi/result_recorder.rb

@@ -51,12 +51,13 @@ class RSpec::OpenAPI::ResultRecorder
       RSpec::OpenAPI::OperationConverter.normalize!(spec)
       schema = RSpec::OpenAPI::DefaultSchema.build(title)
       schema[:info].merge!(RSpec::OpenAPI.info)
+      # Normalize the document once here rather than on every merge below.
       RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
       new_from_zero = {}
       records.each do |record|
         record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
-        RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
-        RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
+        RSpec::OpenAPI::SchemaMerger.merge_normalized!(spec, record_schema)
+        RSpec::OpenAPI::SchemaMerger.merge_normalized!(new_from_zero, record_schema)
       rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
         @error_records[e] = record # Avoid failing the build
       end

data/lib/rspec/openapi/schema_builder/variation_merger.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+class << RSpec::OpenAPI::SchemaBuilder
+  # Merges multiple observed schema variations of the same value (array items,
+  # stream items, repeated object properties) into a single OpenAPI schema.
+  # Divergent types are combined into oneOf, and keys that only appear in some
+  # variations are marked nullable.
+  VariationMerger = Object.new
+
+  class << VariationMerger
+    def merge_variations(variations)
+      # Drop empty `{}` schemas (e.g. items of an empty array) — they carry no
+      # type info and would otherwise spuriously mark every property of their
+      # populated siblings as nullable via the missing-key nullable rule.
+      non_empty = variations.reject(&:empty?)
+      return {} if non_empty.empty?
+      return non_empty.first if non_empty.size == 1
+
+      types = non_empty.map { |v| v[:type] }.compact.uniq
+      return one_of_schema(non_empty) if types.size > 1
+
+      case types.first
+      when 'object' then merge_object_variations(non_empty)
+      when 'array' then merge_array_item_variations(non_empty)
+      else non_empty.first
+      end
+    end
+
+    def merge_non_object_item_variations(schemas)
+      nullable_only = ->(schema) { schema.keys == [:nullable] }
+      typed = schemas.reject(&nullable_only)
+
+      merged = typed.size == 1 ? typed.first.dup : merge_multi(typed)
+      merged[:nullable] = true if schemas.any?(&nullable_only) && merged.is_a?(Hash)
+      merged
+    end
+
+    # Merge the per-key property schemas of multiple object variations.
+    # When `allow_recursive_merge` is true, objects are recursively merged via
+    # merge_variations and existing oneOf entries are flattened.
+    # When false (callsite: array-items merging), divergent property variations
+    # become oneOf without recursive descent.
+    def merge_property_variations(variations, allow_recursive_merge:)
+      property_keys(variations).each_with_object({}) do |key, merged_props|
+        all = variations.map { |v| v[:properties]&.[](key) }
+        prop_variations = all.reject { |p| p.nil? || p.keys == [:nullable] }
+        has_nullable = nullable_present?(all, recursive: allow_recursive_merge)
+
+        next if prop_variations.empty? && !has_nullable
+
+        merged_props[key] = merge_single_property(prop_variations, has_nullable,
+                                                  variations_total: variations.size,
+                                                  allow_recursive_merge: allow_recursive_merge,)
+      end
+    end
+
+    private
+
+    def merge_object_variations(variations)
+      {
+        type: 'object',
+        properties: merge_property_variations(variations, allow_recursive_merge: true),
+        required: variations.map { |v| v[:required] || [] }.reduce(:&) || [],
+      }
+    end
+
+    # Merge multiple array schemas by merging their `items` schemas.
+    def merge_array_item_variations(variations)
+      { type: 'array', items: merge_variations(variations.map { |v| v[:items] }.compact) }
+    end
+
+    def property_keys(variations)
+      variations.flat_map { |v| v[:properties]&.keys || [] }.uniq
+    end
+
+    # `recursive` mirrors merge_variations' original rule that also treats
+    # `{ ..., nullable: true }` as a nullable signal. Array-items merging only
+    # looks at outright nil or `{ nullable: true }` markers.
+    def nullable_present?(all_props, recursive:)
+      all_props.any? do |p|
+        p.nil? || (p.is_a?(Hash) && (p.keys == [:nullable] || (recursive && p[:nullable] == true)))
+      end
+    end
+
+    def merge_single_property(prop_variations, has_nullable, variations_total:, allow_recursive_merge:)
+      return { nullable: true } if prop_variations.empty?
+
+      merged =
+        if prop_variations.size == 1
+          prop_variations.first.dup
+        else
+          merge_multi(prop_variations)
+        end
+
+      return merged unless merged.is_a?(Hash)
+
+      # In recursive mode, multi-variation merges also flag nullable when the key
+      # only appeared in some of the source variations.
+      needs_nullable =
+        if allow_recursive_merge && prop_variations.size > 1
+          has_nullable || prop_variations.size < variations_total
+        else
+          has_nullable
+        end
+      merged[:nullable] = true if needs_nullable
+      merged
+    end
+
+    # Combine multiple variations of the same property: flatten existing oneOf
+    # entries, recurse into objects and arrays, and combine divergent types into
+    # oneOf. Scalar variations of a single type collapse to the first schema.
+    def merge_multi(prop_variations)
+      return { oneOf: flatten_one_of(prop_variations) } if prop_variations.any? { |p| p.key?(:oneOf) }
+
+      prop_types = prop_variations.map { |p| p[:type] }.compact.uniq
+      return one_of_schema(prop_variations) if prop_types.size > 1
+
+      case prop_types.first
+      when 'array' then merge_array_item_variations(prop_variations)
+      when 'object' then merge_variations(prop_variations)
+      else prop_variations.first.dup
+      end
+    end
+
+    def flatten_one_of(prop_variations)
+      prop_variations.each_with_object([]) do |prop, options|
+        clean = without_nullable(prop)
+        if clean.key?(:oneOf)
+          options.concat(clean[:oneOf])
+        elsif !clean.empty?
+          options << clean
+        end
+      end.uniq
+    end
+
+    def without_nullable(prop)
+      prop.reject { |k, _| k == :nullable }
+    end
+
+    def one_of_schema(variations)
+      { oneOf: variations.map { |p| without_nullable(p) }.uniq }
+    end
+  end
+
+  private_constant :VariationMerger
+end

data/lib/rspec/openapi/schema_builder.rb

@@ -2,6 +2,7 @@
 
 RSpec::OpenAPI::SchemaBuilder = Object.new
 require_relative 'schema_builder/build_context'
+require_relative 'schema_builder/variation_merger'
 
 class << RSpec::OpenAPI::SchemaBuilder
   # @param [RSpec::OpenAPI::Record] record
@@ -74,7 +75,7 @@ class << RSpec::OpenAPI::SchemaBuilder
     return nil if items.empty?
 
     variations = items.map { |item| build_property(item, ctx) }
-    build_merged_schema_from_variations(variations)
+    VariationMerger.merge_variations(variations)
   end
 
   # Returns the per-content-type body (schema + optional example/examples).
@@ -131,20 +132,18 @@ class << RSpec::OpenAPI::SchemaBuilder
       build_parameter(key, value, location: 'header', record: record)
     end
 
-    parameters&.empty? ? nil : parameters
+    parameters.empty? ? nil : parameters
   end
 
-  # `compound_name` and `required` follow from `location`:
-  # path/header params are always required and use bracketed names like
-  # `key[subkey]`; query params are pre-flattened and may be optional.
+  # Path and header params are always required; query params are pre-flattened
+  # by flatten_query_params and may be optional.
   def build_parameter(key, value, location:, record:)
     is_query = location == 'query'
-    compound_name = !is_query
     required = is_query ? record.required_request_params.include?(key) : true
     cast = try_cast(value)
     ctx = BuildContext.new(record: record, context: :request, key: key, path: key.to_s)
     {
-      name: compound_name ? build_parameter_name(key, value) : key,
+      name: key.to_s,
       in: location,
       required: required,
       schema: build_property(cast, ctx),
@@ -159,16 +158,6 @@ class << RSpec::OpenAPI::SchemaBuilder
     end
   end
 
-  def build_parameter_name(key, value)
-    key = key.to_s
-    if value.is_a?(Hash) && (value_keys = value.keys).size == 1
-      value_key = value_keys.first
-      build_parameter_name("#{key}[#{value_key}]", value[value_key])
-    else
-      key
-    end
-  end
-
   def flatten_query_params(params, parent_key = nil)
     params.each_with_object({}) do |(key, value), result|
       full_key = parent_key ? "#{parent_key}[#{key}]" : key.to_s
@@ -279,8 +268,6 @@ class << RSpec::OpenAPI::SchemaBuilder
   # distinguishable from "no override"; for :hybrid_additional_properties
   # plain lookup is enough because only Hash values are meaningful.
   def infer_override(path, record, context, kind)
-    return nil unless record
-
     overrides = record.send("#{context}_#{kind}")
     return nil unless overrides
 
@@ -333,141 +320,11 @@ class << RSpec::OpenAPI::SchemaBuilder
   def build_array_items_schema(array, ctx)
     schemas = array.map { |item| build_property(item, ctx) }
     return schemas.first if schemas.size == 1
-    return merge_non_object_item_variations(schemas) unless array.all?(Hash)
+    return VariationMerger.merge_non_object_item_variations(schemas) unless array.all?(Hash)
 
     merged = schemas.first.dup
-    merged[:properties] = merge_property_variations(schemas, allow_recursive_merge: false)
+    merged[:properties] = VariationMerger.merge_property_variations(schemas, allow_recursive_merge: false)
     merged[:required] = schemas.map { |s| s[:required] || [] }.reduce(:&) || []
     merged
   end
-
-  def merge_non_object_item_variations(schemas)
-    nullable_only = ->(schema) { schema.keys == [:nullable] }
-    typed = schemas.reject(&nullable_only)
-
-    merged = typed.size == 1 ? typed.first.dup : merge_multi(typed)
-    merged[:nullable] = true if schemas.any?(&nullable_only) && merged.is_a?(Hash)
-    merged
-  end
-
-  def build_merged_schema_from_variations(variations)
-    # Drop empty `{}` schemas (e.g. items of an empty array) — they carry no
-    # type info and would otherwise spuriously mark every property of their
-    # populated siblings as nullable via the missing-key nullable rule.
-    non_empty = variations.reject(&:empty?)
-    return {} if non_empty.empty?
-    return non_empty.first if non_empty.size == 1
-
-    types = non_empty.map { |v| v[:type] }.compact.uniq
-    return one_of_schema(non_empty) if types.size > 1
-
-    case types.first
-    when 'object'
-      {
-        type: 'object',
-        properties: merge_property_variations(non_empty, allow_recursive_merge: true),
-        required: non_empty.map { |v| v[:required] || [] }.reduce(:&) || [],
-      }
-    when 'array'
-      items_variations = non_empty.map { |v| v[:items] }.compact
-      { type: 'array', items: build_merged_schema_from_variations(items_variations) }
-    else
-      non_empty.first
-    end
-  end
-
-  # Merge the per-key property schemas of multiple object variations.
-  # When `allow_recursive_merge` is true, objects are recursively merged via
-  # build_merged_schema_from_variations and existing oneOf entries are flattened.
-  # When false (callsite: array-items merging), divergent property variations
-  # become oneOf without recursive descent.
-  def merge_property_variations(variations, allow_recursive_merge:)
-    property_keys(variations).each_with_object({}) do |key, merged_props|
-      all = variations.map { |v| v[:properties]&.[](key) }
-      prop_variations = all.reject { |p| p.nil? || p.keys == [:nullable] }
-      has_nullable = nullable_present?(all, recursive: allow_recursive_merge)
-
-      next if prop_variations.empty? && !has_nullable
-
-      merged_props[key] = merge_single_property(prop_variations, has_nullable,
-                                                variations_total: variations.size,
-                                                allow_recursive_merge: allow_recursive_merge,)
-    end
-  end
-
-  def property_keys(variations)
-    variations.flat_map { |v| v[:properties]&.keys || [] }.uniq
-  end
-
-  # `recursive` mirrors build_merged_schema_from_variations' original rule that
-  # also treats `{ ..., nullable: true }` as a nullable signal. Array-items
-  # merging only looks at outright nil or `{ nullable: true }` markers.
-  def nullable_present?(all_props, recursive:)
-    all_props.any? do |p|
-      p.nil? || (p.is_a?(Hash) && (p.keys == [:nullable] || (recursive && p[:nullable] == true)))
-    end
-  end
-
-  def merge_single_property(prop_variations, has_nullable, variations_total:, allow_recursive_merge:)
-    return { nullable: true } if prop_variations.empty?
-
-    merged =
-      if prop_variations.size == 1
-        prop_variations.first.dup
-      else
-        merge_multi(prop_variations)
-      end
-
-    return merged unless merged.is_a?(Hash)
-
-    # In recursive mode, multi-variation merges also flag nullable when the key
-    # only appeared in some of the source variations.
-    needs_nullable =
-      if allow_recursive_merge && prop_variations.size > 1
-        has_nullable || prop_variations.size < variations_total
-      else
-        has_nullable
-      end
-    merged[:nullable] = true if needs_nullable
-    merged
-  end
-
-  # Combine multiple variations of the same property: flatten existing oneOf
-  # entries, recurse into objects and arrays, and combine divergent types into
-  # oneOf. Scalar variations of a single type collapse to the first schema.
-  def merge_multi(prop_variations)
-    return { oneOf: flatten_one_of(prop_variations) } if prop_variations.any? { |p| p.key?(:oneOf) }
-
-    prop_types = prop_variations.map { |p| p[:type] }.compact.uniq
-    return one_of_schema(prop_variations) if prop_types.size > 1
-
-    case prop_types.first
-    when 'array'
-      items_variations = prop_variations.map { |p| p[:items] }.compact
-      { type: 'array', items: build_merged_schema_from_variations(items_variations) }
-    when 'object'
-      build_merged_schema_from_variations(prop_variations)
-    else
-      prop_variations.first.dup
-    end
-  end
-
-  def flatten_one_of(prop_variations)
-    prop_variations.each_with_object([]) do |prop, options|
-      clean = without_nullable(prop)
-      if clean.key?(:oneOf)
-        options.concat(clean[:oneOf])
-      elsif !clean.empty?
-        options << clean
-      end
-    end.uniq
-  end
-
-  def without_nullable(prop)
-    prop.reject { |k, _| k == :nullable }
-  end
-
-  def one_of_schema(variations)
-    { oneOf: variations.map { |p| without_nullable(p) }.uniq }
-  end
 end

data/lib/rspec/openapi/schema_cleaner.rb

@@ -79,10 +79,9 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
 
   private
 
-  # Recursively remove temporary fields like :_example_key and :_example_name from the schema
+  # Recursively remove temporary fields like :_example_key and :_example_name from the schema.
+  # Every caller has already established that it holds a Hash.
   def cleanup_temporary_fields!(hash)
-    return unless hash.is_a?(Hash)
-
     hash.delete(:_example_key)
     hash.delete(:_example_summary)
     hash.delete(:_example_name)
@@ -113,9 +112,9 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     path_definition.delete(:parameters) if path_definition[:parameters].empty?
   end
 
-  def cleanup_array!(base, spec, selector, fields_for_identity = [])
+  def cleanup_array!(base, spec, selector, fields_for_identity)
     marshal = lambda do |obj|
-      Marshal.dump(slice(obj, fields_for_identity))
+      Marshal.dump(obj.slice(*fields_for_identity))
     end
 
     RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
@@ -127,33 +126,20 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
       target_array.select! { |e| spec_identities.include?(marshal.call(e)) }
       target_array.sort_by! { |param| fields_for_identity.map { |f| param[f] }.join('-') }
       # Keep the last duplicate to produce the result stably
-      deduplicated = target_array.reverse.uniq { |param| slice(param, fields_for_identity) }.reverse
+      deduplicated = target_array.reverse.uniq { |param| param.slice(*fields_for_identity) }.reverse
       target_array.replace(deduplicated)
     end
     base
   end
 
+  # Every selector above names at least two segments, so a matched path always
+  # has a parent to delete the entry from.
   def cleanup_hash!(base, spec, selector)
     RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
       exist_in_base = !base.dig(*paths).nil?
       not_in_spec = spec.dig(*paths).nil?
-      if exist_in_base && not_in_spec
-        if paths.size == 1
-          base.delete(paths.last)
-        else
-          parent_node = base.dig(*paths[0..-2])
-          parent_node.delete(paths.last)
-        end
-      end
+      base.dig(*paths[0..-2]).delete(paths.last) if exist_in_base && not_in_spec
     end
     base
   end
-
-  def slice(obj, fields_for_identity)
-    if fields_for_identity.any?
-      obj.slice(*fields_for_identity)
-    else
-      obj
-    end
-  end
 end

data/lib/rspec/openapi/schema_merger.rb

@@ -1,12 +1,28 @@
 # frozen_string_literal: true
 
 class << RSpec::OpenAPI::SchemaMerger = Object.new
+  # Merge spec into base, normalizing the keys of both to symbols first.
+  #
   # @param [Hash] base
   # @param [Hash] spec
   def merge!(base, spec)
-    spec = RSpec::OpenAPI::KeyTransformer.symbolize(spec)
     base.replace(RSpec::OpenAPI::KeyTransformer.symbolize(base))
-    merge_schema!(base, spec)
+    merge_normalized!(base, spec)
+  end
+
+  # Same, for a base whose keys are already symbols.
+  #
+  # Normalizing base rebuilds every hash and array in it. Callers that merge
+  # record after record into one document hold a base of thousands of nodes and
+  # merge into it twice per request, so paying for that rebuild each time makes
+  # the whole build quadratic in the number of requests. A document read back
+  # from a file is normalized by SchemaFile, and anything this file builds is
+  # normalized by construction, so those callers can skip it.
+  #
+  # @param [Hash] base
+  # @param [Hash] spec
+  def merge_normalized!(base, spec)
+    merge_schema!(base, RSpec::OpenAPI::KeyTransformer.symbolize(spec))
   end
 
   SIMILARITY_THRESHOLD = 0.5
@@ -180,7 +196,11 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   end
 
   def convert_example_to_examples!(hash)
-    name = RSpec::OpenAPI::ExampleKey.normalize(hash.delete(:_example_key)) || 'default'
+    # This writes straight into the document rather than going through
+    # KeyTransformer, so symbolize the name here the way symbolize_examples
+    # would. Otherwise the next merge sees a string key beside the symbol one
+    # the builder produces and treats them as two different examples.
+    name = RSpec::OpenAPI::ExampleKey.normalize(hash.delete(:_example_key))&.to_sym || :default
     summary = hash.delete(:_example_summary)
     value = hash.delete(:example)
     example = {}

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.32.0'
+    VERSION = '0.33.0'
   end
 end

data/lib/rspec/openapi.rb

@@ -8,6 +8,7 @@ require 'rspec/openapi/operation_converter'
 require 'rspec/openapi/stream_parser'
 require 'rspec/openapi/record_builder'
 require 'rspec/openapi/exchange_recorder'
+require 'rspec/openapi/parallel_records'
 require 'rspec/openapi/result_recorder'
 require 'rspec/openapi/schema_builder'
 require 'rspec/openapi/schema_file'
@@ -131,10 +132,13 @@ module RSpec::OpenAPI
     # Allow Rails request specs to issue extra verbs (e.g. QUERY); ActionDispatch
     # otherwise rejects unknown verbs. No-op outside Rails.
     def register_http_methods(methods)
-      # simplecov:disable branch non-Rails guard for roda/hanami; the suite always loads Rails
+      # :nocov:
+      # Guards users without Rails. Every job here installs it, so this arm is
+      # unreachable from the suite. SimpleCov's token is `nocov`, so the marker
+      # this used to carry never actually excluded anything.
       return unless defined?(ActionDispatch::Request::HTTP_METHODS)
 
-      # simplecov:enable
+      # :nocov:
       Array(methods).each do |method|
         verb = method.to_s.upcase
         next if ActionDispatch::Request::HTTP_METHODS.include?(verb)
@@ -149,6 +153,9 @@ end
 if ENV['OPENAPI']
   RSpec::OpenAPI::Config.load_environment_settings
 
+  # :nocov:
+  # These two rescues report a framework the user does not have. Every job here
+  # installs both Hanami and Rails, so no run can reach them.
   begin
     require 'hanami'
   rescue LoadError
@@ -164,6 +171,7 @@ if ENV['OPENAPI']
   else
     require 'rspec/openapi/extractors/rails'
   end
+  # :nocov:
 end
 
 require 'rspec/openapi/minitest_hooks' if Object.const_defined?('Minitest')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.33.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -77,12 +77,14 @@ files:
 - lib/rspec/openapi/minitest_hooks.rb
 - lib/rspec/openapi/nullable_converter.rb
 - lib/rspec/openapi/operation_converter.rb
+- lib/rspec/openapi/parallel_records.rb
 - lib/rspec/openapi/record.rb
 - lib/rspec/openapi/record_builder.rb
 - lib/rspec/openapi/result_recorder.rb
 - lib/rspec/openapi/rspec_hooks.rb
 - lib/rspec/openapi/schema_builder.rb
 - lib/rspec/openapi/schema_builder/build_context.rb
+- lib/rspec/openapi/schema_builder/variation_merger.rb
 - lib/rspec/openapi/schema_cleaner.rb
 - lib/rspec/openapi/schema_file.rb
 - lib/rspec/openapi/schema_merger.rb
@@ -97,7 +99,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/exoego/rspec-openapi
   source_code_uri: https://github.com/exoego/rspec-openapi
-  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.32.0
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.33.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: