rspec-json_api 1.4.0 → 1.5.0

data/lib/generators/rspec/json_api/interface/interface_generator.rb

@@ -8,12 +8,14 @@ module Rspec
 
         def copy_interface_file
           create_file "spec/rspec/json_api/interfaces/#{file_name}.rb", <<~FILE
+            # frozen_string_literal: true
+
             module RSpec
               module JsonApi
                 module Interfaces
                   #{file_name.upcase} = {
                     # name: String
-                  }
+                  }.freeze
                 end
               end
             end

data/lib/generators/rspec/json_api/type/type_generator.rb

@@ -1,23 +1,25 @@
-# frozen_string_literal: true
-
-module Rspec
-  module JsonApi
-    module Generators
-      class TypeGenerator < Rails::Generators::NamedBase
-        source_root File.expand_path("templates", __dir__)
-
-        def copy_type_file
-          create_file "spec/rspec/json_api/types/#{file_name}.rb", <<~FILE
-            module RSpec
-              module JsonApi
-                module Types
-                  #{file_name.upcase} = //
-                end
-              end
-            end
-          FILE
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Rspec
+  module JsonApi
+    module Generators
+      class TypeGenerator < Rails::Generators::NamedBase
+        source_root File.expand_path("templates", __dir__)
+
+        def copy_type_file
+          create_file "spec/rspec/json_api/types/#{file_name}.rb", <<~FILE
+            # frozen_string_literal: true
+
+            module RSpec
+              module JsonApi
+                module Types
+                  #{file_name.upcase} = //
+                end
+              end
+            end
+          FILE
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_api/constraints.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RSpec
+  module JsonApi
+    # Constraints evaluates the option hash produced by a schema Proc
+    # (e.g. `-> { { type: Integer, min: 1, max: 10, allow_blank: true } }`)
+    # against an actual value.
+    #
+    # allow_blank is a modifier, not a constraint of its own: when it is true a
+    # blank value is accepted and the remaining options are skipped; otherwise
+    # the value is checked against every other option.
+    module Constraints
+      module_function
+
+      SUPPORTED_OPTIONS = %i[allow_blank type value min max inclusion regex lambda].freeze
+
+      # @param value [Object] the actual value being matched.
+      # @param options [Hash] the option hash returned by the schema Proc.
+      # @return [Boolean] true when the value satisfies the options.
+      # @raise [ArgumentError] when an option key is not supported.
+      def match(value, options)
+        validate!(options)
+
+        return true if value.blank? && options[:allow_blank]
+
+        options.except(:allow_blank).all? do |option, condition|
+          satisfies?(value, option, condition)
+        end
+      end
+
+      def validate!(options)
+        unknown = options.keys - SUPPORTED_OPTIONS
+        return if unknown.empty?
+
+        raise ArgumentError, "Unsupported match option(s): #{unknown.join(", ")}"
+      end
+
+      def satisfies?(value, option, condition)
+        case option
+        when :type      then value.instance_of?(condition)
+        when :value     then value == condition
+        when :inclusion then condition.include?(value)
+        when :regex     then condition.match?(value.to_s)
+        when :lambda    then condition.call(value)
+        when :min, :max then within_bound?(value, option, condition)
+        end
+      end
+
+      def within_bound?(value, option, condition)
+        return false unless value.is_a?(Numeric) && condition.is_a?(Numeric)
+
+        option == :min ? value >= condition : value <= condition
+      end
+    end
+  end
+end

data/lib/rspec/json_api/matchers/match_json_schema.rb

@@ -23,18 +23,13 @@ module RSpec
         # @param actual [String] The JSON string to test against the expected schema.
         # @return [Boolean] true if the actual JSON matches the expected schema, false otherwise.
         def matches?(actual)
+          @diff = nil
           @actual = JSON.parse(actual, symbolize_names: true)
-          @diff = Diffy::Diff.new(expected, @actual, context: 5)
 
-          return false unless @actual.instance_of?(expected.class)
-
-          if expected.instance_of?(Array)
-            RSpec::JsonApi::CompareArray.compare(@actual, expected)
-          else
-            return false unless @actual.deep_keys.deep_sort == expected.deep_keys.deep_sort
-
-            RSpec::JsonApi::CompareHash.compare(@actual, expected)
-          end
+          RSpec::JsonApi::SchemaMatch.match(@actual, expected)
+        rescue JSON::ParserError
+          @actual = actual
+          false
         end
 
         # Provides a failure message for when the JSON data does not match the expected schema.
@@ -45,7 +40,7 @@ module RSpec
                  got: #{actual}
 
             Diff:
-            #{@diff}
+            #{diff}
           MSG
         end
 
@@ -55,6 +50,14 @@ module RSpec
         def failure_message_when_negated
           "expected the JSON data not to match the provided schema, but it did."
         end
