specproof 0.1.0

data/examples/age_policy/run.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "minitest/autorun"
+require "specproof/minitest"
+
+mode = ARGV.shift || "correct"
+output = ARGV.shift || File.expand_path("../../tmp/age-policy-#{mode}.json", __dir__)
+tests = {
+  "correct" => "test/age_policy_test.rb",
+  "missing" => "faulty/test/age_policy_examples_test.rb",
+  "regression" => "faulty/test/age_policy_test.rb"
+}.freeze
+abort "Choose correct, missing, or regression" unless tests.key?(mode)
+
+implementation = mode == "correct" ? "lib/age_policy.rb" : "faulty/lib/age_policy.rb"
+require File.join(__dir__, implementation)
+SpecProof::Minitest.install!(
+  specifications: [File.join(__dir__, "specification.rb")],
+  output: output,
+  fail_on_missing: ENV["SPECPROOF_STRICT"] == "1"
+)
+require File.join(__dir__, tests.fetch(mode))

data/examples/age_policy/specification.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+SpecProof.define "AgePolicy#adult?" do
+  input :age, range: 0..120, allow_gaps: false, allow_overlaps: false do
+    partition :minor, range: 0...18
+    partition :adult, range: 18..120
+  end
+end

data/examples/age_policy/test/age_policy_test.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "../lib/age_policy"
+
+# Verifies the declared age policy examples.
+class AgePolicyTest < Minitest::Test
+  def test_adult_boundary
+    policy = AgePolicy.new
+
+    refute policy.adult?(0)
+    refute policy.adult?(1)
+    refute policy.adult?(17)
+    assert policy.adult?(18)
+    assert policy.adult?(119)
+    assert policy.adult?(120)
+  end
+end

data/examples/constrained_partition_pairs/README.md

@@ -0,0 +1,40 @@
+# Constrained pairwise coverage over integer partitions
+
+This example combines the complete, non-overlapping age categories `minor`
+(`0...18`) and `adult` (`18..120`) with finite account and country values. Its
+[independent requirements](requirements.md) prohibit minors from having a
+business account and define eligibility from age alone. The restriction uses
+`in_partition(:minor)` to select the whole integer category:
+
+```ruby
+combinations :age, :account, :country do
+  forbid age: in_partition(:minor), account: "business"
+end
+```
+
+Run from the `gems/specproof` directory with the prepared Ruby and bundle for
+this checkout. Reports and suggestion output go under `tmp/`:
+
+```sh
+bundle exec ruby -Ilib exe/specproof plan examples/constrained_partition_pairs/specification.rb --criterion pairwise-partitions-v1 --format json
+bundle exec ruby examples/constrained_partition_pairs/run.rb initial
+bundle exec ruby -Ilib exe/specproof suggest examples/constrained_partition_pairs/specification.rb --report tmp/constrained-partition-pairs-initial.json --format json > tmp/constrained-partition-pairs-suggestions.json
+bundle exec ruby examples/constrained_partition_pairs/run.rb complete
+```
+
+The two integer categories and two finite domains produce eight possible full
+assignments. The requirement-backed restriction removes the two assignments
+with a minor and a business account, leaving six allowed tuples. The plan has
+eleven required category-pair obligations and one `excluded_pairs` entry with
+`reason: "no_allowed_completion"`. The initial process passes three requirement-
+backed calls and hits nine obligations. `suggest` proposes the two remaining
+allowed assignments, `age: 18, account: "business", country: "de"` and
+`age: 0, account: "personal", country: "de"`. The complete process adds those
+calls with expected results justified by the separate requirement.
+
+The normalized selector value used for the contract digest is
+`{ "kind": "partition_reference", "name": "minor" }`. Planned pair values
+continue to use the existing partition object with its name and inclusive
+bounds. Suggestions choose each partition's lower endpoint as a concrete call
+input. Neither category coverage nor a suggested input establishes boundary
+coverage or an expected result.

