bcdd-contract 0.1.0

data/examples/business_processes/README.md

@@ -0,0 +1,245 @@
+- [📈 Business Processes](#-business-processes)
+- [💻 Self-Documented Code](#-self-documented-code)
+  - [Why use a division as an example?](#why-use-a-division-as-an-example)
+  - [What are the challenges of dividing numbers?](#what-are-the-challenges-of-dividing-numbers)
+  - [What are NaN and Infinity numbers?](#what-are-nan-and-infinity-numbers)
+  - [Representing a Process as Code](#representing-a-process-as-code)
+- [⚖️ What are the benefits of using this pattern?](#️-what-are-the-benefits-of-using-this-pattern)
+  - [Is it worth the overhead of contract checking at runtime?](#is-it-worth-the-overhead-of-contract-checking-at-runtime)
+- [🏃‍♂️ How to run the application?](#️-how-to-run-the-application)
+
+## 📈 Business Processes
+
+**What is a Process?**
+
+A process is a series of steps or actions performed in a specific order to achieve an outcome. These steps streamline operations, reduce errors, and enhance productivity.
+
+Processes can be documented, analyzed, comprehended, and continuously improved to change and adapt to new circumstances/requirements.
+
+**What is a Business Process in Software?**
+
+In software, a business process refers to a structured sequence of tasks or activities that embody a particular function or operation within a business.
+
+For example, if a business involves product sales, it'll have distinct processes for receiving orders, processing payments, and shipping products. These processes are and reflect the business's core operations. So, the sum of these processes is the business or the software that automates/represents it.
+
+## 💻 Self-Documented Code
+
+In this example, we'll use the [`BCDD::Result`](https://github.com/B-CDD/result) and `BCDD::Contract` to express a division of two numbers.
+
+Is this a business process? If your business involves dividing numbers, yes, it is. 😛
+
+### Why use a division as an example?
+
+Because it's simple to understand and complex enough to show the benefits of using this pattern.
+
+### What are the challenges of dividing numbers?
+
+- The dividend and divisor must be valid numbers (not `NaN` or `Infinity`).
+- The divisor must be different from zero.
+- If the dividend is zero, the result must be zero.
+- The result must be a valid number (not `NaN` or `Infinity`).
+
+### What are NaN and Infinity numbers?
+
+```ruby
+nan = 0.0 / 0.0 # => NaN
+inf = 1.0 / 0.0 # => Infinity
+
+nan.is_a?(Numeric) # => true
+inf.is_a?(Numeric) # => true
+
+nan / 2 # => NaN
+inf / 2 # => Infinity
+
+inf / nan # => NaN
+nan / inf # => NaN
+```
+
+Yes, Ruby has these "numbers". 😅
+
+### Representing a Process as Code
+
+```ruby
+class Division
+  module Contract
+    not_nan = -> { _1.respond_to?(:nan?) and _1.nan? and '%p cannot be nan' }
+    not_inf = -> { _1.respond_to?(:infinite?) and _1.infinite? and '%p cannot be infinite' }
+
+    FiniteNumber = ::BCDD::Contract[Numeric] & not_nan & not_inf
+    CannotBeZero = ::BCDD::Contract[-> { _1.zero? and 'cannot be zero' }]
+  end
+
+  include ::BCDD::Result::Expectations.mixin(
+    config:  { addon: { continue: true } },
+    success: { division_completed: Contract::FiniteNumber },
+    failure: {
+      invalid_arg:      ->(value) { value in [Symbol, Array] },
+      division_by_zero: ->(value) { value in [:arg2, Array] }
+    }
+  )
+
+  def call(arg1, arg2)
+    ::BCDD::Result.transitions(name: 'Division', desc: 'divide two numbers') do
+      Given([Contract::FiniteNumber[arg1], Contract::FiniteNumber[arg2]])
+        .and_then(:require_numbers)
+        .and_then(:check_for_zeros)
+        .and_then(:divide)
+    end
+  end
+
+  private
+
+  def require_numbers((arg1, arg2))
+    arg1.invalid? and return Failure(:invalid_arg, [:arg1, arg1.errors])
+    arg2.invalid? and return Failure(:invalid_arg, [:arg2, arg2.errors])
+
+    Continue([arg1.value, arg2.value])
+  end
+
+  def check_for_zeros(numbers)
+    num1 = numbers[0]
+    num2 = Contract::CannotBeZero[numbers[1]]
+
+    num2.invalid? and return Failure(:division_by_zero, [:arg2, num2.errors])
+
+    num1.zero? and return Success(:division_completed, 0)
+
+    Continue(numbers)
+  end
+
+  def divide((num1, num2))
+    Success(:division_completed, num1 / num2)
+  end
+end
+```
+
+Let's break it down.
+
+```ruby
+module Contract
+  module Contract
+    not_nan = -> { _1.respond_to?(:nan?) and _1.nan? and '%p cannot be nan' }
+    not_inf = -> { _1.respond_to?(:infinite?) and _1.infinite? and '%p cannot be infinite' }
+
+    FiniteNumber = ::BCDD::Contract[Numeric] & not_nan & not_inf
+    CannotBeZero = ::BCDD::Contract[-> { _1.zero? and 'cannot be zero' }]
+  end
+```
+
+The `Contract` module defines the contracts the `Division` class uses. The `FiniteNumber` ensures the value is numeric, not `NaN` or `Infinity`. The `CannotBeZero` contract ensures the value is not zero.
+
+The lambda is the contract unit checker. It receives two arguments: the value to be validated and an array of errors. The checker will add an error to the array when the value is invalid.
+
+**What is a contract unit?**
+
+It's a single or as part of a contract composition. It can perform validations and type checking and be used for pattern matching.
+
+```ruby
+include ::BCDD::Result::Expectations.mixin(
+  config:  { addon: { continue: true } },
+  success: { division_completed: Contract::FiniteNumber },
+  failure: {
+    invalid_arg:      ->(value) { value in [Symbol, Array] },
+    division_by_zero: ->(value) { value in [:arg2, Array] }
+  }
+)
+```
+
+The `BCDD::Result::Expectations.mixin` is a mixin that adds the `Given()`, `Continue()`, `Success()`, and `Failure()` methods. It also defines a contract (the expectations) for the `Success()` and `Failure()` results. If the contract is unsatisfied, the result methods will raise an exception.
+
+**Note:** The `Contract::FiniteNumber` is being used to type-check the `:division_completed` result.
+
+```ruby
+def call(arg1, arg2)
+  ::BCDD::Result.transitions(name: 'Division', desc: 'divide two numbers') do
+    Given([Contract::FiniteNumber[arg1], Contract::FiniteNumber[arg2]])
+      .and_then(:require_numbers)
+      .and_then(:check_for_zeros)
+      .and_then(:divide)
+  end
+end
+```
+
+The `call` method uses the `BCDD::Result.transitions` method to track the result of each step (perform `result.transitions` to see it in action) within the business process. It starts with the `Given()` and uses the `and_then()` to chain the steps. The process will stop on the first `Success()` or `Failure()`. Based on this, the previous step must return a `Continue()` to achieve the next one.
+
+**Note:** the inputs were transformed into contract units by using the `[]` operator.
+
+```ruby
+def require_numbers((arg1, arg2))
+  arg1.invalid? and return Failure(:invalid_arg, [:arg1, arg1.errors])
+  arg2.invalid? and return Failure(:invalid_arg, [:arg2, arg2.errors])
+
+  Continue([arg1.value, arg2.value])
+end
+```
+
+The `require_numbers` method receives the inputs as a tuple (an array with two elements). It checks if the inputs are valid and returns `Continue()` with the contract unit values or a `Failure()` with the contract unit errors.
+
+```ruby
+def check_for_zeros(numbers)
+  num1 = numbers[0]
+  num2 = Contract::CannotBeZero[numbers[1]]
+
+  num2.invalid? and return Failure(:division_by_zero, [:arg2, num2.errors])
+
+  num1.zero? and return Success(:division_completed, 0)
+
+  Continue(numbers)
+end
+```
+
+The `check_for_zeros` method receives the inputs as an array. It uses the `Contract::CannotBeZero` to check if the second input is zero. If it is, it returns a `Failure()` with the contract errors. If the first input is zero, it returns a `Success()` with `0` to stop the process. Otherwise, it returns a `Continue()` to continue it.
+
+```ruby
+def divide((num1, num2))
+  Success(:division_completed, num1 / num2)
+end
+```
+
+The `divide` method is the last step. If it was reached, it means the inputs are valid and the divisor is not zero. So, it returns a `Success()` with the result of the division.
+
+## ⚖️ What are the benefits of using this pattern?
+
+- The process is
+  - reliable. (Contracts for inputs and outputs)
+  - self-documented. (Is simple to understand)
+  - simple to test. (Every possible outcome is clear)
+  - simple to reuse. (The contracts and processes are reusable)
+  - simple to extend. (Just add a new step)
+  - simple to evolve. (The contracts and behaviors can be changed to support new requirements)
+  - simple to observe, monitor. (The transitions are tracked, each step is a method)
+
+### Is it worth the overhead of contract checking at runtime?
+
+You can eliminate the overhead by disabling the `BCDD::Result` expectations, which are the result contract checkers. Use it in dev/test environments to ensure the contracts are satisfied and disable it in production.
+
+```ruby
+BCDD::Result.configuration do |config|
+  config.feature.disable!(:expectations) if ::Rails.env.production?
+end
+```
+
+## 🏃‍♂️ How to run the application?
+
+In the same directory as this `README`, run:
+
+```bash
+rake
+
+# Output sample:
+#
+# --  Failures  --
+#
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg1, ["\"10\" must be numeric"]]>
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg2, ["\"2\" must be numeric"]]>
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg1, ["cannot be nan"]]>
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg2, ["cannot be infinite"]]>
+# #<BCDD::Result::Failure type=:division_by_zero value=[:arg2, ["cannot be zero"]]>
+# #<BCDD::Result::Failure type=:division_by_zero value=[:arg2, ["cannot be zero"]]>
+#
+# --  Successes  --
+#
+# #<BCDD::Result::Success type=:division_completed value=0>
+# #<BCDD::Result::Success type=:division_completed value=0>
+# #<BCDD::Result::Success type=:division_completed value=5>
+```

data/examples/business_processes/Rakefile

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+if RUBY_VERSION <= '3.1'
+  puts 'This example requires Ruby 3.1 or higher.'
+  exit! 1
+end
+
+require_relative 'config'
+
+task :default do
+  puts '=================================================='
+  puts 'Business Processes = BCDD::Result + BCDD::Contract'
+  puts '=================================================='
+
+  puts
+  puts '--  Failures  --'
+  puts
+
+  p Division.new.call('10', 2)
+  p Division.new.call(10, '2')
+  p Division.new.call(Float::NAN, 2)
+  p Division.new.call(10, Float::INFINITY)
+  p Division.new.call(10, 0)
+  p Division.new.call(10, 0.0)
+
+  puts
+  puts '--  Successes  --'
+  puts
+
+  p Division.new.call(0, 2)
+  p Division.new.call(0.0, 2)
+  p Division.new.call(10, 2)
+end
+
+# Output sample: rake
+#
+# --  Failures  --
+#
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg1, ["\"10\" must be numeric"]]>
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg2, ["\"2\" must be numeric"]]>
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg1, ["cannot be nan"]]>
+# #<BCDD::Result::Failure type=:invalid_arg value=[:arg2, ["cannot be infinite"]]>
+# #<BCDD::Result::Failure type=:division_by_zero value=[:arg2, ["cannot be zero"]]>
+# #<BCDD::Result::Failure type=:division_by_zero value=[:arg2, ["cannot be zero"]]>
+#
+# --  Successes  --
+#
+# #<BCDD::Result::Success type=:division_completed value=0>
+# #<BCDD::Result::Success type=:division_completed value=0>
+# #<BCDD::Result::Success type=:division_completed value=5>

data/examples/business_processes/config.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+$LOAD_PATH.unshift(__dir__)
+
+gemfile do
+  source 'https://rubygems.org'
+
+  gem 'bcdd-result', '>= 0.12.0'
+  gem 'bcdd-contract', path: '../../'
+end
+
+require 'lib/division'

data/examples/business_processes/lib/division.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# This class ensures the division of two valid numbers.
+#
+# It uses BCDD::Result to represent the operation as a process
+# (a series of steps to achieve a particular result).
+#
+class Division
+  module Contract
+    not_nan = -> { _1.respond_to?(:nan?) and _1.nan? and '%p cannot be nan' }
+    not_inf = -> { _1.respond_to?(:infinite?) and _1.infinite? and '%p cannot be infinite' }
+
+    FiniteNumber = ::BCDD::Contract[Numeric] & not_nan & not_inf
+    CannotBeZero = ::BCDD::Contract[-> { _1.zero? and 'cannot be zero' }]
+  end
+
+  include ::BCDD::Result::Expectations.mixin(
+    config:  { addon: { continue: true } },
+    success: { division_completed: Contract::FiniteNumber },
+    failure: {
+      invalid_arg:      ->(value) { value in [Symbol, Array] },
+      division_by_zero: ->(value) { value in [:arg2, Array] }
+    }
+  )
+
+  def call(arg1, arg2)
+    ::BCDD::Result.transitions(name: 'Division', desc: 'divide two numbers') do
+      Given([Contract::FiniteNumber[arg1], Contract::FiniteNumber[arg2]])
+        .and_then(:require_numbers)
+        .and_then(:check_for_zeros)
+        .and_then(:divide)
+    end
+  end
+
+  private
+
+  def require_numbers((arg1, arg2))
+    arg1.invalid? and return Failure(:invalid_arg, [:arg1, arg1.errors])
+    arg2.invalid? and return Failure(:invalid_arg, [:arg2, arg2.errors])
+
+    Continue([arg1.value, arg2.value])
+  end
+
+  def check_for_zeros(numbers)
+    num1 = numbers[0]
+    num2 = Contract::CannotBeZero[numbers[1]]
+
+    num2.invalid? and return Failure(:division_by_zero, [:arg2, num2.errors])
+
+    num1.zero? and return Success(:division_completed, 0)
+
+    Continue(numbers)
+  end
+
+  def divide((num1, num2))
+    Success(:division_completed, num1 / num2)
+  end
+end

data/examples/design_by_contract/README.md

@@ -0,0 +1,227 @@
+- [📜 Design by Contract Example](#-design-by-contract-example)
+- [A Shopping Cart](#a-shopping-cart)
+  - [The implementation](#the-implementation)
+    - [What are the preconditions in this code?](#what-are-the-preconditions-in-this-code)
+    - [What are the postconditions in this code?](#what-are-the-postconditions-in-this-code)
+    - [What is the invariant in this code?](#what-is-the-invariant-in-this-code)
+- [⚖️ What are the benefits of using this pattern?](#️-what-are-the-benefits-of-using-this-pattern)
+  - [How much to do this (apply DbC)?](#how-much-to-do-this-apply-dbc)
+  - [Is it worth the overhead of contract checking at runtime?](#is-it-worth-the-overhead-of-contract-checking-at-runtime)
+- [🏃‍♂️ How to run the application?](#️-how-to-run-the-application)
+
+## 📜 Design by Contract Example
+
+The **Design by Contract**, or DbC, is an approach where components define their expected behavior with preconditions, postconditions, and invariants, enhancing reliability and code understanding.
+
+These are the key concepts of DbC:
+
+- **Preconditions:** Conditions that must be met before a method is executed. They specify the input requirements/expectations.
+
+- **Postconditions:** Conditions that must hold true after the method has completed its execution. They specify the guarantees or outcomes.
+
+- **Invariants:** Invariants are conditions that should always be true for a specific module or class throughout its execution. They represent the essential properties that should never be violated.
+
+- **Assertions:** Are statements or checks placed within the code to validate that preconditions, postconditions, and invariants are being satisfied. If an assertion fails, it indicates a violation of the contract, highlighting a potential bug or issue.
+
+## A Shopping Cart
+
+What if we want to create a shopping cart that:
+- Features
+  - Can add items to the cart
+  - Can remove items from the cart
+  - Can calculate the total price of the cart
+  - Has a list of items with a name, quantity, and price per unit.
+- To add or remove an item
+  - The name must be a non-empty string.
+  - The quantity must be a positive integer.
+  - The per unit must be a positive valid number (numeric, not infinite or nan).
+- To remove an item
+  - The item name must exist in the cart.
+  - The cart must have enough quantity.
+  - If the quantity is zero, the item must be removed from the cart.
+- Before and after each operation, the cart must be valid:
+  - The items must have a valid name (not-blank), quantity (cannot be negative), and price per unit (positive valid number).
+  - This is an **invariant**. It should always be true.
+
+### The implementation
+
+```ruby
+class ShoppingCart
+  module Item
+    module Contract
+      cannot_be_nan = ->(val) { val.respond_to?(:nan?) and val.nan? and '%p cannot be nan' }
+      cannot_be_inf = ->(val) { val.respond_to?(:infinite?) and val.infinite? and '%p cannot be infinite' }
+      must_be_positive = ->(label) { ->(val) { val.positive? or "#{label} (%p) must be positive" } }
+
+      PricePerUnit = ::BCDD::Contract[::Numeric] & cannot_be_nan & cannot_be_inf & must_be_positive['price per unit']
+      Quantity     = ::BCDD::Contract[::Integer] & must_be_positive['quantity']
+      Name         = ::BCDD::Contract[::String]  & ->(val) { val.empty? and 'item name must be filled' }
+
+      NameAndData = ::BCDD::Contract.pairs(Name => { quantity: Quantity, price_per_unit: PricePerUnit })
+    end
+  end
+
+  module Items
+    module Contract
+      extend ::BCDD::Contract[::Hash] & ->(items, errors) do
+        return if items.empty?
+
+        Item::Contract::NameAndData[items].then { |it| it.valid? or errors.concat(it.errors) }
+      end
+    end
+  end
+
+  def initialize(items = {})
+    @items = +Items::Contract[items]
+  end
+
+  def add_item(item_name, quantity, price_per_unit)
+    Items::Contract.invariant(@items) do |items|
+      item_name = +Item::Contract::Name[item_name]
+
+      item = items[item_name] ||= { quantity: 0, price_per_unit: 0 }
+
+      item[:price_per_unit] = +Item::Contract::PricePerUnit[price_per_unit]
+      item[:quantity]      += +Item::Contract::Quantity[quantity]
+    end
+  end
+
+  def remove_item(item_name, quantity)
+    Items::Contract.invariant(@items) do |items|
+      item_name = +Item::Contract::Name[item_name]
+      quantity  = +Item::Contract::Quantity[quantity]
+
+      item = items[item_name]
+
+      ::BCDD::Contract.assert!(item_name, 'item (%p) not found')
+      ::BCDD::Contract.refute!(item_name, 'item (%p) not enough quantity to remove') { quantity > item[:quantity] }
+
+      item[:quantity] -= quantity
+
+      item[:quantity].tap { |number| items.delete(item_name) if number.zero? }
+    end
+  end
+
+  def total_price
+    (+Items::Contract[@items]).sum { |_name, data| data[:quantity] * data[:price_per_unit] }
+  end
+end
+```
+
+#### What are the preconditions in this code?
+
+- The `add_item` method expects three arguments: `item_name`, `quantity`, and `price_per_unit`.
+
+```ruby
+def add_item(item_name, quantity, price_per_unit)
+  Items::Contract.invariant(@items) do |items|
+    item_name = +Item::Contract::Name[item_name]
+
+    item = items[item_name] ||= { quantity: 0, price_per_unit: 0 }
+
+    item[:quantity]      += +Item::Contract::Quantity[quantity]
+    item[:price_per_unit] = +Item::Contract::PricePerUnit[price_per_unit]
+  end
+end
+```
+
+**Contract:**
+
+- The name must be a non-empty string.
+- The quantity must be a positive integer.
+- The per unit must be a positive valid number (numeric, not infinite or nan).
+
+**Note:** The `+` operator is used to perform a strict validation, raising an exception if the input does not match the expected type.
+
+- The `remove_item` method expects two arguments: `item_name` and `quantity`.
+
+```ruby
+def remove_item(item_name, quantity)
+  Items::Contract.invariant(@items) do |items|
+    item_name = +Item::Contract::Name[item_name]
+    quantity  = +Item::Contract::Quantity[quantity]
+
+    item = items[item_name]
+
+    ::BCDD::Contract.assert!(item_name, 'item (%p) not found')
+    ::BCDD::Contract.refute!(item_name, 'item (%p) not enough quantity to remove') { quantity > item[:quantity] }
+
+    item[:quantity] -= quantity
+
+    item[:quantity].then { |number| items.delete(item_name) if number.zero? }
+  end
+end
+```
+
+**Contract:**
+
+- The name must be a non-empty string.
+- The quantity must be a positive integer.
+- The item name must exist in the cart.
+- The cart must have enough quantity.
+
+#### What are the postconditions in this code?
+
+Did you notice that all the methods are wrapped by the `Items::Contract.invariant` method?
+
+In this case, the `Items::Contract` contains the postconditions and the invariant.
+
+#### What is the invariant in this code?
+
+The invariant is the `Items::Contract` contract, which ensures that the items are valid before and after each operation.
+
+**Contract:**
+
+- The items must have a valid name (not-blank), quantity (cannot be negative), and price per unit (positive valid number).
+
+## ⚖️ What are the benefits of using this pattern?
+
+- The code will work properly, as the preconditions and postconditions are validated by each method.
+- The code is simple to understand and test, as the preconditions and postconditions are explicit.
+- The object is always valid, an invariant can be defined to ensure the object state is valid before and after each operation.
+
+### How much to do this (apply DbC)?
+
+It depends on the context. In this example, the `ShoppingCart` is a core application component, so it is worth applying DbC. However, if it was simple, it may not be worth it.
+
+Use some or all the DbC concepts (preconditions, postconditions, invariants, assertions) to ensure the behavior of critical components.
+
+### Is it worth the overhead of contract checking at runtime?
+
+Having a slow and correct code is better than a fast and incorrect code. Slow is relative as an I/O (DB query, network call, etc.) operation is much slower than a contract check.
+
+## 🏃‍♂️ How to run the application?
+
+In the same directory as this `README`, run:
+
+```bash
+rake
+
+# Output sample:
+#
+# --  Adding items  --
+#
+# Total Price: $7.5
+#
+# --  Removing items  --
+#
+# Total Price: $4.5
+#
+# --  Invalid input  --
+#
+# item (Apple) not enough quantity to remove
+#
+# --------------------------------------------
+# --  Violating the invariant deliberately  --
+# --------------------------------------------
+#
+# rake aborted!
+# BCDD::Contract::Error: (Apple: (quantity: "1" must be a Integer)) (BCDD::Contract::Error)
+# /.../lib/bcdd/contract/core/checking.rb:30:in `raise_validation_errors!'
+# /.../lib/bcdd/contract/core/checker.rb:18:in `invariant'
+# /.../examples/design_by_contract/lib/shopping_cart.rb:44:in `remove_item'
+# /.../examples/design_by_contract/Rakefile:52:in `block (2 levels) in <top (required)>'
+# /.../examples/design_by_contract/Rakefile:54:in `block in <top (required)>'
+# Tasks: TOP => default
+# (See full trace by running task with --trace)
+```

data/examples/design_by_contract/Rakefile

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+if RUBY_VERSION <= '3.1'
+  puts 'This example requires Ruby 3.1 or higher.'
+  exit! 1
+end
+
+require_relative 'config'
+
+task :default do
+  puts '==================='
+  puts 'Design by Contract '
+  puts '==================='
+  puts
+
+  cart = ShoppingCart.new
+
+  puts '--  Adding items  --'
+  puts
+
+  cart.add_item('Apple', 5, 1.5)
+
+  puts "Total Price: $#{cart.total_price}"
+  puts
+
+  puts '--  Removing items  --'
+  puts
+
+  cart.remove_item('Apple', 2)
+
+  puts "Total Price: $#{cart.total_price}"
+  puts
+
+  puts '--  Invalid input  --'
+  puts
+
+  begin
+    cart.remove_item('Apple', 4)
+  rescue StandardError => e
+    puts e.message
+  end
+
+  puts
+  puts '--------------------------------------------'
+  puts '--  Violating the invariant deliberately  --'
+  puts '--------------------------------------------'
+  puts
+
+  [
+    -> { cart.instance_variable_set(:@items, { 'Apple' => { quantity: [-1, '1'].sample, price_per_unit: 1.5 } }) },
+    -> { cart.instance_variable_set(:@items, { 'Apple' => { quantity: 1, price_per_unit: [-1.5, '1.5'].sample } }) },
+    -> { cart.instance_variable_set(:@items, { ['', nil].sample => { quantity: 1, price_per_unit: 1.5 } }) }
+  ].sample.call
+
+  [
+    -> { cart.add_item('Orange', 1, 1) },
+    -> { cart.remove_item('Apple', 1) },
+    -> { cart.total_price }
+  ].sample.call
+end

data/examples/design_by_contract/config.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+$LOAD_PATH.unshift(__dir__)
+
+gemfile do
+  source 'https://rubygems.org'
+
+  gem 'bcdd-contract', path: '../../'
+end
+
+require 'lib/shopping_cart'