rspec-json_api 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6be977d812080cea5feea8a9c9a0a429196c43c06b2aa64e0e742a44e0eb66fd
-  data.tar.gz: 77d21174747915fb1c33607eb331e4cfbd8ae9ed9dfa13936bd1cf2436de41af
+  metadata.gz: 1af83b52a7a2a283b8f88e3d35920a6a5222fe10ec786a7a7f09f509ee923b75
+  data.tar.gz: 7772ea842f6e73370494969b5f5ad867ef0cb67f77449a95607b71190fd37545
 SHA512:
-  metadata.gz: ea7471b8cb4ed9e871917ec51f61426931c765f2c0c46f4bd0c2c5291b3af1fecd855646847897608eace564f734337d34290551b7fca82181b37f9a2eb856da
-  data.tar.gz: ef41fe2e7c32dfc6b605cfce7f847ef48a7c0f84878c32ca72178923a0f53e6f556541ef5d28cddb1cd795dc061be7016fa7970266ef369b3f0c693ffb41d9e7
+  metadata.gz: 7bd1537b2ea54021789bc2bf2d9ace9df346c2a75ee1d3183eafd6ca0aaebfa332b534f233047605bb252cc0afb76e35d9e7e26d97c921cbc44f321760ef1fe9
+  data.tar.gz: 6a2161022a3bff6d5af28398653289eaee7be1e3cc27cddeedd74cffaeb644a7e2548c6e5e04891e211c826a68b6c0d0de2cf7d98253459b0bc90d35e7ca126c

data/CHANGELOG.md