data/examples/constrained_partition_pairs/lib/account_eligibility.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Applies the age requirement to supported account and country values.
+class AccountEligibility
+  def eligible?(age:, account:, country:)
+    %w[personal business].include?(account) && %w[ro de].include?(country) && age >= 18
+  end
+end

data/examples/constrained_partition_pairs/requirements.md

@@ -0,0 +1,11 @@
+# Account eligibility requirements
+
+An account may be opened only by an adult. Minors cannot have a business
+account. Both supported account types (`"personal"` and `"business"`) and
+countries (`"ro"` and `"de"`) are otherwise valid. Eligibility is true exactly
+when age is at least 18; account type and country do not change that result.
+
+The restriction on business accounts justifies forbidding the whole `minor`
+partition with `account: "business"`. The age-based eligibility rule supplies
+expected outputs to the example tests. Suggestions provide inputs only and
+are not an output oracle.

data/examples/constrained_partition_pairs/run.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "minitest/autorun"
+require "specproof/minitest"
+require_relative "lib/account_eligibility"
+
+mode = ARGV.shift || "initial"
+abort "Choose initial or complete" unless %w[initial complete].include?(mode)
+
+ENV["ADD_MISSING_PAIRS"] = mode == "complete" ? "1" : "0"
+root = File.expand_path("../..", __dir__)
+report = File.join(root, "tmp/constrained-partition-pairs-#{mode}.json")
+
+SpecProof::Minitest.install!(
+  specifications: [File.join(__dir__, "specification.rb")],
+  criterion: "pairwise-partitions-v1",
+  output: report,
+  fail_on_missing: false
+)
+
+require_relative "test_account_eligibility"

data/examples/constrained_partition_pairs/specification.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "specproof"
+
+SpecProof.define "AccountEligibility#eligible?" do
+  input :age, range: 0..120, allow_gaps: false, allow_overlaps: false do
+    partition :minor, range: 0...18
+    partition :adult, range: 18..120
+  end
+
+  input :account, values: %w[personal business]
+  input :country, values: %w[ro de]
+
+  combinations :age, :account, :country do
+    forbid age: in_partition(:minor), account: "business"
+  end
+end

data/examples/constrained_partition_pairs/test_account_eligibility.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "lib/account_eligibility"
+
+# Covers selected age-category, account, and country pairs.
+class AccountEligibilityPairwiseTest < Minitest::Test
+  BASELINE_CASES = [
+    [16, "personal", "ro", false],
+    [30, "business", "ro", true],
+    [30, "personal", "de", true]
+  ].freeze
+
+  def test_baseline_calls_follow_the_age_requirement
+    policy = AccountEligibility.new
+
+    BASELINE_CASES.each do |age, account, country, expected|
+      assert_equal expected,
+                   policy.eligible?(age: age, account: account, country: country),
+                   "requirements.md: eligibility depends on age >= 18, not account or country"
+    end
+  end
+
+  if ENV["ADD_MISSING_PAIRS"] == "1"
+    def test_suggested_assignments_follow_the_age_requirement
+      policy = AccountEligibility.new
+
+      assert_equal false, policy.eligible?(age: 0, account: "personal", country: "de"),
+                   "requirements.md: every minor is ineligible"
+      assert_equal true, policy.eligible?(age: 18, account: "business", country: "de"),
+                   "requirements.md: every adult with a supported account and country is eligible"
+    end
+  end
+end

data/examples/input_selection/README.md