+
+        private
+
+        # The diff is only needed to render a failure message, so it is built
+        # lazily and memoized rather than on every matches? call.
+        def diff
+          @diff ||= Diffy::Diff.new(expected, actual, context: 5)
+        end
       end
     end
   end

data/lib/rspec/json_api/schema_match.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module RSpec
+  module JsonApi
+    # SchemaMatch compares parsed JSON (a Hash, an Array, or a scalar) against an
+    # expected schema. It is the single entry point behind the match_json_schema
+    # matcher: callers hand it the actual and expected values and it dispatches on
+    # shape internally, so the matcher does not need to know whether it is looking
+    # at an object or a collection.
+    module SchemaMatch
+      module_function
+
+      # Top-level comparison. Applies the shape guards (class equality and, for
+      # objects, key-set equality) before recursing.
+      def match(actual, expected)
+        return false unless actual.instance_of?(expected.class)
+
+        case expected
+        when Array
+          compare_array(actual, expected)
+        when Hash
+          return false unless same_key_structure?(actual, expected)
+
+          compare(actual, expected)
+        else
+          compare_simple_value(actual, expected)
+        end
+      end
+
+      def same_key_structure?(actual, expected)
+        Traversal.deep_sort(Traversal.deep_keys(actual)) ==
+          Traversal.deep_sort(Traversal.deep_keys(expected))
+      end
+
+      def compare(actual, expected)
+        return false if actual.blank? && expected.present?
+
+        keys = Traversal.deep_key_paths(expected) | Traversal.deep_key_paths(actual)
+
+        compare_key_paths_and_values(keys, actual, expected)
+      end
+
+      def compare_key_paths_and_values(keys, actual, expected)
+        keys.all? do |key_path|
+          actual_value = dig_path(actual, key_path)
+          expected_value = dig_path(expected, key_path)
+
+          compare_values(actual_value, expected_value)
+        end
+      end
+
+      # Digs a key path without raising when an intermediate value is not a Hash.
+      # Plain Hash#dig raises TypeError if it walks into a scalar (e.g. a schema
+      # expects a nested object but the actual value is a String), so a mismatch
+      # would crash instead of failing the match.
+      def dig_path(data, key_path)
+        key_path.reduce(data) do |value, key|
+          break nil unless value.is_a?(Hash)
+
+          value[key]
+        end
+      end
+
+      def compare_values(actual_value, expected_value)
+        case expected_value
+        when Class  then compare_class(actual_value, expected_value)
+        when Regexp then compare_regexp(actual_value, expected_value)
+        when Proc   then compare_proc(actual_value, expected_value)
+        when Array  then compare_array(actual_value, expected_value)
+        else             compare_simple_value(actual_value, expected_value)
+        end
+      end
+
+      def compare_class(actual_value, expected_value)
+        actual_value.instance_of?(expected_value)
+      end
+
+      def compare_regexp(actual_value, expected_value)
+        expected_value.match?(actual_value.to_s)
+      end
+
+      def compare_proc(actual_value, expected_value)
+        Constraints.match(actual_value, expected_value.call)
+      end
+
+      def compare_array(actual_value, expected_value)
+        if simple_type?(expected_value)
+          compare_typed_array(actual_value, expected_value)
+        elsif interface?(expected_value)
+          compare_interface_array(actual_value, expected_value)
+        else
+          compare_exact_array(actual_value, expected_value)
+        end
+      end
+
+      # [SomeClass] => every element must be an instance of SomeClass.
+      def compare_typed_array(actual_value, expected_value)
+        type = expected_value[0]
+
+        actual_value.all? { |elem| compare_class(elem, type) }
+      end
+
+      # [{ ...interface... }] => every element must match the single interface.
+      # Elements go through match (not compare) so each one is held to the same
+      # key-structure guard as a top-level object; otherwise an element with an
+      # extra null-valued key would slip through (nil == nil).
+      def compare_interface_array(actual_value, expected_value)
+        interface = expected_value[0]
+
+        actual_value.all? { |elem| match(elem, interface) }
+      end
+
+      # Any other array => element-by-element match, sizes must be equal.
+      def compare_exact_array(actual_value, expected_value)
+        return false if actual_value&.size != expected_value&.size
+
+        expected_value.each_with_index.all? do |elem, index|
+          elem.is_a?(Hash) ? compare(actual_value[index], elem) : compare_simple_value(actual_value[index], elem)
+        end
+      end
+
+      def compare_simple_value(actual_value, expected_value)
+        actual_value == expected_value
+      end
+
+      def simple_type?(expected_value)
+        expected_value.size == 1 && expected_value[0].instance_of?(Class)
+      end
+
+      def interface?(expected_value)
+        expected_value.size == 1 && expected_value[0].is_a?(Hash)
+      end
+    end
+  end
+end

