verquest 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48e1067531cf426f709ebe2dfffe4548cfd161b19f9481ca87599a0152e1fcab
-  data.tar.gz: d4387ad9de93bceebb05e94b69560f43f7b374cad28588a3ff0599d9f8d17667
+  metadata.gz: f02a2f54e2736694e9f26f4c4b2fd2d2939fb246b3bd9031733e6bf606fac3f0
+  data.tar.gz: 0ca7bd1d066426f72a8507cb25dcda7f45df491dedfd8ee4b0be9e425df5c528
 SHA512:
-  metadata.gz: bc95249593570b003e7dc49881fe4a3a34a60efc535be6f1803c17db7cd6475317eaacb0c9ff5c1f11ba24bb18ff5065d86d070be92e24f7ff4d1e1fa88f14e9
-  data.tar.gz: 8d915f5cbd2f3fdfea67a1d94f13803d9a1125db6a8a21fe3cec81233693017391e40f69feee0fd9a60a8bb6926764cc0d7de1c77a3746c7ef87e2672acdd978
+  metadata.gz: 68bb809fe32619ff5bf02f43787cee0d36f6462c1fb84114b246e8165c6c8725d1fd05048cd788d5c9eb97d89b60cc9dc91c008b81ad1240d80dd3dc62cf1843
+  data.tar.gz: 59471fdfdfb8aaca008467e772d925520fd1b491ce9e303b987bc96f4c2d119f37517cc819c5506de17b2839c3f386827fc5408cfa9fa694b4250642dbd1d6a2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.6.3] - 2026-03-17
+
+### Fixed
+- Transformer fixes: fix null propagation, unknown discriminator, and null variant path.
+
+## [0.6.2] - 2025-12-09
+
+### Fixed
+- The `item_schema_options` is now properly passed to the `Array` property.
+
 ## [0.6.1] - 2025-10-13
 
 ### Fixed

data/Rakefile

@@ -1,12 +1,35 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "minitest/test_task"
+require "rake/testtask"
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = true
+end
 
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+desc "Check YARD documentation coverage (must be 100%)"
+task :yard do
+  require "yard"
+
+  # Capture the stats output
+  stats = YARD::CLI::Stats.new
+  stats.run("--list-undoc")
+
+  # Check if there are any undocumented objects
+  undocumented = stats.instance_variable_get(:@undoc_list) || []
+
+  unless undocumented.empty?
+    abort "\nYARD documentation check failed: #{undocumented.size} undocumented objects found."
+  end
+
+  puts "\nYARD documentation: 100% documented"
+end
+
+task default: %i[test rubocop yard]

data/lib/verquest/base/private_class_methods.rb

@@ -265,9 +265,10 @@ module Verquest
     # @param required [Boolean, Array<Symbol>] Whether the array property is required
     # @param nullable [Boolean] Whether this array can be null
     # @param map [String, nil] An optional mapping to another array property
+    # @param item_schema_options [Hash] Additional JSON schema options for the array items (merged with custom type options)
     # @param schema_options [Hash] Additional schema options for the array property
     # @return [void]
-    def array(name, type:, required: nil, nullable: nil, map: nil, **schema_options)
+    def array(name, type:, required: nil, nullable: nil, map: nil, item_schema_options: {}, **schema_options)
       camelize(schema_options)
 
       type = default_options.fetch(:type, type)
@@ -275,10 +276,40 @@ module Verquest
       nullable = default_options.fetch(:nullable, false) if nullable.nil?
       schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)
 
-      array = Properties::Array.new(name:, type:, required:, nullable:, map:, **schema_options)
+      array = Properties::Array.new(name:, type:, required:, nullable:, map:, item_schema_options:, **schema_options)
       current_scope.add(array)
     end
 