@@ -0,0 +1,22 @@
+# Explicit input selection
+
+This example analyzes the boolean `expedited` option and explicitly excludes
+the ordinary `Hash` payload. The expected results come from the independent
+[delivery requirements](requirements.md), not from the implementation.
+
+From the `gems/specproof` checkout, inspect the offline contract and candidate
+plan, then run the Minitest suite:
+
+```sh
+bundle exec ruby -Ilib exe/specproof check examples/input_selection/specification.rb --format json
+bundle exec ruby -Ilib exe/specproof plan examples/input_selection/specification.rb --format json
+bundle exec ruby -Ilib examples/input_selection/test_delivery_policy.rb
+```
+
+The plan has one candidate for each boolean value. The suite asserts both
+acceptance and rejection under the independent rules and passes ordinary Hash
+values at runtime. Its coverage report concerns only the selected `expedited`
+input. It says nothing about payload values, payload content, output behavior
+outside the assertions, interactions, or complete method correctness. An
+excluded input cannot be used to claim coverage for that input. If a selected
+input receives a non-primitive value, collection is incomplete.

data/examples/input_selection/delivery_policy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Evaluates whether a delivery meets its option requirements.
+class DeliveryPolicy
+  def accept?(payload, expedited:)
+    return false unless payload.fetch(:ready)
+    return true unless expedited
+
+    payload.fetch(:priority) == :high
+  end
+end

data/examples/input_selection/requirements.md

@@ -0,0 +1,9 @@
+# Delivery option requirements
+
+The option decision is evaluated only for ready deliveries. A regular ready
+delivery is accepted regardless of payload details. An expedited ready delivery
+is accepted exactly when its payload has `priority: :high`. A delivery that is
+not ready is rejected.
+
+These rules are the expected-result oracle for the example tests. They describe
+behavior independently of `DeliveryPolicy#accept?`.

data/examples/input_selection/specification.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "specproof"
+
+SpecProof.define "DeliveryPolicy#accept?" do
+  input :expedited, values: [false, true]
+  exclude_input :payload, reason: "Payload content is outside this option coverage"
+end

data/examples/input_selection/test_delivery_policy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "delivery_policy"
+require "specproof/minitest"
+
+SpecProof::Minitest.install!(
+  specifications: ["examples/input_selection/specification.rb"],
+  output: "tmp/specproof-input-selection-coverage.json",
+  fail_on_missing: true
+)
+
+# Exercises delivery options against the independent requirements.
+class DeliveryPolicyTest < Minitest::Test
+  def setup
+    @policy = DeliveryPolicy.new
+  end
+
+  def test_regular_ready_delivery_is_accepted
+    assert @policy.accept?({ ready: true, priority: :low }, expedited: false),
+           "A regular ready delivery is accepted (requirements.md)"
+  end
+
+  def test_high_priority_expedited_delivery_is_accepted
+    assert @policy.accept?({ ready: true, priority: :high }, expedited: true),
+           "A high-priority expedited delivery is accepted (requirements.md)"
+  end
+
+  def test_low_priority_expedited_delivery_is_rejected
+    refute @policy.accept?({ ready: true, priority: :low }, expedited: true),
+           "A low-priority expedited delivery is rejected (requirements.md)"
+  end
+
+  def test_unready_delivery_is_rejected
+    refute @policy.accept?({ ready: false, priority: :high }, expedited: false),
+           "An unready delivery is rejected (requirements.md)"
+  end
+end

data/examples/method_targets/README.md

@@ -0,0 +1,30 @@
+# String and method-object targets
+
+The requirements in [requirements.md](requirements.md) define independent
+input and behavior rules for an instance method, a class method, and a module
+method. The two declarations below select those same methods in equivalent
+ways and produce the same canonical target identities, contract digest, and
+obligation IDs.
+
+Run from the `gems/specproof` directory with the checkout's Ruby and bundle:
+
+```sh
+bundle exec ruby -Ilib exe/specproof plan examples/method_targets/specification_strings.rb --format json > tmp/method-targets-strings.json
+bundle exec ruby -Ilib exe/specproof plan examples/method_targets/specification_objects.rb --format json > tmp/method-targets-objects.json
+```
+
+The first command uses strings and does not load or autoload the application
+owners. The second loads the definitions so Ruby can provide one
+`UnboundMethod` and two `Method` objects; SpecProof inspects those objects
+without invoking the methods. Compare `contract_digest` and the typed
+obligation `id`/`target` pairs in the reports. The target fields remain
+canonical strings, such as `DeliveryOptions#build` and
+`DeliveryDefaults.build`.
+
+String declarations are a good fit for offline checking or planning when
+application loading is unavailable or could trigger autoload. Method objects
+are useful in runtime declarations after code has loaded. They must refer to
+directly defined public methods on named classes/modules and remain current at
+declaration time. Aliases, inherited singleton methods, anonymous owners, and
+bound methods on arbitrary instances are unsupported. Editor navigation from
+target names depends on language-server support.

