contracts-rb 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9993a3ee0ba0579a550417f72325feb368a093f39508ad4b2a6c3ae516bf4fe
-  data.tar.gz: 84923376eab19c456ba1a5a783f44c5aab228915f6e80db7d0b7f3adac17946c
+  metadata.gz: 3c50991fa2ffc01a3c3a213d34a813be80939f9c5086cba3e8d542ba61982602
+  data.tar.gz: 90babd1110a562e0921ca036d85789a693bc7bf3ed0d76340769ff8f1f62812e
 SHA512:
-  metadata.gz: 2d7c3695fada564090c026e1cc9e6add5e538c772e9c317ee7fdfea0486f42355193107202b27a9057b80c61c42644cd6676cd7a2a9f1bea04f4e8c00bf1fb46
-  data.tar.gz: 16be4ea8a83af309effbd863cd8efe26e5b50d2d10847caba139a49d240580ca2278371950eeb2a2e1a24da74b9481c9372134d45abca4cb2c64698de071e3c8
+  metadata.gz: fdf4bc427ec2d091068cc7a8bc934376e964236b0c448b5c64ef5fe3e3be3f85cf5833335c370840c596ee5cb1e197d59c80ade8955d84a14966919421631a29
+  data.tar.gz: fe9d806bbc89fed14613f1773a31a86392764e040e6f0384bee065d97fffa141cb9cd0de01e51eeaf9c53a10635505d3ffd0aa022a0776cf4d26167da5c9c56f

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.4.0 - 2026-08-14
+
+- Added `Contracts.all` to require every nested constraint to match.
+- Added `Contracts.length(min:, max:, exactly:)` for String, Array, Hash, and other sized values.
+
+## 0.3.0 - 2026-08-11
+
+- Enforce `must_change` `from:` and `to:` bounds for scalar and array values.
+- Raise `Contracts::MutationViolation` when required change bounds fail.
+
+## 0.2.0 - 2026-08-04
+
+- Added `Contracts::Constraints::Tuple` for fixed-length heterogeneous arrays.
+- Added `Contracts::Constraints::Shape` for required and optional hash-key contracts.
+- Added `Contracts::Constraints.tuple` and `.shape` constructors.
+- Added strict extra-key handling with an opt-in `allow_extra` mode.
+- Added structured constraint serialization through `to_h`.
+- Corrected gem metadata links to the current `theworker02/contracts-rb` repository.
+
 ## 0.1.2 - 2026-07-30
 
 - Corrected package metadata links to use the repository's `master` branch.

data/README.md

@@ -23,6 +23,8 @@ Ruby tests describe expected examples; contracts keep critical method promises e
 
 ## Install
 