+    # Defines a oneOf property for polymorphic schemas
+    #
+    # Creates a JSON Schema oneOf structure where exactly one of the defined
+    # schemas must match. When used at the root level (without a name), it creates
+    # a "combination schema" where the entire request body matches one of the options.
+    #
+    # @param name [Symbol, nil] The property name, or nil for root-level oneOf
+    # @param discriminator [Symbol, nil] The property used to discriminate between schemas
+    # @param required [Boolean, Array<Symbol>, nil] Whether this property is required
+    # @param nullable [Boolean] Whether this property can be null
+    # @param map [String, nil] An optional mapping to another property
+    # @yield Block defining the schema options using reference declarations
+    # @return [void]
+    def one_of(name: nil, discriminator: nil, required: nil, nullable: nil, map: nil, &block)
+      required = default_options.fetch(:required, false) if required.nil?
+      nullable = default_options.fetch(:nullable, false) if nullable.nil?
+
+      one_of = Properties::OneOf.new(name:, discriminator:, required:, nullable:, map:)
+      current_scope.add(one_of)
+
+      if block_given?
+        previous_scope = current_scope
+        @current_scope = one_of
+
+        instance_exec(&block)
+      end
+    ensure
+      @current_scope = previous_scope if block_given?
+    end
+
     # Excludes specified properties from the current scope by removing them
     # from the version's property set
     #

data/lib/verquest/base/public_class_methods.rb

@@ -12,7 +12,7 @@ module Verquest
     # @param version [String, nil] Specific version to use, defaults to configuration setting
     # @param validate [Boolean, nil] Whether to validate the params, defaults to configuration setting
     # @param remove_extra_root_keys [Boolean, nil] Whether to remove extra keys at the root level, defaults to configuration setting
-    # @return [Verquest::Result, Hash, Exception] When validation_error_handling is :result, returns a Success result with mapped params or Failure result with validation errors.
+    # @return [Verquest::Result, Hash] When validation_error_handling is :result, returns a Success result with mapped params or Failure result with validation errors.
     #   When validation_error_handling is :raise, returns mapped params directly or raises InvalidParamsError with validation errors.
     def process(params, version: nil, validate: nil, remove_extra_root_keys: nil)
       validate = Verquest.configuration.validate_params if validate.nil?
@@ -22,7 +22,7 @@ module Verquest
 
       params = params.dup
       params = params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
-      params = params.slice(*version_class.properties.keys) if remove_extra_root_keys
+      params = params.slice(*version_class.properties.keys) if remove_extra_root_keys && !version_class.combination?
 
       if validate && (validation_result = version_class.validate_params(params: params)) && validation_result.any?
         case Verquest.configuration.validation_error_handling
@@ -32,13 +32,22 @@ module Verquest
           Result.failure(validation_result)
         end
       else
-        mapped_params = version_class.map_params(params)
-
-        case Verquest.configuration.validation_error_handling
-        when :raise
-          mapped_params
-        when :result
-          Result.success(mapped_params)
+        begin
+          mapped_params = version_class.map_params(params)
+
+          case Verquest.configuration.validation_error_handling
+          when :raise
+            mapped_params
+          when :result
+            Result.success(mapped_params)
+          end
+        rescue MappingError => e
+          case Verquest.configuration.validation_error_handling
+          when :raise
+            raise
+          when :result
+            Result.failure([{message: e.message, type: "mapping_error"}])
+          end
         end
       end
     end

data/lib/verquest/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Verquest
   # Configuration for the Verquest gem
   #

data/lib/verquest/gem_version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verquest
-  GEM_VERSION = "0.6.1"
+  GEM_VERSION = "0.6.3"
 end

data/lib/verquest/helper_methods/required_properties.rb

@@ -20,7 +20,7 @@ module Verquest
       # by selecting those with their required attribute set to true (boolean).
       # Results are memoized to avoid recalculating on subsequent calls.
       #
-      # @return [Array<Symbol>] Names of properties marked as unconditionally required (required == true)
+      # @return [Array<String>] Names of properties marked as unconditionally required (required == true)
       def required_properties
         @_required_properties ||= properties.values.select { _1.required == true }.map(&:name)
       end

data/lib/verquest/properties/array.rb

@@ -72,8 +72,8 @@ module Verquest
       # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
-      # @param version [String, nil] The version to create mapping for, defaults to configuration setting
-      # @return [Hash] The updated mapping hash
+      # @param version [String, nil] The version to create mapping for
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/base.rb

@@ -49,7 +49,7 @@ module Verquest
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       # @raise [NoMethodError] This is an abstract method that must be overridden
       def mapping(key_prefix:, value_prefix:, mapping:, version:)
         raise NoMethodError