data/examples/method_targets/lib/delivery_defaults.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Provides a region-specific shipping default.
+module DeliveryDefaults
+  def self.build(region:)
+    { carrier: region == :local ? :nearby : :national }
+  end
+end

data/examples/method_targets/lib/delivery_options.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Builds delivery options for requested quantities and scheduling modes.
+class DeliveryOptions
+  def build(quantity:)
+    { quantity: quantity, package: quantity.zero? ? :empty : :parcel }
+  end
+
+  def self.build(mode:)
+    { mode: mode, schedule_at_checkout: mode == :scheduled }
+  end
+end

data/examples/method_targets/requirements.md

@@ -0,0 +1,20 @@
+# Independent requirements
+
+These rules define the example's expected behavior independently of its Ruby
+implementation:
+
+- An instance delivery build accepts quantities from `0` through `100`; a
+  zero quantity selects the `:empty` package and every positive quantity
+  selects `:parcel` in its result.
+- The class-level delivery builder supports `:scheduled` and `:immediate`;
+  scheduling at checkout is enabled only for `:scheduled`.
+- The module-level default builder supports `:local` and `:remote`; local
+  delivery selects the `:nearby` carrier and remote delivery selects
+  `:national`.
+
+The two specification files encode the same input domains and canonical target
+names. `specification_strings.rb` can be planned without loading these methods.
+`specification_objects.rb` loads the file and demonstrates equivalent
+`UnboundMethod`/`Method` selections. The runtime methods exist to make those
+objects available; the requirements above remain the source of expected
+behavior.

data/examples/method_targets/specification_objects.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "specproof"
+require_relative "lib/delivery_options"
+require_relative "lib/delivery_defaults"
+
+SpecProof.define DeliveryOptions.instance_method(:build) do
+  input :quantity, range: 0..100
+end
+
+SpecProof.define DeliveryOptions.method(:build) do
+  input :mode, values: %i[immediate scheduled]
+end
+
+SpecProof.define DeliveryDefaults.method(:build) do
+  input :region, values: %i[local remote]
+end

data/examples/method_targets/specification_strings.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "specproof"
+
+SpecProof.define "DeliveryOptions#build" do
+  input :quantity, range: 0..100
+end
+
+SpecProof.define "DeliveryOptions.build" do
+  input :mode, values: %i[immediate scheduled]
+end
+
+SpecProof.define "DeliveryDefaults.build" do
+  input :region, values: %i[local remote]
+end

data/examples/pairwise/README.md

