strict 1.4.0 → 2.0.0

data/Gemfile.lock

@@ -1,66 +1,142 @@
 PATH
   remote: .
   specs:
-    strict (1.4.0)
+    strict (2.0.0)
       zeitwerk (~> 2.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    debug (1.6.3)
-      irb (>= 1.3.6)
-      reline (>= 0.3.1)
-    gem-release (2.2.2)
-    io-console (0.5.11)
-    irb (1.4.2)
-      reline (>= 0.3.0)
-    json (2.6.2)
-    minitest (5.16.3)
-    minitest-spec-context (0.0.4)
-    parallel (1.22.1)
-    parser (3.1.2.1)
+    activesupport (8.1.3.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    erb (6.0.7)
+    factory_bot (6.6.0)
+      activesupport (>= 6.1.0)
+    gem-release (2.2.4)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    io-console (0.9.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    parallel (2.1.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
+      racc
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.6.0)
-    reline (0.3.1)
+    rake (13.4.2)
+    rbs (4.1.3)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.7.0)
       io-console (~> 0.5)
-    rexml (3.2.5)
-    rubocop (1.38.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.89.0)
       json (~> 2.3)
-      parallel (~> 1.10)
-      parser (>= 3.1.2.1)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.23.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.23.0)
-      parser (>= 3.1.1.0)
-    rubocop-minitest (0.23.0)
-      rubocop (>= 0.90, < 2.0)
-    rubocop-rake (0.6.0)
-      rubocop (~> 1.0)
-    ruby-progressbar (1.11.0)
-    unicode-display_width (2.3.0)
-    zeitwerk (2.6.4)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-factory_bot (2.28.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.10.2)
+      lint_roller (~> 1.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   arm64-darwin-21
+  arm64-darwin-23
   x86_64-linux
 
 DEPENDENCIES
-  debug (>= 1.0.0)
+  debug (~> 1.11)
+  factory_bot (~> 6.5)
   gem-release (~> 2.2)
-  minitest (~> 5.0)
-  minitest-spec-context (~> 0.0.4)
-  rake (~> 13.0)
-  rubocop (~> 1.21)
-  rubocop-minitest (~> 0.22)
-  rubocop-rake (~> 0.6)
+  rake (~> 13.4)
+  rbs (~> 4.1)
+  rspec (~> 3.13)
+  rubocop (~> 1.89)
+  rubocop-factory_bot (~> 2.28)
+  rubocop-rake (~> 0.7)
+  rubocop-rspec (~> 3.10)
   strict!
 
 BUNDLED WITH
-   2.3.23
+  4.0.19

data/README.md

@@ -4,6 +4,8 @@ Strict provides a means to strictly validate instantiation of values, instantiat
 
 ## Installation
 
+Strict requires Ruby 3.3 or newer.
+
 Install the gem and add to the application's Gemfile by executing:
 
 ```sh
@@ -18,6 +20,8 @@ $ gem install strict
 
 ## Usage
 
+See [Supported API](API.md) for the 2.0 compatibility boundary.
+
 ### `Strict::Value`
 
 ```rb
@@ -49,6 +53,83 @@ Money.new(amount_in_cents: 100_00) == Money.new(amount_in_cents: 100_00)
 # => true
 ```
 
+Subclasses can add attributes while retaining their inherited attributes:
+
+```rb
+class Person
+  include Strict::Value
+
+  attributes do
+    name String
+  end
+end
+
+class Employee < Person
+  attributes do
+    employee_id String
+  end
+end
+```
+
+A subclass can also redeclare an inherited attribute by its exact name. The subclass declaration replaces the inherited validator, coercer, and default without changing the parent or the attribute order.
+
+### `Strict::Union`
+
+```rb
+class PaymentResult
+  include Strict::Union
+
+  discriminator :status
+
+  attributes do
+    request_id String
+  end
+
+  variant :authorized, tag: "payment.authorized" do
+    attributes do
+      authorization_id String
+      amount_in_cents Integer
+    end
+
+    def successful? = true
+  end
+
+  variant :declined do
+    attributes do
+      reason String
+    end
+
+    def successful? = false
+  end
+end
+
+authorized = PaymentResult::Authorized.new(
+  request_id: "request_123",
+  authorization_id: "auth_123",
+  amount_in_cents: 1_000
+)
+authorized.to_h
+# => { status: "payment.authorized", request_id: "request_123", authorization_id: "auth_123", amount_in_cents: 1_000 }
+
+authorized.successful?
+# => true
+
+result = PaymentResult.coercer.call(
+  "status" => "declined",
+  "request_id" => "request_456",
+  "reason" => "insufficient_funds"
+)
+# => #<PaymentResult::Declined status=:declined request_id="request_456" reason="insufficient_funds">
+
+case result
+in PaymentResult::Authorized(authorization_id:)
+  authorization_id
+in PaymentResult::Declined(reason:)
+  reason
+end
+# => "insufficient_funds"
+```
+
 ### `Strict::Object`
 
 ```rb
@@ -78,11 +159,59 @@ Stateful.new(some_state: "123") == Stateful.new(some_state: "123")
 # => false
 ```
 
+Validation errors provide structured violations with paths into nested values:
+
+```rb
+class Batch
+  include Strict::Value
+
+  attributes do
+    labels ArrayOf(String)
+  end
+end
+
+begin
+  Batch.new(labels: ["ready", 404], extra: true)
+rescue Strict::InitializationError => error
+  error.violations.map do |violation|
+    [violation.path, violation.code, violation.value, violation.validator]
+  end
+end
+# => [
+#      [[:labels, 1], :invalid, 404, String],
+#      [[:extra], :unexpected, true, nil]
+#    ]
+```
+
+The codes are `:invalid`, `:missing`, and `:unexpected`. Custom validators only need to implement `===`; Strict reports a rejected value against that validator at the current path. A custom validator can include `Strict::DetailedValidator` and implement `violations(value)` when it needs to report relative nested paths:
+
+```rb
+class Emails
+  include Strict::DetailedValidator
+
+  def violations(value)
+    unless Array === value
+      return [Strict::Violation.new(path: [], code: :invalid, value: value, validator: Array)]
+    end
+
+    value.each_with_index.filter_map do |email, index|
+      next if String === email
+
+      Strict::Violation.new(path: [index], code: :invalid, value: email, validator: String)
+    end
+  end
+end
+```
+
+The module provides `===` from `violations`, and Strict prefixes each relative path with its enclosing attribute, parameter, or collection path.
+
+When an attribute or parameter validator provides a `.coercer`, Strict uses it automatically before validation. An explicit `coerce:` value overrides it, and `coerce: false` disables it. This lets nested Strict values, unions, and interfaces accept the input handled by their class coercers without repeating `coerce:` in each declaration. `ArrayOf` and `HashOf` propagate coercers from their element, key, and value validators, so compositions such as `ArrayOf(ValueClass)` also coerce automatically.
+
 ### `Strict::Method`
 
 ```rb
 class UpdateEmail
-  extend Strict::Method
+  include Strict::Method
 
   sig do
     user_id String, coerce: ->(value) { value.to_s }
@@ -108,11 +237,13 @@ UpdateEmail.new.call(user_id: "123", email: "456")
 # => Strict::MethodReturnError
 ```
 
+`returns` validates the exact value produced by the method. It never coerces or replaces that value, and a successful call returns the same object to the caller.
+
 ### `Strict::Interface`
 
 ```rb
 class Storage
-  extend Strict::Interface
+  include Strict::Interface
 
   expose(:write) do
     key String
@@ -147,7 +278,15 @@ module Storages
   end
 end
 
-storage = Storage.new(Storages::Memory.new)
+adapter = Storages::Memory.new
+
+Storage.implemented_by?(adapter)
+# => true
+
+Storage.verify_implementation!(adapter)
+# => nil
+
+storage = Storage.new(adapter)
 # => #<Storage implementation=#<Storages::Memory>>
 
 storage.write(key: "some/path/to/file.rb", contents: "Hello")
@@ -173,9 +312,144 @@ storage = Storage.new(Storages::Wat.new)
 # => Strict::ImplementationDoesNotConformError
 ```
 
+### RSpec extensions
+
+Strict provides supported, opt-in integration with RSpec 3.13. RSpec remains an optional dependency and is not loaded by
+`require "strict"`. Add RSpec to the test bundle:
+
+```rb
+group :test do
+  gem "rspec", "~> 3.13"
+end
+```
+
+Then require the adapter from the spec helper:
+
+```rb
+require "strict/rspec"
+```
+
+The adapter provides matchers for validators and interfaces:
+
+```rb
+expect(String).to validate("value")
+expect(String).not_to validate(1)
+
+expect(Storages::Memory.new).to conform_to(Storage)
+expect(Object.new).not_to conform_to(Storage)
+```
+
+When validation fails, `validate` uses `Strict::Violation` records to report root and nested
+`Strict::DetailedValidator` failure paths.
+
+`strict_double` builds an RSpec verifying double. For an interface, it stubs every exposed method to `nil` unless a
+different result is provided, so the double conforms without extra setup:
+
+```rb
+storage = strict_double(Storage, write: true, read: "contents")
+
+expect(storage).to conform_to(Storage)
+Storage.new(storage).read(key: "some/path")
+# => "contents"
+```
+
+RSpec instance doubles also satisfy Strict class validators for attributes, signed parameters, and return values. Plain
+doubles remain invalid:
+
+```rb
+class Item
+  include Strict::Value
+
+  attributes do
+    sku String
+  end
+end
+
+class Shipment
+  include Strict::Value
+
+  attributes do
+    item Item
+  end
+end
+
+item = instance_double(Item, sku: "item_123")
+Shipment.new(item: item)
+# => #<Shipment item=#<InstanceDouble(Item)>>
+
+Shipment.new(item: double("item"))
+# => Strict::InitializationError
+```
+
+Matcher objects can also stand in for validated fields or elements of built-in collection validators when constructing
+expected Strict values. RSpec recursively applies the nested matchers in argument expectations:
+
+```rb
+expect(dispatcher).to have_received(:ship).with(
+  shipment: Shipment.new(
+    item: have_attributes(sku: "item_123")
+  )
+)
+```
+
+This composition does not change normal Strict value equality or hashing.
+
+### Configuration
+
+Strict exposes some configuration options which can be configured globally via `Strict.configure { ... }` or overridden
+within a block via `Strict.with_overrides(...) { ... }`.
+
+#### Example
+
+```ruby
+# Globally
+
+Strict.configure do |c|
+  c.sample_rate = 0.75 # run validation ~75% of the time
+end
+
+Strict.configure do |c|
+  c.sample_rate = 0 # disable validation (Strict becomes Lenient)
+end
+
+Strict.configure do |c|
+  c.sample_rate = 1 # always run validation
+end
+
+# Locally within the block (only applies to the current execution context)
+
+Strict.with_overrides(sample_rate: 0) do
+  # Use Strict as you normally would
+
+  Strict.with_overrides(sample_rate: 0.5) do
+    # Overrides can be nested
+  end
+end
+```
+
+Overrides are local to the current execution context (fiber). They can be nested and are restored when a block returns
+or raises. Neither a newly created fiber nor a new thread inherits an active override.
+
+#### `Strict.configuration.random`
+
+The instance of a `Random::Formatter` that Strict uses in tandom with the `sample_rate` to determine when validation
+should be checked.
+
+**Default**: `Random.new`
+
+#### `Strict.configuration.sample_rate`
+
+The rate of samples Strict will consider when validating attributes, parameters, and return values. A rate of 0.25 will
+validate roughly 25% of the time, a rate of 0 will disable validation entirely, and a rate of 1 will always
+run validations. The `sample_rate` is used in tandem with `random` to determine whether validation should be run.
+
+**Default**: 1
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the specs. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Run `bundle exec rake benchmark` to measure baseline timing and allocations for value initialization, mutable assignment, verified method calls, interface construction, interface calls, `to_h`, equality, and hashing. Set `ITERATIONS`, `WARMUP_ITERATIONS`, or `SAMPLES` to change the workload, and set `FORMAT=markdown` to produce a Markdown table. Pull requests publish this table in a non-blocking job summary and upload it as an artifact. These benchmarks report measurements only and do not enforce thresholds.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -1,16 +1,22 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rake/testtask"
+require "rspec/core/rake_task"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
+RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+desc "Validate RBS signatures"
+task :rbs do
+  sh "bundle exec rbs -I sig validate"
+end
+
+desc "Run timing and allocation baselines"
+task :benchmark do
+  sh "bundle exec ruby benchmark/baseline.rb", verbose: false
+end
+
+task default: %i[spec rubocop rbs]