rspec-json_api 1.4.0 → 1.6.0

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,58 @@
+# 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)
+        raise ArgumentError, "options must be a Hash, got #{options.class}" unless options.is_a?(Hash)
+
+        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,38 +23,62 @@ 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)
-          @actual = JSON.parse(actual, symbolize_names: true)
-          @diff = Diffy::Diff.new(expected, @actual, context: 5)
+          @diff = nil
+          @actual = actual
+          @type_error = !actual.is_a?(String)
+
+          return false if @type_error
 
-          return false unless @actual.instance_of?(expected.class)
+          @actual = JSON.parse(actual, symbolize_names: true)
 
-          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::SchemaMatch.match(@actual, expected)
+        rescue JSON::ParserError
+          @actual = actual
+          false
+        end
 
-            RSpec::JsonApi::CompareHash.compare(@actual, expected)
-          end
+        # A non-String actual is a mistake in the spec rather than a fact about the
+        # response, so the negated form has to fail rather than pass by default.
+        # @param actual [String] The JSON string to test against the expected schema.
+        # @return [Boolean] true if the actual JSON does not match the expected schema.
+        def does_not_match?(actual)
+          !matches?(actual) && !@type_error
         end
 
         # Provides a failure message for when the JSON data does not match the expected schema.
         # @return [String] A descriptive message detailing the mismatch between expected and actual JSON.
         def failure_message
+          return type_error_message if @type_error
+
           <<~MSG
             expected: #{expected}
                  got: #{actual}
 
             Diff:
-            #{@diff}
+            #{diff}
           MSG
         end
 
         # Provides a failure message for when the JSON data matches the expected schema, but it was expected not to.
         # This is used in negative matchers.
-        # @return [self] Returns itself, but typically this method should be implemented to return a descriptive message
+        # @return [String] A descriptive message indicating the JSON was expected not to match the schema.
         def failure_message_when_negated
+          return type_error_message if @type_error
+
           "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
+
+        def type_error_message
+          "expected a JSON String to match against the schema, got #{actual.class}"
+        end
       end
     end
   end

data/lib/rspec/json_api/schema_match.rb

@@ -0,0 +1,162 @@
+# 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 unless actual.is_a?(Hash)
+        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
+
+      # A schema Proc describes the constraints for a value; it is called without
+      # arguments and must return the option Hash. A Proc that expects the value
+      # as an argument is a common misreading of the DSL, and calling it here
+      # would raise a bare "wrong number of arguments" from deep in the matcher.
+      def compare_proc(actual_value, expected_value)
+        if declares_value_parameter?(expected_value)
+          raise ArgumentError,
+                "schema Proc must take no arguments; " \
+                "write -> { { lambda: ->(value) { ... } } } to test the value itself"
+        end
+
+        options = expected_value.call
+        raise ArgumentError, "schema Proc must return an options Hash, got #{options.class}" unless options.is_a?(Hash)
+
+        Constraints.match(actual_value, options)
+      end
+
+      # A non-lambda Proc reports its block parameters as optional, so
+      # `proc { |value| ... }` has to be caught on the parameter list rather
+      # than on arity. A bare splat states no expectation and is left alone.
+      def declares_value_parameter?(callable)
+        callable.parameters.any? { |type, _name| %i[req opt keyreq].include?(type) }
+      end
+
+      # A list schema only ever matches an actual Array. Without this guard the
+      # branches below call Array methods on whatever the response contained, so
+      # a null or a scalar where a list was expected raised NoMethodError
+      # instead of failing the match.
+      def compare_array(actual_value, expected_value)
+        return false unless actual_value.is_a?(Array)
+
+        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_values(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/uri.rb

@@ -3,7 +3,11 @@
 module RSpec
   module JsonApi
     module Types
-      URI = URI::DEFAULT_PARSER.make_regexp
+      # URI::DEFAULT_PARSER.make_regexp is unanchored, and comparison uses
+      # Regexp#match?, so on its own it accepts any string that merely contains
+      # a URI ("see https://example.com for details"). \A...\z holds the whole
+      # value to the pattern, the same way EMAIL and UUID already are anchored.
+      URI = /\A#{::URI::DEFAULT_PARSER.make_regexp}\z/
     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.6.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"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rspec-json_api
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Michal Gajowiak
-autorequire:
-bindir: exe
+bindir: bin
 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,47 +65,32 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 5.0.2
-description:
 email:
 - m.gajowiak@nomtek.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/main.yml"
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".ruby-version"
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
-- lib/extensions/array.rb
-- lib/extensions/hash.rb
 - 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
 - lib/rspec/json_api/version.rb
-- rspec-json_api.gemspec
 homepage: https://github.com/nomtek/rspec-json_api
 licenses:
 - MIT
@@ -115,7 +99,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 +113,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/.github/workflows/main.yml

@@ -1,20 +0,0 @@
-name: Ruby
-
-on: [push,pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: 3.2.2
-        bundler: 4.0.4
-    - name: Bundle gems
-      run: bundle install
-    - name: Run rspec
-      run: bundle exec rspec
-    - name: Run rubocop
-      run: bundle exec rubocop

data/.gitignore

@@ -1,11 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,50 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.2
-  NewCops: enable
-  SuggestExtensions: false
-  Exclude:
-    - "README.md"
-
-Style/StringLiterals:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Layout/LineLength:
-  Max: 120
-
-Metrics/BlockLength:
-  Exclude:
-    - "spec/**/*_spec.rb"
-
-Metrics/MethodLength:
-  Exclude:
-    - "lib/rspec/json_api/compare_hash.rb"
-    - "lib/extensions/hash.rb"
-
-Metrics/AbcSize:
-  Exclude:
-    - "lib/rspec/json_api/compare_hash.rb"
-    - "lib/rspec/json_api/matchers/match_json_schema.rb"
-
-Metrics/CyclomaticComplexity:
-  Exclude:
-    - "lib/rspec/json_api/compare_hash.rb"
-
-Metrics/PerceivedComplexity:
-  Exclude:
-    - "lib/rspec/json_api/compare_hash.rb"
-
-Style/Documentation:
-  Enabled: false
-
-Naming/PredicatePrefix:
-  Exclude:
-    - "lib/rspec/json_api/matchers.rb"
-
-Naming/PredicateMethod:
-  Exclude:
-    - "lib/rspec/json_api/compare_hash.rb"

data/.ruby-version

@@ -1 +0,0 @@
-3.2.2