+Install the official package from [RubyGems: `contracts-rb`](https://rubygems.org/gems/contracts-rb).
+
 ```ruby
 gem "contracts-rb", "~> 0.1"
 require "contracts"
@@ -50,7 +52,7 @@ class Account
 end
 ```
 
-Constraints include `Contracts.nilable`, `any`, `matching`, `range`, `one_of`, `array_of`, `hash_of`, `respond_to`, `duck_type`, `anything`, `nothing`, and `predicate`.
+Constraints include `Contracts.nilable`, `any`, `all`, `matching`, `range`, `one_of`, `array_of`, `hash_of`, `length`, `respond_to`, `duck_type`, `anything`, `nothing`, and `predicate`.
 
 ## Stateful contracts
 
@@ -67,7 +69,8 @@ Use `observe` to capture relevant receiver fields; `changes` permits a subset, `
 | `one_of` | `Contracts.one_of(:draft, :published)` | one literal value |
 | `array_of` | `Contracts.array_of(String)` | array whose elements match |
 | `hash_of` | `Contracts.hash_of(Symbol, Numeric)` | hash with matching keys/values |
-| `predicate` | `Contracts.predicate("valid ID") { ... }` | custom runtime rule |
+| `all` | `Contracts.all(String, Contracts.matching(/A/))` | every nested constraint matches |
+| `length` | `Contracts.length(min: 1, max: 80)` | `size`/`length` within bounds |
 
 ## Runtime configuration
 

data/docs/contracts/contracts.md

@@ -1,59 +1,59 @@
-## `BankAccount#__invariant__`
-
-### Parameters
-
-
-### Preconditions
-
-
-### Returns
-`unspecified`
-
-### Observed State
-| Field | Deep | Comparator |
-|---|---:|---|
-
-
-### Permitted Changes
-
-
-### Required Changes
-None.
-
-### Invariants
-- balance cannot be negative
-- status is valid
-
+## `BankAccount#__invariant__`
+
+### Parameters
+
+
+### Preconditions
+
+
+### Returns
+`unspecified`
+
+### Observed State
+| Field | Deep | Comparator |
+|---|---:|---|
+
+
+### Permitted Changes
+
+
+### Required Changes
+None.
+
+### Invariants
+- balance cannot be negative
+- status is valid
+
 ### Allowed Exceptions
-
-## `BankAccount#withdraw`
-
-### Parameters
-- `amount`: `Numeric`
-
-### Preconditions
-- positive amount
-- active account
-
-### Returns
-`unspecified`
-
-### Observed State
-| Field | Deep | Comparator |
-|---|---:|---|
-| `balance` | No | `eql?` |
-| `audit_log` | Yes | `eql?` |
-
-### Permitted Changes
-- `balance`
-- `audit_log`
-
-### Required Changes
-None.
-
-### Invariants
-- balance cannot be negative
-- status is valid
-
-### Allowed Exceptions
-
+
+## `BankAccount#withdraw`
+
+### Parameters
+- `amount`: `Numeric`
+
+### Preconditions
+- positive amount
+- active account
+
+### Returns
+`unspecified`
+
+### Observed State
+| Field | Deep | Comparator |
+|---|---:|---|
+| `balance` | No | `eql?` |
+| `audit_log` | Yes | `eql?` |
+
+### Permitted Changes
+- `balance`
+- `audit_log`
+
+### Required Changes
+None.
+
+### Invariants
+- balance cannot be negative
+- status is valid
+
+### Allowed Exceptions
+

data/docs/structured-constraints.md

@@ -0,0 +1,52 @@
+# Structured constraints
+
+Contracts-rb 0.2.0 adds optional structured constraints for fixed tuples and hash-shaped payloads.
+
+Load the extension after the main gem:
+
+```ruby
+require "contracts"
+require "contracts/structured"
+```
+
+## Tuple
+
+```ruby
+Coordinates = Contracts::Constraints.tuple(Float, Float)
+Coordinates.matches?([41.3, -72.9]) # => true
+```
+
+A tuple requires an `Array` with the exact declared length and validates every position independently.
+
+## Shape
+
+```ruby
+Payload = Contracts::Constraints.shape(
+  required: {
+    name: String,
+    retries: Integer
+  },
+  optional: {
+    tags: Contracts::Constraints::ArrayOf.new(String)
+  }
+)
+```
+
+Shapes reject missing required keys, invalid optional values, and unknown keys. Set `allow_extra: true` when additional keys are part of the contract.
+
+```ruby
+OpenPayload = Contracts::Constraints.shape(
+  required: {name: String},
+  allow_extra: true
+)
+```
+
+Both constraints implement the normal Contracts-rb constraint interface: `matches?`, `description`, and `to_h`.
+
+`Contracts.all` and `Contracts.length` live on the core gem (no extra require) for conjunctions and sized values:
+
+```ruby
+Contracts.all(String, Contracts.matching(/\A[A-Z]/)).matches?("OK")
+Contracts.length(min: 2, max: 4).matches?("ab")
+```
+

data/exe/contracts

@@ -1,105 +1,105 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "cgi"
-require "fileutils"
-require "json"
-require "optparse"
-require "contracts"
-
-command = ARGV.shift || "help"
-options = { requires: [], format: "text", output: nil }
-OptionParser.new do |parser|
-  parser.on("--require PATH") { |path| options[:requires] << path }
-  parser.on("--format FORMAT") { |format| options[:format] = format }
-  parser.on("--output PATH") { |path| options[:output] = path }
-end.parse!
-options[:requires].each { |path| require File.expand_path(path) }
-
-def contracts_for(target)
-  return Contracts.registry.all unless target
-
-  owner_name, method_name = target.split("#", 2)
-  owner = owner_name.split("::").reject(&:empty?).inject(Object) { |scope, name| scope.const_get(name) }
-  method_name ? [Contracts.contract_for(owner, method_name)].compact : Contracts.registry.for_class(owner)
-end
-
-def markdown(contracts)
-  contracts.map do |contract|
-    item = contract.to_h
-    observed = item[:observed].map do |field|
-      "| `#{field[:name]}` | #{field[:deep] ? 'Yes' : 'No'} | `#{field[:comparator] || 'eql?'}` |"
-    end.join("\n")
-    <<~DOC
-      ## `#{item[:owner]}##{item[:method_name]}`
-
-      ### Parameters
-      #{item[:parameters].map { |name, rule| "- `#{name}`: `#{rule}`" }.join("\n")}
-
-      ### Preconditions
-      #{item[:preconditions].map { |rule| "- #{rule}" }.join("\n")}
-
-      ### Returns
-      `#{item[:return_constraint] || 'unspecified'}`
-
-      ### Observed State
-      | Field | Deep | Comparator |
-      |---|---:|---|
-      #{observed}
-
-      ### Permitted Changes
-      #{item[:permitted_changes].map { |field| "- `#{field}`" }.join("\n")}
-
-      ### Required Changes
-      #{item[:required_changes].empty? ? 'None.' : item[:required_changes].map { |field| "- `#{field}`" }.join("\n")}
-
-      ### Invariants
-      #{item[:invariants].map { |rule| "- #{rule}" }.join("\n")}
-
-      ### Allowed Exceptions
-      #{item[:allowed_exceptions].map { |rule| "- `#{rule}`" }.join("\n")}
-    DOC
-  end.join("\n")
-end
-
-case command
-when "version" then puts Contracts::VERSION
-when "inspect"
-  list = contracts_for(ARGV.shift)
-  puts(options[:format] == "json" ? JSON.pretty_generate(list.map(&:to_h)) : markdown(list))
-when "docs"
-  list = Contracts.registry.all
-  body = case options[:format]
-         when "json" then JSON.pretty_generate(list.map(&:to_h))
-         when "html" then "<html><body><pre>#{CGI.escapeHTML(markdown(list))}</pre></body></html>"
-         else markdown(list)
-         end
-  if options[:output]
-    path = options[:output]
-    if File.extname(path).empty?
-      FileUtils.mkdir_p(path)
-      path = File.join(path,
-                       "contracts.#{if options[:format] == 'json'
-                                      'json'
-                                    else
-                                      options[:format] == 'html' ? 'html' : 'md'
-                                    end}")
-    end
-    FileUtils.mkdir_p(File.dirname(path))
-    File.write(path, body)
-    puts path
-  else
-    puts body
-  end
-when "validate", "doctor"
-  failures = Contracts.registry.all.filter_map do |contract|
-    next if contract.method_name == :__invariant__
-
-    owner = contract.owner
-    "#{contract.id}: method missing" unless owner.method_defined?(contract.method_name) || owner.private_method_defined?(contract.method_name) || owner.protected_method_defined?(contract.method_name)
-  end
-  abort("Contract diagnostics failed:\n#{failures.join("\n")}") unless failures.empty?
-  puts(command == "doctor" ? "No contract wrapper or registry problems detected." : "Contracts are valid.")
-else
-  puts "Usage: contracts <version|inspect|validate|doctor|docs> [--require PATH] [--format FORMAT] [--output PATH]"
-end
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "cgi"
+require "fileutils"
+require "json"
+require "optparse"
+require "contracts"
+
+command = ARGV.shift || "help"
+options = { requires: [], format: "text", output: nil }
+OptionParser.new do |parser|
+  parser.on("--require PATH") { |path| options[:requires] << path }
+  parser.on("--format FORMAT") { |format| options[:format] = format }
+  parser.on("--output PATH") { |path| options[:output] = path }
+end.parse!
+options[:requires].each { |path| require File.expand_path(path) }
+
+def contracts_for(target)
+  return Contracts.registry.all unless target
+
+  owner_name, method_name = target.split("#", 2)
+  owner = owner_name.split("::").reject(&:empty?).inject(Object) { |scope, name| scope.const_get(name) }
+  method_name ? [Contracts.contract_for(owner, method_name)].compact : Contracts.registry.for_class(owner)
+end
+
+def markdown(contracts)
+  contracts.map do |contract|
+    item = contract.to_h
+    observed = item[:observed].map do |field|
+      "| `#{field[:name]}` | #{field[:deep] ? 'Yes' : 'No'} | `#{field[:comparator] || 'eql?'}` |"
+    end.join("\n")
+    <<~DOC
+      ## `#{item[:owner]}##{item[:method_name]}`
+
+      ### Parameters
+      #{item[:parameters].map { |name, rule| "- `#{name}`: `#{rule}`" }.join("\n")}
+
+      ### Preconditions
+      #{item[:preconditions].map { |rule| "- #{rule}" }.join("\n")}
+
+      ### Returns
+      `#{item[:return_constraint] || 'unspecified'}`
+
+      ### Observed State
+      | Field | Deep | Comparator |
+      |---|---:|---|
+      #{observed}
+
+      ### Permitted Changes
+      #{item[:permitted_changes].map { |field| "- `#{field}`" }.join("\n")}
+
+      ### Required Changes
+      #{item[:required_changes].empty? ? 'None.' : item[:required_changes].map { |field| "- `#{field}`" }.join("\n")}
+
+      ### Invariants
+      #{item[:invariants].map { |rule| "- #{rule}" }.join("\n")}
+
+      ### Allowed Exceptions
+      #{item[:allowed_exceptions].map { |rule| "- `#{rule}`" }.join("\n")}
+    DOC
+  end.join("\n")
+end
+
+case command
+when "version" then puts Contracts::VERSION
+when "inspect"
+  list = contracts_for(ARGV.shift)
+  puts(options[:format] == "json" ? JSON.pretty_generate(list.map(&:to_h)) : markdown(list))
+when "docs"
+  list = Contracts.registry.all
+  body = case options[:format]
+         when "json" then JSON.pretty_generate(list.map(&:to_h))
+         when "html" then "<html><body><pre>#{CGI.escapeHTML(markdown(list))}</pre></body></html>"
+         else markdown(list)
+         end
+  if options[:output]
+    path = options[:output]
+    if File.extname(path).empty?
+      FileUtils.mkdir_p(path)
+      path = File.join(path,
+                       "contracts.#{if options[:format] == 'json'
+                                      'json'
+                                    else
+                                      options[:format] == 'html' ? 'html' : 'md'
+                                    end}")
+    end
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, body)
+    puts path
+  else
+    puts body
+  end
+when "validate", "doctor"
+  failures = Contracts.registry.all.filter_map do |contract|
+    next if contract.method_name == :__invariant__
+
+    owner = contract.owner
+    "#{contract.id}: method missing" unless owner.method_defined?(contract.method_name) || owner.private_method_defined?(contract.method_name) || owner.protected_method_defined?(contract.method_name)
+  end
+  abort("Contract diagnostics failed:\n#{failures.join("\n")}") unless failures.empty?
+  puts(command == "doctor" ? "No contract wrapper or registry problems detected." : "Contracts are valid.")
+else
+  puts "Usage: contracts <version|inspect|validate|doctor|docs> [--require PATH] [--format FORMAT] [--output PATH]"
+end