@@ -1,9 +1,56 @@
-## [Unreleased]
+## [2.0.0] - 2026-09-14
+
+### Fixed
+- Exact arrays enforce full key structure for Hash elements. Extra null-valued keys and missing keys that happen to accept blank values no longer pass inside tuples.
+- Nested key checks preserve each key's parent association. Objects with the same nested key names attached to different parents no longer match when the affected values are `null`.
+- Regexp schemas require a String value instead of matching `to_s`. Numeric values and `null` no longer satisfy permissive regular expressions.
+
+### Changed
+- Removed ActiveSupport blank/present core extensions in favor of a JSON-focused internal helper with the same relevant semantics.
+- Runtime dependencies are now only `diffy` and `rspec-expectations`. Rails, Railties, ActiveSupport, and `rspec-rails` are no longer installed for matcher-only consumers. Projects using the optional generators must provide Rails themselves.
+- The compatibility matrix tests matcher behavior without Rails on Ruby 3.2, 3.3, 3.4, and 4.0. Separate generator jobs exercise Rails 6.1 and Rails 8.1 at the supported boundaries.
+- The README now documents strict key behavior, schema dispatch, errors, array shorthand, supported runtimes, and the fact that this is a general JSON shape matcher rather than a JSON:API implementation.
+- CI runs `actions/checkout@v7`, up from v5, alongside `ruby/setup-ruby@v1`. Both track their major tag, so upstream patch releases arrive without a commit here and Dependabot opens a pull request for each new major. Checkout also runs with `persist-credentials: false`: no step needs git credentials, and bundler evaluates gemspec and native-extension code from the branch under test.
+- The workflow runs once per change rather than twice. `push` is scoped to `master`, so a branch with an open pull request no longer builds under both events, and a `concurrency` group cancels superseded pull request runs. Runs on `master` are left alone, so every commit there keeps a result.
+- `rubocop` and `bundler-audit` share one job definition instead of two byte-identical ones, and every job carries `timeout-minutes: 30` in place of the six-hour default.
+
+### Added
+- Top-level Class and Regexp schemas now work for scalar JSON documents, using the same dispatch rules as nested values.
+- `match_json_schema` exposes an RSpec description for one-line and documentation formatter output.
+- Direct unit coverage for schema matching, traversal, constraints, and the Rails generators; randomized spec ordering; Ruby warnings; and a 90% SimpleCov floor.
+- Contributor and security policy documents, included in the packaged gem.
+- A weekly `schedule` trigger, so `bundler-audit` reports an advisory published against a lockfile nobody has touched. Only the audit runs on that trigger. `workflow_dispatch` runs it on demand and is also how the cron is re-armed, since GitHub disables scheduled workflows after 60 days without repository activity.
+
+### Removed
+- The internal example interface fixture from the packaged library; it now lives under test support.
+- Redundant Rails 7.1, 7.2, and 8.0 appraisal files after reducing generator compatibility checks to the supported boundaries.
+
+## [1.6.0] - 2026-09-03
+
+### Fixed
+- A list schema (`[String]`, `[INTERFACE]`) fails the match instead of raising `NoMethodError` when the response holds `null` or a scalar where an array was expected. This affected nested lists too, so an interface element with a scalar in place of a list crashed the example.
+- `Types::URI` is anchored with `\A...\z`. It previously accepted any value that merely contained a URI, so `"see https://example.com for details"` matched. `EMAIL` and `UUID` were already anchored. Suites that relied on the substring behaviour will start failing.
+- `match_json_schema` fails with `expected a JSON String to match against the schema, got NilClass` instead of raising `TypeError` when handed `nil`, an already-parsed Hash, or any other non-String.
+- A schema `Proc` that returns something other than an options Hash, or that expects the value as an argument, raises a descriptive `ArgumentError` naming the mistake. Both previously surfaced as a bare `NoMethodError` or `wrong number of arguments` from inside the matcher.
+- An object schema compared against array elements of another shape (`[{ id: Integer }]` against `["a", "b"]`) fails instead of raising `NoMethodError`. This is the same class of bug as the list-schema crash above, on the object comparison path.
+- `expect(body).not_to match_json_schema(schema)` fails when the body is not a JSON String, rather than passing by default. A type error in the spec is now a failure whichever way the expectation is written.
+- A non-lambda `proc { |value| ... }` used as a schema Proc is rejected alongside the lambda form. Ruby reports a non-lambda block parameter as optional, so the check reads the parameter list rather than the arity; a Proc declaring an optional parameter is rejected for the same reason.
+- The `have_no_content` specs gave every body its own context. A repeated `let(:actual)` in one context meant the `"{}"` case never ran.
+
+### Changed
+- The released gem contains the tracked files under `lib/` plus the licence, the README and the CHANGELOG, and nothing else. It previously packaged the repository's own tooling: the CI workflow, the RuboCop config, the Gemfile and lockfile, the Rakefile, `bin/` and `gemfiles/`. Scoping the file list to tracked paths also keeps an untracked local file in `lib/` out of a release.
+- README regex examples anchor with `\A` and `\z` instead of `^` and `$`, with a note explaining that the line-boundary anchors let a multi-line value satisfy a schema.
+- Updated the locked development dependencies past every advisory `bundler-audit` reported: rack, nokogiri, railties, activesupport, concurrent-ruby, loofah, crass, erb, json, rails-html-sanitizer and rack-session.
+
+### Added
+- Exact-array schemas dispatch each element the same way any other schema value is dispatched, so `[Integer, Integer]` is a fixed-length tuple and `[RSpec::JsonApi::Types::URI]` type-checks its single element. Elements were previously compared with `==`, so a Class, Regexp or Proc in that position could never match.
+- A `bundler-audit` job in CI, a Dependabot config for bundler and github-actions, and `permissions: contents: read` on the workflow.
+- `ROADMAP.md`, the prioritised findings from a full review of the codebase.
 
 ## [1.5.0] - 2026-06-05
 
 ### Added