data/lib/verquest/properties/collection.rb

@@ -61,6 +61,22 @@ module Verquest
         !item.nil?
       end
 
+      # Check if this collection contains a oneOf property as its item type
+      #
+      # @return [Boolean] True if the collection contains a oneOf property
+      def has_one_of?
+        properties.values.size == 1 && properties.values.first.is_a?(Verquest::Properties::OneOf)
+      end
+
+      # Returns the oneOf property if this collection contains one
+      #
+      # @return [Verquest::Properties::OneOf, nil] The oneOf property or nil
+      def one_of_property
+        return nil unless has_one_of?
+
+        properties.values.first
+      end
+
       # Generate JSON schema definition for this collection property
       #
       # @return [Hash] The schema definition for this collection property
@@ -74,6 +90,13 @@ module Verquest
               }
             }.merge(schema_options)
           }
+        elsif has_one_of?
+          {
+            name => {
+              "type" => type,
+              "items" => one_of_property.to_schema[one_of_property.name] || one_of_property.to_schema
+            }.merge(schema_options)
+          }
         else
           {
             name => {
@@ -103,6 +126,14 @@ module Verquest
               "items" => item.to_validation_schema(version: version)
             }.merge(schema_options)
           }
+        elsif has_one_of?
+          one_of_schema = one_of_property.to_validation_schema(version: version)
+          {
+            name => {
+              "type" => type,
+              "items" => one_of_schema[one_of_property.name] || one_of_schema
+            }.merge(schema_options)
+          }
         else
           {
             name => {
@@ -122,13 +153,17 @@ module Verquest
 
       # Create mapping for this collection property and all its children
       #
-      # This method handles two different scenarios:
+      # This method handles three different scenarios:
       # 1. When the collection references an external item schema (`has_item?` returns true)
       #    - Creates mappings by transforming keys from the referenced item schema
       #    - Adds array notation ([]) to indicate this is a collection
       #    - Prefixes all keys and values with the appropriate paths
       #
-      # 2. When the collection has inline item properties
+      # 2. When the collection contains a oneOf property (`has_one_of?` returns true)
+      #    - Creates variant-keyed mappings for discriminator-less oneOf support
+      #    - Each variant gets array notation applied to its paths
+      #
+      # 3. When the collection has inline item properties
       #    - Creates mappings for each property in the collection items
       #    - Each property gets mapped with array notation and appropriate prefixes
       #
@@ -136,16 +171,20 @@ module Verquest
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version:)
         if has_item?
           value_key_prefix = mapping_value_key(value_prefix: value_prefix, collection: true)
 
           reference_mapping = item.mapping(version:).dup
-          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join("/")}[]/#{_1}" }
-          reference_mapping.transform_values! { "#{value_key_prefix}/#{_1}" }
+          reference_mapping.transform_keys! { |k| "#{(key_prefix + [name]).join("/")}[]/#{k}" }
+          reference_mapping.transform_values! { |v| "#{value_key_prefix}/#{v}" }
 
           mapping.merge!(reference_mapping)
+        elsif has_one_of?
+          one_of_mapping = {}
+          one_of_property.mapping(key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping: one_of_mapping, version:)
+          mapping.merge!(one_of_mapping)
         else
           properties.values.each do |property|
             property.mapping(key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping:, version:)

data/lib/verquest/properties/const.rb

@@ -36,11 +36,11 @@ module Verquest
 
       # Create mapping for this const property
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/enum.rb

@@ -48,11 +48,11 @@ module Verquest
 
       # Create mapping for this enum property
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/field.rb

@@ -68,11 +68,11 @@ module Verquest
 
       # Create mapping for this field property
       #
-      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param key_prefix [Array<String>] Prefix for the source key
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         mapping[(key_prefix + [name]).join("/")] = mapping_value_key(value_prefix:)
       end

data/lib/verquest/properties/object.rb

@@ -84,7 +84,7 @@ module Verquest
       # @param value_prefix [Array<String>] Prefix for the target value
       # @param mapping [Hash] The mapping hash to be updated
       # @param version [String, nil] The version to create mapping for
-      # @return [Hash] The updated mapping hash
+      # @return [void]
       def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
         properties.values.each do |property|
           property.mapping(key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), mapping:, version:)