data/lib/contracts/rails.rb

@@ -1,9 +1,9 @@
-# frozen_string_literal: true
-
-require "contracts"
-begin
-  require "rails/railtie"
-  module Contracts
+# frozen_string_literal: true
+
+require "contracts"
+begin
+  require "rails/railtie"
+  module Contracts
     class Railtie < Rails::Railtie
       initializer "contracts.logger" do
         Contracts.configuration.logger ||= Rails.logger
@@ -13,8 +13,8 @@ begin
         # Contract wrapping is idempotent, making reloads safe for existing contracts.
         Contracts.configuration.enabled = true if Contracts.configuration.enabled.nil?
       end
-    end
-  end
-rescue LoadError
-  # Rails remains an optional dependency.
-end
+    end
+  end
+rescue LoadError
+  # Rails remains an optional dependency.
+end

data/lib/contracts/rspec.rb

@@ -1,42 +1,42 @@
-# frozen_string_literal: true
-
+# frozen_string_literal: true
+
 require "contracts"
 require_relative "rspec/verifier"
-begin
-  require "rspec/expectations"
-  RSpec::Matchers.define :have_contract do |method_name|
-    match { |owner| !Contracts.contract_for(owner, method_name).nil? }
-  end
-  RSpec::Matchers.define :have_precondition do |method_name|
-    match { |owner| (contract = Contracts.contract_for(owner, method_name)) && !contract.preconditions.empty? }
-  end
-  RSpec::Matchers.define :return_contract do |method_name, constraint|
-    match do |owner|
-      (contract = Contracts.contract_for(owner,
-                                         method_name)) && contract.return_constraint.description == Contracts::Constraints.coerce(constraint).description
-    end
-  end
-  RSpec::Matchers.define :have_invariant do |description|
-    match { |owner| Contracts.invariants_for(owner).any? { |invariant| invariant.description == description } }
-  end
-  RSpec::Matchers.define :observe_state do |field, on:|
-    match { |owner| (contract = Contracts.contract_for(owner, on)) && contract.observed_fields.include?(field.to_sym) }
-  end
-  RSpec::Matchers.define :permit_change do |field, on:|
-    match do |owner|
-      (contract = Contracts.contract_for(owner, on)) && contract.permitted_changes.include?(field.to_sym)
-    end
-  end
-  RSpec::Matchers.define :require_change do |field, on:|
-    match { |owner| (contract = Contracts.contract_for(owner, on)) && contract.required_changes.include?(field.to_sym) }
-  end
+begin
+  require "rspec/expectations"
+  RSpec::Matchers.define :have_contract do |method_name|
+    match { |owner| !Contracts.contract_for(owner, method_name).nil? }
+  end
+  RSpec::Matchers.define :have_precondition do |method_name|
+    match { |owner| (contract = Contracts.contract_for(owner, method_name)) && !contract.preconditions.empty? }
+  end
+  RSpec::Matchers.define :return_contract do |method_name, constraint|
+    match do |owner|
+      (contract = Contracts.contract_for(owner,
+                                         method_name)) && contract.return_constraint.description == Contracts::Constraints.coerce(constraint).description
+    end
+  end
+  RSpec::Matchers.define :have_invariant do |description|
+    match { |owner| Contracts.invariants_for(owner).any? { |invariant| invariant.description == description } }
+  end
+  RSpec::Matchers.define :observe_state do |field, on:|
+    match { |owner| (contract = Contracts.contract_for(owner, on)) && contract.observed_fields.include?(field.to_sym) }
+  end
+  RSpec::Matchers.define :permit_change do |field, on:|
+    match do |owner|
+      (contract = Contracts.contract_for(owner, on)) && contract.permitted_changes.include?(field.to_sym)
+    end
+  end
+  RSpec::Matchers.define :require_change do |field, on:|
+    match { |owner| (contract = Contracts.contract_for(owner, on)) && contract.required_changes.include?(field.to_sym) }
+  end
   RSpec::Matchers.define :have_pure_contract do |method_name|