data/lib/rspec/json_api/traversal.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RSpec
+  module JsonApi
+    # Traversal holds the structural helpers used to compare JSON shapes:
+    # collecting the nested key structure of a Hash and sorting it into a
+    # canonical order. These were previously monkey-patched onto core Hash and
+    # Array; keeping them here means the gem no longer mutates those classes in
+    # the host application.
+    module Traversal
+      module_function
+
+      # The nested keys of a hash, with each nested hash's keys inlined as an
+      # array, e.g. { a: 1, b: { c: 2 } } => [:a, :b, [:c]].
+      def deep_keys(hash)
+        hash.each_with_object([]) do |(key, value), keys|
+          keys << key
+          keys << deep_keys(value) if value.respond_to?(:keys)
+        end
+      end
+
+      # Every leaf key path of a hash, e.g. { a: { b: 1 }, c: 2 } => [[:a, :b], [:c]].
+      def deep_key_paths(hash)
+        stack = hash.map { |key, value| [[key], value] }
+        key_map = []
+
+        until stack.empty?
+          key, value = stack.pop
+
+          key_map << key unless value.is_a?(Hash)
+
+          next unless value.is_a?(Hash)
+
+          value.each { |k, v| stack.push([key.dup << k, v]) }
+        end
+
+        key_map.reverse
+      end
+
+      # Recursively sorts an array (and any nested arrays) into a canonical order
+      # so two key structures can be compared regardless of original order.
+      def deep_sort(array)
+        array
+          .map { |element| element.is_a?(Array) ? deep_sort(element) : element }
+          .sort_by { |element| element.is_a?(Array) ? element.first.to_s : element.to_s }
+      end
+    end
+  end
+end

data/lib/rspec/json_api/types/uuid.rb

@@ -3,7 +3,7 @@
 module RSpec
   module JsonApi
     module Types
-      UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
+      UUID = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/
     end
   end
 end

data/lib/rspec/json_api/version.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
-module RSpec
-  module JsonApi
-    VERSION = "1.4.0"
-  end
-end
+# frozen_string_literal: true
+
+module RSpec
+  module JsonApi
+    VERSION = "1.5.0"
+  end
+end

data/lib/rspec/json_api.rb

@@ -1,25 +1,23 @@
-# frozen_string_literal: true
-
-# Load 3rd party libraries
-require "json"
-require "diffy"
-require "active_support/core_ext/object/blank"
-
-# Load the json_api parts
-require "rspec/json_api/version"
-require "rspec/json_api/compare_hash"
-require "rspec/json_api/compare_array"
-
-# Load extensions
-require "extensions/hash"
-require "extensions/array"
-
-# Load matchers
-require "rspec/json_api/matchers"
-require "rspec/json_api/matchers/match_json_schema"
-require "rspec/json_api/matchers/have_no_content"
-
-# Load defined types
-require "rspec/json_api/types/email"
-require "rspec/json_api/types/uri"
-require "rspec/json_api/types/uuid"
+# frozen_string_literal: true
+
+# Load 3rd party libraries
+require "json"
+require "uri"
+require "diffy"
+require "active_support/core_ext/object/blank"
+
+# Load the json_api parts
+require "rspec/json_api/version"
+require "rspec/json_api/traversal"
+require "rspec/json_api/constraints"
+require "rspec/json_api/schema_match"
+
+# Load matchers
+require "rspec/json_api/matchers"
+require "rspec/json_api/matchers/match_json_schema"
+require "rspec/json_api/matchers/have_no_content"
+
+# Load defined types
+require "rspec/json_api/types/email"
+require "rspec/json_api/types/uri"
+require "rspec/json_api/types/uuid"

data/rspec-json_api.gemspec