-- CI compatibility matrix across Ruby 3.2–3.4 and Rails 6.1, 7.1, 7.2, 8.0 and 8.1 (`gemfiles/` + GitHub Actions matrix), so the advertised version support is actually tested.
+- CI compatibility matrix across Ruby 3.2-3.4 and Rails 6.1, 7.1, 7.2, 8.0 and 8.1 (`gemfiles/` + GitHub Actions matrix), so the advertised version support is actually tested.
 - `RSpec::JsonApi::Constraints` module encapsulating the schema `Proc` options DSL.
 - `RSpec::JsonApi::SchemaMatch` as the single comparison entry point, and `RSpec::JsonApi::Traversal` for the internal structural helpers.
 

data/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Bug reports and pull requests are welcome.
+
+## Setup
+
+Use the Ruby version declared in `.ruby-version` and Bundler 4.0.4:
+
+```sh
+gem install bundler -v 4.0.4
+bundle install
+```
+
+Run the local checks before opening a pull request:
+
+```sh
+bundle exec rspec
+bundle exec rubocop
+bundle exec bundle-audit check --update
+```
+
+Matcher changes should include focused examples under `spec/rspec/json_api`. Generator changes should include examples under `spec/generators` and be checked against both appraisal gemfiles.
+
+Keep pull requests focused and explain user-visible behavior changes in `CHANGELOG.md`. By participating, you agree to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/README.md

@@ -1,319 +1,226 @@
 # RSpec::JsonApi
 