-    match { |owner| (contract = Contracts.contract_for(owner, method_name)) && contract.pure? }
+    match { |owner| (contract = Contracts.contract_for(owner, method_name)) && contract.pure? }
   end
 
   RSpec::Core::ExampleGroup.define_singleton_method(:describe_contract) do |owner, method_name, &block|
     describe("#{owner}##{method_name}", &block)
   end
 rescue LoadError
-  # RSpec is optional at runtime.
-end
+  # RSpec is optional at runtime.
+end

data/lib/contracts/structured.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "contracts"
+
+module Contracts
+  module Constraints
+    # Matches a fixed-length Array whose positions use independent constraints.
+    class Tuple < Base
+      def initialize(*items)
+        @items = items.map { |item| Constraints.coerce(item) }.freeze
+      end
+
+      def matches?(value)
+        value.is_a?(Array) && value.length == @items.length &&
+          @items.each_with_index.all? { |constraint, index| constraint.matches?(value[index]) }
+      end
+
+      def description
+        "Tuple<#{@items.map(&:description).join(', ')}>"
+      end
+
+      def to_h
+        super.merge(items: @items.map(&:description))
+      end
+    end
+
+    # Matches a Hash with required and optional key contracts.
+    class Shape < Base
+      attr_reader :required, :optional, :allow_extra
+
+      def initialize(required: {}, optional: {}, allow_extra: false)
+        @required = coerce_map(required)
+        @optional = coerce_map(optional)
+        overlap = @required.keys & @optional.keys
+        raise DefinitionError, "shape keys cannot be both required and optional: #{overlap.join(', ')}" unless overlap.empty?
+
+        @allow_extra = allow_extra
+        freeze
+      end
+
+      def matches?(value)
+        return false unless value.is_a?(Hash)
+        return false unless required.all? { |key, constraint| value.key?(key) && constraint.matches?(value[key]) }
+        return false unless optional.all? { |key, constraint| !value.key?(key) || constraint.matches?(value[key]) }
+        return true if allow_extra
+
+        (value.keys - required.keys - optional.keys).empty?
+      end
+
+      def description
+        required_text = required.map { |key, constraint| "#{key}: #{constraint.description}" }
+        optional_text = optional.map { |key, constraint| "#{key}?: #{constraint.description}" }
+        suffix = allow_extra ? ", ..." : ""
+        "Shape<{#{(required_text + optional_text).join(', ')}#{suffix}}>"
+      end
+
+      def to_h
+        super.merge(
+          required: required.transform_values(&:description),
+          optional: optional.transform_values(&:description),
+          allow_extra: allow_extra
+        )
+      end
+
+      private
+
+      def coerce_map(values)
+        values.to_h.transform_values { |constraint| Constraints.coerce(constraint) }.freeze
+      end
+    end
+
+    module_function
+
+    # Creates a fixed-length heterogeneous Array constraint.
+    def tuple(*items)
+      Tuple.new(*items)
+    end
+
+    # Creates a required/optional Hash shape constraint.
+    def shape(required: {}, optional: {}, allow_extra: false)
+      Shape.new(required:, optional:, allow_extra:)
+    end
+  end
+end

data/lib/contracts/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Contracts
-  VERSION = "0.1.2"
+  VERSION = "0.4.0"
 end