@@ -1,38 +1,42 @@
-# frozen_string_literal: true
-
-require_relative "lib/rspec/json_api/version"
-
-Gem::Specification.new do |spec|
-  spec.name          = "rspec-json_api"
-  spec.version       = RSpec::JsonApi::VERSION
-  spec.authors       = ["Michal Gajowiak"]
-  spec.email         = ["m.gajowiak@nomtek.com"]
-
-  spec.summary       = "RSpec extension to test JSON API response."
-  spec.homepage      = "https://github.com/nomtek/rspec-json_api"
-  spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/nomtek/rspec-json_api"
-  spec.metadata["changelog_uri"] = "https://github.com/nomtek/rspec-json_api/blob/master/CHANGELOG.md"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Uncomment to register a new dependency of your gem
-  spec.add_dependency "activesupport", ">= 6.1.4.1"
-  spec.add_dependency "diffy", ">= 3.4.2"
-  spec.add_dependency "rails", ">= 6.1.4.1"
-  spec.add_dependency "rspec-rails", ">= 5.0.2"
-
-  # For more information and examples about making a new gem, checkout our
-  # guide at: https://bundler.io/guides/creating_gem.html
-end
+# frozen_string_literal: true
+
+require_relative "lib/rspec/json_api/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rspec-json_api"
+  spec.version       = RSpec::JsonApi::VERSION
+  spec.authors       = ["Michal Gajowiak"]
+  spec.email         = ["m.gajowiak@nomtek.com"]
+
+  spec.summary       = "RSpec extension to test JSON API response."
+  spec.homepage      = "https://github.com/nomtek/rspec-json_api"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/nomtek/rspec-json_api"
+  spec.metadata["changelog_uri"] = "https://github.com/nomtek/rspec-json_api/blob/master/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies. The gem only needs ActiveSupport's blank?/present?
+  # core extensions and Rails::Generators (which lives in railties); depending
+  # on the full "rails" meta-gem would force ActiveRecord, ActionCable,
+  # ActionMailer, ActionMailbox, ActiveStorage, ActionText, etc. on every
+  # consumer of a JSON-matcher gem. The >= 6.1.4.1 floor is unchanged.
+  spec.add_dependency "activesupport", ">= 6.1.4.1"
+  spec.add_dependency "diffy", ">= 3.4.2"
+  spec.add_dependency "railties", ">= 6.1.4.1"
+  spec.add_dependency "rspec-rails", ">= 5.0.2"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rspec-json_api
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Michal Gajowiak
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -39,7 +38,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 3.4.2
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,13 +65,13 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 5.0.2
-description:
 email:
 - m.gajowiak@nomtek.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitattributes"
 - ".github/workflows/main.yml"
 - ".gitignore"
 - ".rspec"
@@ -87,21 +86,24 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- lib/extensions/array.rb
-- lib/extensions/hash.rb
+- gemfiles/rails_6_1.gemfile
+- gemfiles/rails_7_1.gemfile
+- gemfiles/rails_7_2.gemfile
+- gemfiles/rails_8_0.gemfile
+- gemfiles/rails_8_1.gemfile
 - lib/generators/rspec/json_api/install/install_generator.rb
 - lib/generators/rspec/json_api/install/templates/rspec/json_api/interfaces/.empty_directory
 - lib/generators/rspec/json_api/install/templates/rspec/json_api/types/.empty_directory
 - lib/generators/rspec/json_api/interface/interface_generator.rb
-- lib/generators/rspec/json_api/interface/templates/interface.erb
 - lib/generators/rspec/json_api/type/type_generator.rb
 - lib/rspec/json_api.rb
-- lib/rspec/json_api/compare_array.rb
-- lib/rspec/json_api/compare_hash.rb
+- lib/rspec/json_api/constraints.rb
 - lib/rspec/json_api/interfaces/example_interface.rb
 - lib/rspec/json_api/matchers.rb
 - lib/rspec/json_api/matchers/have_no_content.rb
 - lib/rspec/json_api/matchers/match_json_schema.rb
+- lib/rspec/json_api/schema_match.rb
+- lib/rspec/json_api/traversal.rb
 - lib/rspec/json_api/types/email.rb
 - lib/rspec/json_api/types/uri.rb
 - lib/rspec/json_api/types/uuid.rb
@@ -115,7 +117,6 @@ metadata:
   source_code_uri: https://github.com/nomtek/rspec-json_api
   changelog_uri: https://github.com/nomtek/rspec-json_api/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -130,8 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: RSpec extension to test JSON API response.
 test_files: []

data/lib/extensions/array.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-class Array
-  def deep_sort
-    map { |element| element.is_a?(Array) ? element.deep_sort : element }
-      .sort_by { |el| el.is_a?(Array) ? el.first.to_s : el.to_s }
-  end
-end

data/lib/extensions/hash.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-# Extension methods for hash class
-class Hash
-  def deep_keys
-    each_with_object([]) do |(k, v), keys|
-      keys << k
-      keys << v.deep_keys if v.respond_to?(:keys)
-    end
-  end
-
-  def deep_key_paths
-    stack = map { |k, v| [[k], v] }
-    key_map = []
-
-    until stack.empty?
-      key, value = stack.pop
-
-      key_map << key unless value.is_a? Hash
-
-      next unless value.is_a? Hash
-
-      value.map do |k, v|
-        stack.push [key.dup << k, v]
-      end
-    end
-
-    key_map.reverse
-  end
-
-  def sanitize!(keys)
-    keep_if do |k, _v|
-      keys.include?(k)
-    end
-  end
-end

data/lib/generators/rspec/json_api/interface/templates/interface.erb

@@ -1,9 +0,0 @@
-<%= module RSpec %>
-  <%= module JsonApi %>
-    <%= module Interfaces %>
-      <%= const_set(file_name, {
-
-      }.freeze) %>
-    <%= end %>
-  <%= end %>
-<%= end %>