-[RSpec:JsonAPI](https://github.com/nomtek/rspec-json_api) 
-is an extension for [RSpec](https://github.com/rspec) 
-to easily allow testing JSON API responses.
+`rspec-json_api` adds RSpec matchers for checking JSON values against compact Ruby schemas. Despite the name, it validates general JSON response shapes; it does not implement the [JSON:API specification](https://jsonapi.org/).
+
+## Requirements
+
+- Ruby 3.2 or newer
+- RSpec 3
+- Rails 6.1 or newer only when using the optional generators
+
+The CI suite covers matcher behavior on Ruby 3.2, 3.3, 3.4, and 4.0. Generator integration is exercised at the supported Rails boundaries: Rails 6.1 on Ruby 3.2 and Rails 8.1 on Ruby 3.4.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your test group:
 
 ```ruby
-gem 'rspec-json_api'
+group :test do
+  gem "rspec-json_api"
+end
 ```
 
-And then execute:
+Then run:
 
-    $ bundle install
+```sh
+bundle install
+```
+
+Load the matchers from `spec/spec_helper.rb` (or your equivalent RSpec setup file):
 
-Or install it yourself as:
+```ruby
+require "rspec/json_api"
+```
 
-    $ gem install rspec-json_api
+Rails projects can generate the definition directories:
 
-Generate directory tree:
+```sh
+rails generate rspec:json_api:install
+```
 
-    rails generate rspec:json_api:install
+Load custom types before interfaces in `rails_helper.rb`, because interfaces may reference types:
 
-Require gem assets in your `rails_helper.rb`
 ```ruby
-Dir[File.join(__dir__, 'rspec', 'json_api', 'types', '*.rb')].each { |file| require file }
-Dir[File.join(__dir__, 'rspec', 'json_api', 'interfaces', '*.rb')].each { |file| require file }
+Dir[File.join(__dir__, "rspec", "json_api", "types", "*.rb")].each { |file| require file }
+Dir[File.join(__dir__, "rspec", "json_api", "interfaces", "*.rb")].each { |file| require file }
 ```
 
-## Generators
+The matchers themselves do not depend on Rails, ActiveSupport, or `rspec-rails`.
 
-Using build-in generators it's possible to create custom interface and type.
+## Matchers
 
-Generate new template:
+### `match_json_schema`
 
-    rails generate rspec:json_api:interface interface-name
+Pass the matcher a JSON String and describe the parsed value with Ruby values, classes, regular expressions, arrays, hashes, or constraint Procs:
 
-Generate new type:
+```ruby
+schema = {
+  id: RSpec::JsonApi::Types::UUID,
+  name: String,
+  age: -> { { type: Integer, min: 18 } },
+  tags: [String]
+}
 
-    rails generate rspec:json_api:type type-name
+expect(response.body).to match_json_schema(schema)
+```
 
+The actual value must be a JSON String. Invalid JSON and non-String inputs fail the match. Schema keys must be symbols because JSON object keys are symbolized while parsing.
 
-## Example usage
+Object schemas are strict at every nesting level: every expected key must be present and unexpected keys fail the match. `allow_blank` permits a blank value; it does not make a key optional.
+
+Root schemas may describe objects, arrays, or scalar JSON values:
 
 ```ruby
-# spec/controllers/users_controller_spec.rb
+expect('"ready"').to match_json_schema(String)
+expect('"ready"').to match_json_schema(/\Aready\z/)
+expect("42").to match_json_schema(42)
+```
 
-RSpec.describe UsersController, type: :controller do
-  describe '#index' do
-    let(:expected_schema) do
-      [{
-        id: RSpec::JsonApi::Types::UUID,
-        name: String,
-        age: Integer,
-        favoriteColorHex: /^\#([a-fA-F]|[0-9]){3,6}$/,
-        number: -> { { type: Integer, min: 10, max: 20, lambda: lambda(&:even?) } }
-      }]
-    end
+### `have_no_content`
 
-    it 'matches API response' do
-      get :index
+`have_no_content` matches only an empty String:
 
-      expect(response.body).to match_json_schema(expected_schema)
-    end
-  end
-  
-  describe '#update' do
-    it 'matches API response' do
-      put :update, params: { name: 'John', age: 35 }
-      
-      expect(response.body).to have_no_content
-    end
-  end
-end
+```ruby
+expect(response.body).to have_no_content
 ```
 
-## Built-in matchers
-- ### match_json_schema
-```
-  expect(response.body).to match_json_schema(expected_schema)
-```
+JSON objects, JSON arrays, and whitespace-only bodies are considered content.
 
-- ### have_no_content
-```
-  expect(response.body).to have_no_content
+## Schema Values
+
+### Exact values
+
+```ruby
+schema = { status: "ready", count: 2 }
 ```
 
-## Interfaces
-The gem introduces interfaces to reuse them during test matches.
+### Classes
+
+Classes use `instance_of?`, so subclasses do not match:
 
 ```ruby
-# spec/rspec/json_api/interfaces/example_interface.rb
+schema = { id: Integer, name: String }
+```
 
-module RSpec
-  module JsonApi
-    module Interfaces
-      EXAMPLE_INTERFACE = {
-        id: Types::UUID,
-        name: String,
-        number: Integer,
-        color: -> { { inclusion: %w[black red white], allow_blank: true } }
-      }.freeze
-    end
-  end
-end
+### Regular expressions
+
+A regular expression matches only a JSON String. Numbers, booleans, and `null` do not match after conversion:
+
+```ruby
+schema = { color: /\A#[0-9a-fA-F]{6}\z/ }
 ```
-_Note: You can either generate file on your own or use generator._
-## Types
 
-The gem allow users either to user build-in types or define owns. 
-### Build-in types
-- #### EMAIL
+Use `\A` and `\z` for whole-string validation. Ruby's `^` and `$` are line anchors and may accept a matching line inside a multiline value.
+
+### Arrays
+
+Array schemas have three forms:
+
 ```ruby
-RSpec::JsonApi::Types::EMAIL
+[String]                         # any-length list of Strings
+[{ id: Integer, name: String }] # any-length list of this object shape
+[Integer, String]               # an exact two-element tuple
 ```
-- #### URI
+
+The one-element shorthand applies only to a Class or Hash. For example, `[Types::UUID]` means an exact one-element array because `Types::UUID` is a Regexp.
+
+### Constraint Procs
+
+A constraint Proc takes no arguments and returns an options Hash:
+
 ```ruby
-RSpec::JsonApi::Types::URI
+schema = {
+  age: -> { { type: Integer, min: 18, max: 120 } },
+  role: -> { { inclusion: %w[admin member] } },
+  code: -> { { regex: /\A[A-Z]{3}\z/ } },
+  even: -> { { lambda: ->(value) { value.even? } } },
+  nickname: -> { { type: String, allow_blank: true } }
+}
 ```
-- #### UUID
+
+Supported options are `allow_blank`, `type`, `value`, `min`, `max`, `inclusion`, `regex`, and `lambda`. All supplied constraints must pass. Unknown options, a non-Hash return value, or a Proc that declares an argument raises `ArgumentError` with usage guidance.
+
+`allow_blank: true` accepts `null`, `false`, empty strings, whitespace-only strings, empty arrays, and empty objects. The key itself remains required.
+
+## Built-in Types
+
+The built-in types are anchored regular expressions:
+
 ```ruby
+RSpec::JsonApi::Types::EMAIL
+RSpec::JsonApi::Types::URI
 RSpec::JsonApi::Types::UUID
 ```
 
+`URI` accepts schemes supported by Ruby's standard URI parser, not only HTTP and HTTPS.
 
-Custom type example:
-```ruby
-# spec/rspec/json_api/types/color_hex.rb
+Generate a custom type with Rails:
+
+```sh
+rails generate rspec:json_api:type color_hex
+```
+
+Or define one directly:
 
+```ruby
 module RSpec
   module JsonApi
     module Types
-      COLOR_HEX = /^#(?:[0-9a-fA-F]{3}){1,2}$/
+      COLOR_HEX = /\A#(?:[0-9a-fA-F]{3}){1,2}\z/
     end
   end
 end
-
-RSpec::JsonApi::Types::COLOR_HEX
 ```
 
-_Note: You can either generate file on your own or use generator._
-## Matching methods
-The gem offers variety of possible matching methods.
+## Interfaces
 
-### Presumptions
-- `match_json_schema` always require full keys match.
+Interfaces are reusable strict object schemas:
 
-  Failure Example:
-    ```ruby
-    let(:expected_schema) do
-      {
-        id: RSpec::JsonApi::Types::UUID,
+```ruby
+module RSpec
+  module JsonApi
+    module Interfaces
+      PERSON = {
+        id: Types::UUID,
         name: String,
-        age: Integer
-      }
-    end
-  
-    let(:actual) do
-      {
-        id: "0a2f911f-3767-4cc7-9c19-049f4350e38c",
-        name: "Mikel",
-      }
+        active: -> { { inclusion: [true, false] } }
+      }.freeze
     end
-    ```
-  
-  Success Example:
-  ```ruby
-  let(:expected_schema) do
-    {
-      id: RSpec::JsonApi::Types::UUID,
-      name: String,
-      age: Integer
-    }
   end
-
-  let(:actual) do
-    {
-      id: "0a2f911f-3767-4cc7-9c19-049f4350e38c",
-      name: "John",
-      age: 24
-    }
-  end
-  ```
-
-### Value match
-```ruby
-let(:expected_schema) do
-  {
-    id: "e0067346-4d24-4aa6-b303-f927a410a001",
-    name: "John",
-    age: 24,
-    favoriteColorHex: "#FF5733"
-  }
 end
 ```
 
-### Class match
-```ruby
-let(:expected_schema) do
-  {
-    id: Integer,
-    name: String,
-    age: Integer,
-    notes: [String]
-  }
-end
-```
+Generate one with:
 
-### Type match
-```ruby
-let(:expected_schema) do
-  {
-    id: RSpec::JsonApi::Types::UUID,
-    email: RSpec::JsonApi::Types::EMAIL,
-  }
-end
+```sh
+rails generate rspec:json_api:interface person
 ```
 
-### Regexp match
-```ruby
-let(:expected_schema) do
-  {
-    color: /^\#([a-fA-F]|[0-9]){3,6}$/
-  }
-end
-```
+Use an interface directly or as a homogeneous list schema:
 
-### Interface match
 ```ruby
-let(:expected_schema) do
-    [RSpec::JsonApi::Interfaces::PERSON]
-end
+expect(response.body).to match_json_schema(RSpec::JsonApi::Interfaces::PERSON)
+expect(response.body).to match_json_schema([RSpec::JsonApi::Interfaces::PERSON])
 ```
 
-### Proc match
-Proc match allows to customize schema according needs using lambda shorthand notation `->`
+## Development
 
-Supported options:
-- #### type
-```ruby
-let(:expected_schema) do
-  {
-    name: -> { { type: String } }
-  }
-end
-```
-- #### value
-```ruby
-let(:expected_schema) do
-  {
-    name: -> { { value: "John" } }
-  }
-end
-```
-- #### min
-```ruby
-let(:expected_schema) do
-  {
-    age: -> { { min: 15 } }
-  }
-end
-```
-- #### max
-```ruby
-let(:expected_schema) do
-  {
-    age: -> { { max: 25 } }
-  }
-end
-```
-- #### inclusion
-```ruby
-let(:expected_schema) do
-  {
-    letter: -> { { inclusion: %w[A B C] } }
-  }
-end
-```
-- #### regex
-```ruby
-let(:expected_schema) do
-  {
-    hex: -> { { regex: /^\#([a-fA-F]|[0-9]){3,6}$/ } }
-  }
-end
-```
-- #### lambda
-```ruby
-let(:expected_schema) do
-  {
-    number: -> { { lambda: lambda(&:even?) } }
-  }
-end
-```
-- #### allow_blank
+Use the Ruby version in `.ruby-version` and Bundler 4.0.4:
 
-```ruby
-let(:expected_schema) do
-  {
-    name: -> { { type: String, allow_blank: true } }
-  }
-end
+```sh
+gem install bundler -v 4.0.4
+bundle install
+bundle exec rspec
+bundle exec rubocop
+bundle exec bundle-audit check --update
 ```
-_Note: Default value is `false`_
-
-## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/nomtek/rspec-json_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nomtek/rspec-json_api/blob/master/CODE_OF_CONDUCT.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for compatibility and contribution guidance. Please report vulnerabilities using [GitHub's private security advisory form](https://github.com/nomtek/rspec-json_api/security/advisories/new), as described in [SECURITY.md](SECURITY.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available under the terms of the [MIT License](LICENSE.txt).
 
 ## Code of Conduct
 
-Everyone interacting in the RSpec::JsonApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/nomtek/rspec-json_api/blob/master/CODE_OF_CONDUCT.md).
+Everyone participating in this project is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are made on the latest released version.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Use [GitHub's private security advisory form](https://github.com/nomtek/rspec-json_api/security/advisories/new) and include reproduction steps, affected versions, and the expected impact.

data/lib/rspec/json_api/blank.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RSpec
+  module JsonApi
+    module Blank
+      module_function
+
+      BLANK_STRING = /\A[[:space:]]*\z/
+
+      def blank?(value)
+        case value
+        when nil, false
+          true
+        when String
+          BLANK_STRING.match?(value)
+        else
+          value.respond_to?(:empty?) && value.empty?
+        end
+      end
+    end
+  end
+end

data/lib/rspec/json_api/constraints.rb

@@ -21,7 +21,7 @@ module RSpec
       def match(value, options)
         validate!(options)
 
-        return true if value.blank? && options[:allow_blank]
+        return true if Blank.blank?(value) && options[:allow_blank]
 
         options.except(:allow_blank).all? do |option, condition|
           satisfies?(value, option, condition)
@@ -29,6 +29,8 @@ module RSpec
       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?
 
@@ -40,7 +42,7 @@ module RSpec
         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 :regex     then matches_regexp?(value, condition)
         when :lambda    then condition.call(value)
         when :min, :max then within_bound?(value, option, condition)
         end
@@ -51,6 +53,10 @@ module RSpec
 
         option == :min ? value >= condition : value <= condition
       end
+
+      def matches_regexp?(value, condition)
+        value.is_a?(String) && condition.match?(value)
+      end
     end
   end
 end