@@ -0,0 +1,46 @@
+# Pairwise input scenarios
+
+The [requirements](requirements.md) independently say that express speed is
+selected exactly when `expedited` is true, and the notification flag follows
+`notify`. The input declaration describes finite booleans; it does not encode
+those output rules.
+
+Run these commands from the `gems/specproof` directory with its development
+bundle:
+
+```sh
+bundle exec ruby -Ilib exe/specproof plan examples/pairwise/specification.rb --criterion pairwise-finite-v1 --format json
+bundle exec ruby examples/pairwise/run.rb initial
+bundle exec ruby examples/pairwise/run.rb gap
+bundle exec ruby examples/pairwise/run.rb corrected
+bundle exec ruby -Ilib exe/specproof plan examples/pairwise/constrained_specification.rb --criterion pairwise-finite-v1 --format json
+bundle exec ruby -Ilib exe/specproof plan examples/pairwise/three_boolean_specification.rb --criterion pairwise-finite-v1 --format json
+bundle exec ruby examples/pairwise/run.rb three
+```
+
+The plan has four pair obligations for the two booleans. The `initial` process
+runs three independent assertions for `00`, `01`, and `10`: all three tests
+pass and coverage is 3/4. The faulty method computes the notification flag as
+`notify && !expedited`; it agrees with the requirement on those three cases.
+The `gap` process repeats them and adds the requirement-backed `11` assertion.
+That assertion fails, although all four pair obligations have now been
+exercised (4/4). The `corrected` process uses a separate implementation and
+passes all four assertions with 4/4 pair coverage. Each mode runs in its own
+process so the implementations never coexist.
+
+The constrained declaration has its own [requirement](constrained_requirements.md):
+expedited delivery requires notification. It explicitly forbids
+`expedited: true, notify: false`, so the plan has three required pairs and one
+`excluded_pairs` row with `reason: "no_allowed_completion"`. This rule is not
+used by the unconstrained example and must not be inferred from the faulty
+implementation.
+
+The three-boolean declaration has 12 possible pair rows. Four calls, `000`,
+`011`, `101`, and `110`, exercise all 12. That is pair coverage for the three
+input pairs; it does not claim all eight full tuples were run or that all
+application behavior is covered.
+
+Each runner mode writes a fresh report below `tmp/pairwise-*.json`. Compare its
+criterion, digest, typed pair rows, run ID, integrity, and `tests_passed` with
+the current plan and command. Coverage records method calls; the assertions
+derive expected values from the separate requirements file.

data/examples/pairwise/constrained_requirements.md

@@ -0,0 +1,6 @@
+# Constrained delivery requirement
+
+For this separate target, expedited delivery requires notification. Therefore
+the full tuple `expedited: true, notify: false` is invalid. The other three
+boolean tuples are allowed. This requirement justifies the explicit forbidden
+assignment in `constrained_specification.rb`.

data/examples/pairwise/constrained_specification.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "specproof"
+
+SpecProof.define "ConstrainedDelivery#build" do
+  input :expedited, values: [false, true]
+  input :notify, values: [false, true]
+  combinations :expedited, :notify do
+    forbid expedited: true, notify: false
+  end
+end

data/examples/pairwise/corrected/lib/delivery_options.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Builds the delivery choices from the two option flags.
+class DeliveryOptions
+  def build(expedited:, notify:)
+    {
+      speed: expedited ? :express : :standard,
+      notification: notify
+    }
+  end
+end

data/examples/pairwise/corrected/test/delivery_options_test.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Checks the corrected implementation against each stated delivery rule.
+class CorrectedDeliveryOptionsTest < Minitest::Test
+  def setup
+    @delivery_options = DeliveryOptions.new
+  end
+
+  def test_standard_delivery_without_notification
+    assert_equal({ speed: :standard, notification: false },
+                 @delivery_options.build(expedited: false, notify: false))
+  end
+
+  def test_standard_delivery_with_notification
+    assert_equal({ speed: :standard, notification: true },
+                 @delivery_options.build(expedited: false, notify: true))
+  end
+
+  def test_express_delivery_without_notification
+    assert_equal({ speed: :express, notification: false },
+                 @delivery_options.build(expedited: true, notify: false))
+  end
+
+  def test_express_delivery_with_notification
+    assert_equal({ speed: :express, notification: true },
+                 @delivery_options.build(expedited: true, notify: true))
+  end
+end

data/examples/pairwise/faulty/lib/delivery_options.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Builds the delivery choices with the documented interaction defect.
+class DeliveryOptions
+  def build(expedited:, notify:)
+    {
+      speed: expedited ? :express : :standard,
+      notification: notify && !expedited
+    }
+  end
+end

data/examples/pairwise/faulty/test/gap_delivery_options_test.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Adds the requirement-backed pair missing from the baseline tests.
+class GapDeliveryOptionsTest < Minitest::Test
+  def test_express_delivery_with_notification
+    assert_equal({ speed: :express, notification: true },
+                 DeliveryOptions.new.build(expedited: true, notify: true),
+                 "Requirement: notification follows notify; see requirements.md")
+  end
+end

data/examples/pairwise/faulty/test/initial_delivery_options_test.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Covers the three baseline option combinations.
+class InitialDeliveryOptionsTest < Minitest::Test
+  def setup
+    @delivery_options = DeliveryOptions.new
+  end
+
+  def test_standard_delivery_without_notification
+    assert_equal({ speed: :standard, notification: false },
+                 @delivery_options.build(expedited: false, notify: false))
+  end
+
+  def test_standard_delivery_with_notification
+    assert_equal({ speed: :standard, notification: true },
+                 @delivery_options.build(expedited: false, notify: true))
+  end
+
+  def test_express_delivery_without_notification
+    assert_equal({ speed: :express, notification: false },
+                 @delivery_options.build(expedited: true, notify: false))
+  end
+end

data/examples/pairwise/requirements.md

@@ -0,0 +1,11 @@
+# Delivery option requirements
+
+These are the normative requirements for `DeliveryOptions#build`:
+
+1. Speed is `:express` exactly when `expedited` is true; otherwise it is
+   `:standard`.
+2. The notification flag equals `notify`, independent of the speed selection.
+
+Both inputs are booleans. Every combination is valid for this example. The
+faulty and corrected implementations are judged against these rules, not used
+to derive them.

data/examples/pairwise/run.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "minitest/autorun"
+require "specproof/minitest"
+
+mode = ARGV.shift || "corrected"
+output = ARGV.shift || File.expand_path("../../tmp/pairwise-#{mode}.json", __dir__)
+implementations = {
+  "initial" => ["faulty/lib/delivery_options.rb"],
+  "gap" => ["faulty/lib/delivery_options.rb"],
+  "corrected" => ["corrected/lib/delivery_options.rb"],
+  "three" => ["three_boolean/lib/boolean_batch.rb"]
+}.freeze
+test_files = {
+  "initial" => ["faulty/test/initial_delivery_options_test.rb"],
+  "gap" => ["faulty/test/initial_delivery_options_test.rb", "faulty/test/gap_delivery_options_test.rb"],
+  "corrected" => ["corrected/test/delivery_options_test.rb"],
+  "three" => ["three_boolean/test/boolean_batch_test.rb"]
+}.freeze
+specifications = {
+  "initial" => "specification.rb",
+  "gap" => "specification.rb",
+  "corrected" => "specification.rb",
+  "three" => "three_boolean_specification.rb"
+}.freeze
+abort "Choose initial, gap, corrected, or three" unless implementations.key?(mode)
+
+require File.join(__dir__, implementations.fetch(mode).first)
+SpecProof::Minitest.install!(
+  specifications: [File.join(__dir__, specifications.fetch(mode))],
+  criterion: "pairwise-finite-v1",
+  output: output,
+  fail_on_missing: false
+)
+test_files.fetch(mode).each { |path| require File.join(__dir__, path) }

data/examples/pairwise/specification.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "specproof"
+
+SpecProof.define "DeliveryOptions#build" do
+  input :expedited, values: [false, true]
+  input :notify, values: [false, true]
+  combinations :expedited, :notify, all_allowed: true
+end

data/examples/pairwise/three_boolean/lib/boolean_batch.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Returns the three finite boolean inputs as a batch result.
+class BooleanBatch
+  def build(first:, second:, third:)
+    [first, second, third]
+  end
+end