diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..c47a701
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,16 @@
+{
+ "name": "php-deal",
+ "owner": {
+ "name": "PhpDeal"
+ },
+ "description": "Claude Code plugins of the PhpDeal Design by Contract framework for PHP",
+ "plugins": [
+ {
+ "name": "php-deal",
+ "source": "./",
+ "description": "Turns business specifications into self-checking PHP code with php-deal/framework contracts and into PHPUnit tests derived from those contracts.",
+ "category": "development",
+ "tags": ["php", "design-by-contract", "testing"]
+ }
+ ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..1911084
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,14 @@
+{
+ "name": "php-deal",
+ "displayName": "PhpDeal: Design by Contract",
+ "version": "2.0.0",
+ "description": "Turns business specifications into self-checking PHP code with php-deal/framework contracts (#[Verify], #[Ensure], #[Invariant]) and into PHPUnit tests derived from those contracts.",
+ "author": {
+ "name": "PhpDeal contributors",
+ "url": "https://github.com/php-deal/framework/graphs/contributors"
+ },
+ "homepage": "https://github.com/php-deal/framework",
+ "repository": "https://github.com/php-deal/framework",
+ "license": "MIT",
+ "keywords": ["php", "design-by-contract", "contracts", "preconditions", "postconditions", "invariants", "phpunit", "specification"]
+}
diff --git a/.gitattributes b/.gitattributes
index 68d9168..71a6223 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -9,5 +9,6 @@
/phpunit.xml.dist export-ignore
/CONTRIBUTING.md export-ignore
/AGENTS.md export-ignore
+/.claude-plugin export-ignore
*.php diff=php
diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php
index 7a12a6e..b022525 100644
--- a/.php-cs-fixer.dist.php
+++ b/.php-cs-fixer.dist.php
@@ -7,7 +7,7 @@
use PhpCsFixer\Runner\Parallel\ParallelConfigFactory;
$finder = Finder::create()
- ->in([__DIR__ . '/src', __DIR__ . '/tests', __DIR__ . '/demo'])
+ ->in([__DIR__ . '/src', __DIR__ . '/tests', __DIR__ . '/demo', __DIR__ . '/skills'])
->exclude(['cache'])
->append([__FILE__]);
diff --git a/AGENTS.md b/AGENTS.md
index e680191..6c0ea8e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,10 +41,13 @@ lowest-dependencies job and `composer audit`.
| `src/Exception/` | `ContractViolation` and its subclasses, `InvalidContractException`, `ExceptionInterface`. |
| `src/PHPStan/` | PHPStan extension (registered by `extension.neon`): members used only by contracts count as used. |
| `src/ContractApplication.php`| The aspect kernel; `registerAspects()` for apps that have their own kernel. |
-| `tests/Fixtures/` | Classes **woven** by the test bootstrap. Only this directory is in `includePaths`. |
+| `tests/Fixtures/` | Classes **woven** by the test bootstrap. Only this directory and the skill example are in `includePaths`. |
| `tests/Functional/` | Tests that call fixtures through real weaving. |
| `tests/Unit/` | Tests without weaving; `tests/Unit/Stub/FakeInvocation.php` is a hand-made `MethodInvocation`. |
+| `tests/Skill/` | Tests of the contract checker of the skill (suite `skill`, with the skill example). |
| `demo/` | Runnable example, also run in CI. |
+| `skills/design-by-contract/` | Agent Skill for users' AI agents: `SKILL.md`, `references/`, the contract checker in `scripts/`, and a worked example in `examples/` that the test suite weaves and runs. |
+| `.claude-plugin/` | Manifests that publish the repository as a Claude Code plugin marketplace with the skill. |
## How it works (read before changing behaviour)
@@ -100,4 +103,7 @@ lowest-dependencies job and `composer audit`.
1. `composer test` passes.
2. Behaviour changes are reflected in `README.md`, `CHANGELOG.md` and, if they break BC, `UPGRADE-2.0.md`.
-3. README code examples still work: they are meant to be copy-paste runnable.
+ Changes to expressions, variables, inheritance or weaving also go into `skills/design-by-contract/` (the skill
+ and its checker teach those rules to users' agents). Bump `version` in `.claude-plugin/plugin.json` together with
+ a release, and run `claude plugin validate . --strict` when you change the manifests.
+3. README and skill code examples still work: they are meant to be copy-paste runnable.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 536fd00..f74a376 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,10 @@ A rewrite for modern PHP. See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the migration
- Invariants are checked after the constructor.
- PHPStan extension: properties and methods used only by contracts are not reported as unused.
- GitHub Actions CI on PHP 8.4 and 8.5, PHPStan level 10 with strict rules, PHP-CS-Fixer.
+- Agent Skill `design-by-contract` for AI coding agents: turns business specifications into contracted code and
+ PHPUnit tests derived from the contracts. It is installable as a Claude Code plugin from this repository
+ (`/plugin marketplace add php-deal/framework`) (#36).
+- Static checker for contract expressions, `skills/design-by-contract/scripts/lint-contracts.php`.
### Changed
diff --git a/README.md b/README.md
index 8311fe1..36314c5 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,7 @@ new Account()->deposit(-10);
- [Writing expressions](#writing-expressions)
- [Handling violations](#handling-violations)
- [PHPStan integration](#phpstan-integration)
+- [AI coding agents](#ai-coding-agents)
- [Production](#production)
- [Upgrading from 1.x](#upgrading-from-1x)
- [Contributing](#contributing)
@@ -366,6 +367,35 @@ includes:
- vendor/php-deal/framework/extension.neon
```
+## AI coding agents
+
+PhpDeal ships an [Agent Skill](https://agentskills.io) that teaches AI coding agents to turn a business
+specification into self-checking code: it extracts the rules, maps each one to a `#[Verify]`, `#[Ensure]` or
+`#[Invariant]` (or to plain code for business errors), writes the classes, checks the contract expressions and
+derives PHPUnit tests from the contracts. The tests cover the examples of the specification, the boundaries of the
+preconditions and random sequences of valid calls.
+
+In Claude Code, install it as a plugin from this repository:
+
+```
+/plugin marketplace add php-deal/framework
+/plugin install php-deal@php-deal
+```
+
+Then ask for it, e.g. *"Implement docs/booking-spec.md with Design by Contract"*, or run
+`/php-deal:design-by-contract`. Other agents that read the Agent Skills format can use the folder
+[`skills/design-by-contract`](skills/design-by-contract) directly. It is also installed with the package, at
+`vendor/php-deal/framework/skills/design-by-contract`.
+
+The skill bundles a checker for contract expressions, which works without an AI as well. Contracts are strings, so
+neither PHP nor PHPStan see their mistakes. The checker reports syntax errors, misspelled variables, `$__old` or
+`$__result` in the wrong kind of contract, `$this` in static methods, names that `use` imports do not resolve, and
+more:
+
+```bash
+php vendor/php-deal/framework/skills/design-by-contract/scripts/lint-contracts.php src
+```
+
## Production
Contracts are a development and testing tool: every checked call costs an expression evaluation. The usual setup is
diff --git a/composer.json b/composer.json
index 49a80cf..a1278f9 100644
--- a/composer.json
+++ b/composer.json
@@ -52,8 +52,12 @@
"autoload-dev": {
"psr-4": {
"Demo\\": "demo/",
+ "Example\\Inventory\\": "skills/design-by-contract/examples/inventory/",
"PhpDeal\\Tests\\": "tests/"
- }
+ },
+ "classmap": [
+ "skills/design-by-contract/scripts/"
+ ]
},
"scripts": {
"cs": "php-cs-fixer check --diff",
diff --git a/phpstan.neon.dist b/phpstan.neon.dist
index d88373e..f8c11de 100644
--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -10,6 +10,7 @@ parameters:
- src
- tests
- demo
+ - skills
excludePaths:
- tests/cache (?)
- demo/cache (?)
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
index 840e4a0..2b3a8c4 100644
--- a/phpunit.xml.dist
+++ b/phpunit.xml.dist
@@ -22,6 +22,10 @@
tests/Functional
+
+ tests/Skill
+ skills/design-by-contract/examples
+
diff --git a/skills/design-by-contract/SKILL.md b/skills/design-by-contract/SKILL.md
new file mode 100644
index 0000000..33ad764
--- /dev/null
+++ b/skills/design-by-contract/SKILL.md
@@ -0,0 +1,182 @@
+---
+name: design-by-contract
+description: >-
+ Turns business specifications (requirements, user stories, acceptance criteria, domain rules) into self-checking
+ PHP code with php-deal/framework: #[Verify] preconditions, #[Ensure] postconditions and #[Invariant] invariants,
+ plus PHPUnit tests derived from those contracts. Use it to implement a spec in PHP with Design by Contract, to add
+ contracts to existing PHP classes, to turn business rules into preconditions, postconditions or invariants, to
+ generate tests from contracts, or to review and fix php-deal contract expressions.
+license: MIT
+compatibility: Needs PHP 8.4+ and php-deal/framework 2.x in the target project. PHPUnit is used for the tests.
+---
+
+# Design by Contract with PhpDeal
+
+Turn a business specification into PHP code that checks its own rules on every call, and into tests that exercise
+those rules. PhpDeal reads the contracts from native attributes. They hold PHP expressions as strings, and
+[Go! AOP](https://github.com/goaop/framework) evaluates them around the method:
+
+```php
+use PhpDeal\Attribute\{Ensure, Invariant, Verify};
+
+#[Invariant('$this->balance >= 0')] // always true between calls
+class Account
+{
+ private int $balance = 0;
+
+ #[Verify('$amount > 0')] // the caller's obligation, checked before the body
+ #[Ensure('$this->balance === $__old->balance + $amount')] // the method's promise, checked after it
+ public function deposit(int $amount): void
+ {
+ $this->balance += $amount;
+ }
+}
+```
+
+A broken contract throws `PreconditionViolation`, `PostconditionViolation` or `InvariantViolation`. A contract
+violation always means a bug in the caller or in the method. It never means invalid user input.
+
+## Workflow
+
+Copy this checklist and work through it:
+
+```
+- [ ] 1. Check the project setup
+- [ ] 2. Extract the rules from the specification and number them
+- [ ] 3. Classify every rule: precondition, postcondition, invariant, business error or not a contract
+- [ ] 4. Design the API: classes, interfaces, query methods for the preconditions
+- [ ] 5. Write the code with its contracts
+- [ ] 6. Run the contract checker, fix every error
+- [ ] 7. Derive the tests and run them
+- [ ] 8. Report the rule-to-contract table, the assumptions and the open questions
+```
+
+### 1. Check the project setup
+
+- `composer.json` requires `php-deal/framework` (2.x) and PHP 8.4 or newer. If it does not, ask before adding the
+ dependency with `composer require php-deal/framework`. Without a `composer.json` you can inspect, rely on the weaving
+ check in step 7: one test that breaks a precondition must throw `PreconditionViolation`.
+- Contracts are checked only in woven classes. `ContractApplication::getInstance()->init([...])` must run before the
+ classes are autoloaded, in the front controller and in the test bootstrap. Its `includePaths` must cover the
+ directory of the new classes. If the project already has its own Go! AOP kernel, it calls
+ `ContractApplication::registerAspects($container)` instead. Without weaving the attributes do nothing, so tests
+ pass without checking anything.
+- See [references/setup.md](references/setup.md) for the snippets.
+
+### 2. Extract the rules
+
+Read the specification and list every statement that constrains state, input, output or behaviour. Give each one a
+stable ID (`R1`, `R2`, ...), or keep the IDs the specification already uses. Quote the source wording. Do not invent
+rules. When the specification is ambiguous or silent, write the question down and pick the most conservative
+assumption, which is usually the stricter precondition. Data that the API needs but the specification only implies,
+such as an id or the name of the person who acts, is API design: add it, list it as an assumption (`A1`, `A2`, ...),
+and constrain it only as far as the code needs.
+
+### 3. Classify each rule
+
+| The specification says... | Use |
+|-----------------------------------------------------------------------------------|--------------------------------------------|
+| "only when", "must be", "at most", "requires": a condition the caller can check first | `#[Verify]` on the method |
+| "after X...", "increases by", "returns", "never changes Y": an effect of the call | `#[Ensure]` with `$__old` / `$__result` |
+| "always", "never", "at all times": a fact about the object | `#[Invariant]` on the class or interface |
+| "is rejected with the message...", "show an error": input from people or systems | Code that throws a domain exception, plus `#[Ensure]` for the success path |
+| Timing, notifications, persistence, permissions, other services | Not a contract: integration tests or code |
+
+Two points need judgement:
+
+- **Precondition or business error?** A precondition is a promise the caller can keep. It is off in production when
+ the kernel is not started, and its violation is a programming error. When the specification describes a reaction
+ to bad input (a message, a rejected status, a retry), implement that reaction in code. You can also add a
+ precondition at the boundary where the input has already been validated. Give the caller a query method
+ (`available()`, `canCancel()`) so that it can check a precondition before the call.
+- **Strength.** Write the strongest contract the specification supports. Prefer
+ `$this->total === $__old->total + $amount` to `$this->total > $__old->total`. Add frame conditions for state that
+ must not change: `#[Ensure('$this->reserved === $__old->reserved')]`.
+
+[references/spec-to-contracts.md](references/spec-to-contracts.md) has a catalogue of rule patterns with their
+contracts: ranges, state machines, collections, uniqueness, implications, money and dates.
+
+### 4. Design the API
+
+- Put contracts on an interface when it will have several implementations, and mark each implementation with
+ `#[Inherit]`. Without it the interface's preconditions do not apply, and a class that declares no contract
+ attribute of its own is not checked at all.
+- Keep complex predicates in a private method (`#[Verify('$this->isValidTransition($to)')]`). Contracts run in the
+ scope of the class, so they can call private methods and read private properties.
+- Expose cheap public query methods for the state that preconditions depend on.
+
+### 5. Write the code
+
+Expression rules. Every one of them breaks contracts silently when ignored:
+
+- Write expressions in **single quotes**: `#[Verify('$amount > 0')]`. In double quotes PHP would interpolate `$amount`.
+- **No `use` imports inside expressions.** Write class names fully qualified (`\App\Money::isValid($amount)`), and
+ global functions with a leading backslash (`\count($items)`). `self::`, `static::` and `parent::` work.
+- Arguments are available by parameter name, with defaults filled in. A variadic parameter is a list: check its
+ items (`\min($amounts) > 0`), because comparing the list with a number (`$amounts > 0`) is always true.
+- `$__result` (return value) and `$__old` (clone of the object before the call) exist only in `#[Ensure]`. `$__old`
+ is a **shallow** clone: compare scalars, or add a `__clone()` that copies mutable objects.
+- A contract returns `true` (holds), `false` (violated) or `null` (for assertion libraries). Any other value throws
+ `InvalidContractException`.
+- Contracts must have no side effects. Do not use `$this` in static methods.
+- Postconditions and invariants are not checked when the method throws.
+- `#[Verify]` and `#[Ensure]` work on every method: constructors, private, protected and static ones. Invariants are
+ checked after the constructor and after every **public** method, not after private ones. `final` classes are
+ woven as well.
+- In a constructor `$__result` is always `null` and `$__old` is the object before its properties are set: check
+ `$this` instead.
+
+[references/expressions.md](references/expressions.md) has the full reference and the pitfalls of floats, dates,
+enums, collections and nullables.
+
+Add the rule ID next to each contract, as a trailing comment or in the method docblock, so that a reader can trace
+it back to the specification.
+
+### 6. Check the contracts
+
+PHP and PHPStan do not see inside the expression strings. Run the bundled checker on the files you wrote:
+
+```bash
+php ${CLAUDE_SKILL_DIR}/scripts/lint-contracts.php --strict src/Inventory
+```
+
+`${CLAUDE_SKILL_DIR}` is the directory of this file. In projects with php-deal installed the checker is also at
+`vendor/php-deal/framework/skills/design-by-contract/scripts/lint-contracts.php`. It reports syntax errors, unknown
+or misspelled variables, `$__old` or `$__result` in the wrong contract, `$this` in static methods, imported names
+that do not resolve, double-quoted strings, assignments, the current time or random values, and `\in_array()`
+without `true`. Fix every error and warning. It can not check types or the existence of properties: the tests in the
+next step do that.
+
+### 7. Derive the tests
+
+Postconditions and invariants are checked on every call of a woven class. Any test that drives the object through
+valid calls therefore also tests them. Write these tests:
+
+1. **Specification examples.** Each example or acceptance criterion becomes a test with explicit assertions. This is
+ the independent oracle: a wrong contract and wrong code can agree with each other.
+2. **Precondition boundaries.** For each `#[Verify]`, call just inside the boundary (it passes) and just outside it
+ (`PreconditionViolation`, and the state is unchanged). This test also proves that weaving is active.
+3. **Business errors.** For each rejected input, assert the domain exception and its message.
+4. **Random valid sequences.** Sample arguments from the preconditions with a seeded `Random\Randomizer` and run a
+ few hundred calls. The contracts check every step.
+
+[references/testing.md](references/testing.md) explains each kind and shows the bootstrap. Run the tests. When one
+of them reports a violation, decide whether the code, the contract or the test is wrong. Do not weaken a contract to
+make a test pass unless the specification supports the weaker version.
+
+### 8. Report
+
+End with:
+
+- a table `Rule | Contract or code | Where | Test`, with one row per rule (`Where` is `Class::method`, or `Class` for
+ an invariant);
+- the assumptions you made, and the open questions for the business;
+- the rules that are not contracts, and where they are handled instead.
+
+## Worked example
+
+[examples/inventory/](examples/inventory) holds a complete run: [SPEC.md](examples/inventory/SPEC.md) (rules
+R1-R9), [StockItem.php](examples/inventory/StockItem.php) with its contracts,
+[CountBelowReserved.php](examples/inventory/CountBelowReserved.php) for the one business error, and
+[StockItemTest.php](examples/inventory/StockItemTest.php) with the four kinds of tests. Read it before the first
+implementation in a project. The PhpDeal test suite runs it, so it always works.
diff --git a/skills/design-by-contract/examples/inventory/CountBelowReserved.php b/skills/design-by-contract/examples/inventory/CountBelowReserved.php
new file mode 100644
index 0000000..73f989a
--- /dev/null
+++ b/skills/design-by-contract/examples/inventory/CountBelowReserved.php
@@ -0,0 +1,12 @@
+onHand >= 0')] // R2
+#[Invariant('$this->reserved >= 0 && $this->reserved <= $this->onHand')] // R3
+class StockItem
+{
+ public const string SKU_PATTERN = '/^[A-Z]{3}-\d{4}$/';
+
+ private int $onHand = 0;
+
+ private int $reserved = 0;
+
+ #[Verify('\preg_match(self::SKU_PATTERN, $sku) === 1')] // R1
+ public function __construct(public readonly string $sku) {}
+
+ public function onHand(): int
+ {
+ return $this->onHand;
+ }
+
+ public function reserved(): int
+ {
+ return $this->reserved;
+ }
+
+ /**
+ * Quantity that can still be reserved (R4)
+ */
+ #[Ensure('$__result === $this->onHand - $this->reserved')]
+ public function available(): int
+ {
+ return $this->onHand - $this->reserved;
+ }
+
+ /**
+ * Adds received goods to the stock on hand (R5)
+ */
+ #[Verify('$quantity > 0')]
+ #[Ensure('$this->onHand === $__old->onHand + $quantity')]
+ #[Ensure('$this->reserved === $__old->reserved')]
+ public function receive(int $quantity): void
+ {
+ $this->onHand += $quantity;
+ }
+
+ /**
+ * Reserves goods for an order; callers check {@see available()} first (R6)
+ */
+ #[Verify('$quantity > 0')]
+ #[Verify('$quantity <= $this->available()')]
+ #[Ensure('$this->reserved === $__old->reserved + $quantity')]
+ #[Ensure('$this->onHand === $__old->onHand')]
+ public function reserve(int $quantity): void
+ {
+ $this->reserved += $quantity;
+ }
+
+ /**
+ * Releases the reservation of a cancelled order (R7)
+ */
+ #[Verify('$quantity > 0 && $quantity <= $this->reserved')]
+ #[Ensure('$this->reserved === $__old->reserved - $quantity')]
+ #[Ensure('$this->onHand === $__old->onHand')]
+ public function release(int $quantity): void
+ {
+ $this->reserved -= $quantity;
+ }
+
+ /**
+ * Ships reserved goods out of the warehouse (R8)
+ */
+ #[Verify('$quantity > 0 && $quantity <= $this->reserved')]
+ #[Ensure('$this->onHand === $__old->onHand - $quantity')]
+ #[Ensure('$this->reserved === $__old->reserved - $quantity')]
+ public function ship(int $quantity): void
+ {
+ $this->onHand -= $quantity;
+ $this->reserved -= $quantity;
+ }
+
+ /**
+ * Replaces the quantity on hand with a stock count entered by staff (R9)
+ *
+ * The count comes from a person, so a count below the reservations is an expected business case: it is handled
+ * in code, not with a precondition.
+ *
+ * @throws CountBelowReserved When the count is lower than the reserved quantity
+ */
+ #[Verify('$counted >= 0')]
+ #[Ensure('$this->onHand === $counted')]
+ #[Ensure('$this->reserved === $__old->reserved')]
+ public function recordCount(int $counted): void
+ {
+ if ($counted < $this->reserved) {
+ throw new CountBelowReserved('Count is below the reserved quantity');
+ }
+ $this->onHand = $counted;
+ }
+}
diff --git a/skills/design-by-contract/examples/inventory/StockItemTest.php b/skills/design-by-contract/examples/inventory/StockItemTest.php
new file mode 100644
index 0000000..113e9af
--- /dev/null
+++ b/skills/design-by-contract/examples/inventory/StockItemTest.php
@@ -0,0 +1,168 @@
+receive(10);
+ $item->reserve(4);
+ $item->ship(3);
+
+ self::assertSame(7, $item->onHand());
+ self::assertSame(1, $item->reserved());
+ self::assertSame(6, $item->available());
+ }
+
+ /**
+ * R1, and a canary: when this test fails, the contracts are not woven at all
+ */
+ #[TestWith(['abc-1234'])]
+ #[TestWith(['ABC1234'])]
+ #[TestWith(['ABCD-123'])]
+ #[TestWith([''])]
+ public function testSkuMustMatchThePattern(string $sku): void
+ {
+ $this->expectException(PreconditionViolation::class);
+
+ $item = new StockItem($sku);
+ self::fail('The SKU was accepted: ' . $item->sku);
+ }
+
+ /**
+ * R6: the boundary of the precondition, exactly the available quantity is accepted
+ */
+ public function testAvailableQuantityCanBeReserved(): void
+ {
+ $item = self::itemWith(onHand: 5, reserved: 2);
+ $item->reserve(3);
+
+ self::assertSame(0, $item->available());
+ }
+
+ /**
+ * @param callable(StockItem): void $call
+ */
+ #[DataProvider('callsBreakingPreconditions')]
+ public function testCallerMustMeetThePreconditions(callable $call): void
+ {
+ $item = self::itemWith(onHand: 5, reserved: 2);
+
+ try {
+ $call($item);
+ self::fail('A precondition violation was expected');
+ } catch (PreconditionViolation) {
+ // The body did not run, so the state is unchanged
+ self::assertSame(5, $item->onHand());
+ self::assertSame(2, $item->reserved());
+ }
+ }
+
+ /**
+ * Calls just outside the boundaries of each precondition, with onHand 5 and reserved 2
+ *
+ * @return iterable
+ */
+ public static function callsBreakingPreconditions(): iterable
+ {
+ yield 'R5: receive nothing' => [static fn(StockItem $item) => $item->receive(0)];
+ yield 'R5: receive a negative amount' => [static fn(StockItem $item) => $item->receive(-1)];
+ yield 'R6: reserve nothing' => [static fn(StockItem $item) => $item->reserve(0)];
+ yield 'R6: reserve more than is free' => [static fn(StockItem $item) => $item->reserve(4)];
+ yield 'R7: release more than reserved' => [static fn(StockItem $item) => $item->release(3)];
+ yield 'R8: ship more than reserved' => [static fn(StockItem $item) => $item->ship(3)];
+ yield 'R8: ship nothing' => [static fn(StockItem $item) => $item->ship(0)];
+ yield 'R9: negative count' => [static fn(StockItem $item) => $item->recordCount(-1)];
+ }
+
+ /**
+ * R9: a business error, reported to the user, not a contract violation
+ */
+ public function testCountBelowTheReservationsIsRejected(): void
+ {
+ $item = self::itemWith(onHand: 5, reserved: 2);
+
+ try {
+ $item->recordCount(1);
+ self::fail('The count was expected to be rejected');
+ } catch (CountBelowReserved $error) {
+ self::assertSame('Count is below the reserved quantity', $error->getMessage());
+ self::assertSame(5, $item->onHand());
+ }
+ }
+
+ #[TestWith([2])]
+ #[TestWith([9])]
+ public function testCountReplacesTheQuantityOnHand(int $counted): void
+ {
+ $item = self::itemWith(onHand: 5, reserved: 2);
+ $item->recordCount($counted);
+
+ self::assertSame($counted, $item->onHand());
+ self::assertSame(2, $item->reserved());
+ }
+
+ /**
+ * Random sequences of valid calls: inputs are sampled from the preconditions, and the postconditions and
+ * invariants check every step. A seeded engine keeps a failure reproducible.
+ */
+ #[DataProvider('seeds')]
+ public function testRandomValidOperationsKeepEveryContract(int $seed): void
+ {
+ $random = new Randomizer(new Mt19937($seed));
+ $item = new StockItem('XYZ-0001');
+ for ($step = 0; $step < 200; ++$step) {
+ $operation = $random->getInt(0, 4);
+ if ($operation === 0) {
+ $item->receive($random->getInt(1, 50));
+ } elseif ($operation === 1 && $item->available() > 0) {
+ $item->reserve($random->getInt(1, $item->available()));
+ } elseif ($operation === 2 && $item->reserved() > 0) {
+ $item->release($random->getInt(1, $item->reserved()));
+ } elseif ($operation === 3 && $item->reserved() > 0) {
+ $item->ship($random->getInt(1, $item->reserved()));
+ } elseif ($operation === 4) {
+ $item->recordCount($random->getInt($item->reserved(), $item->onHand() + 10));
+ }
+ }
+
+ self::assertSame($item->onHand() - $item->reserved(), $item->available());
+ }
+
+ /**
+ * @return iterable
+ */
+ public static function seeds(): iterable
+ {
+ foreach ([1, 2, 3, 42, 2026] as $seed) {
+ yield "seed {$seed}" => [$seed];
+ }
+ }
+
+ private static function itemWith(int $onHand, int $reserved): StockItem
+ {
+ $item = new StockItem('ABC-1234');
+ $item->receive($onHand);
+ $item->reserve($reserved);
+
+ return $item;
+ }
+}
diff --git a/skills/design-by-contract/references/expressions.md b/skills/design-by-contract/references/expressions.md
new file mode 100644
index 0000000..7ea357d
--- /dev/null
+++ b/skills/design-by-contract/references/expressions.md
@@ -0,0 +1,129 @@
+# Contract expressions
+
+A contract is one PHP expression in a string. PhpDeal compiles it once into a closure and binds the closure to the
+object, in the scope of the class that declares the contract.
+
+## Contents
+
+- [Attributes](#attributes)
+- [Variables](#variables)
+- [Scope and names](#scope-and-names)
+- [Results and errors](#results-and-errors)
+- [Inheritance](#inheritance)
+- [Pitfalls](#pitfalls)
+
+## Attributes
+
+| Attribute | Target | Checked | Repeatable |
+|----------------|------------------|------------------------------------------------|------------|
+| `#[Verify]` | method | before the method body | yes |
+| `#[Ensure]` | method | after the method returns (not when it throws) | yes |
+| `#[Invariant]` | class, interface | after the constructor and every public method | yes |
+| `#[Inherit]` | method, class | enables the contracts of parents | no |
+
+Import them with `use PhpDeal\Attribute\{Ensure, Inherit, Invariant, Verify};`. Prefer one attribute per rule
+to one long `&&` chain: the violation message then names the exact rule that broke.
+
+## Variables
+
+| Variable | Available in | Value |
+|---------------------|----------------------------|--------------------------------------------------------------|
+| `$paramName` | `Verify`, `Ensure` | the argument, or its default value; a variadic is a list |
+| `$this` | all, not in static methods | the object |
+| `$__result` | `Ensure` | the return value (`null` for `void`) |
+| `$__old` | `Ensure` | a shallow clone of the object taken before the call |
+
+An invariant can technically see the arguments and the result of whichever public method ran last. Do not use them
+there: an invariant describes the object alone.
+
+## Scope and names
+
+- The expression can read private and protected members of the declaring class: `$this->balance`,
+ `$this->isValid($x)`, `self::LIMIT`, `static::$registry`. A contract of an interface runs in the scope of the
+ implementing class. A contract of a parent class runs in the scope of the parent and can read its private state.
+- The expression is compiled outside of your file, in the global namespace. `use` imports do **not** apply:
+ - classes, enums and interfaces are fully qualified: `$status === \App\Order\Status::Paid`,
+ `$at instanceof \DateTimeImmutable`;
+ - functions get a leading backslash: `\count()`, `\in_array($x, self::ALLOWED, true)`, `\preg_match(...)`;
+ - `self`, `static` and `parent` resolve as usual.
+- Strings inside the expression: use double quotes when they hold no `$`, as in `'$currency === "EUR"'`. Escape a
+ single quote as `\'`. Put regular expressions and lists in class constants: `'\preg_match(self::SKU, $sku) === 1'`.
+- A trailing `// comment` inside the string is allowed.
+
+## Results and errors
+
+| The expression... | Outcome |
+|-----------------------------------------------------|----------------------------------------------------------------|
+| returns `true` | the contract holds |
+| returns `null` | the contract holds (for assertion helpers that return nothing) |
+| returns `false` | `PreconditionViolation` / `PostconditionViolation` / `InvariantViolation` |
+| throws any `Throwable` | the violation, with the error as `getPrevious()` |
+| returns anything else (`1`, `'yes'`, an object) | `InvalidContractException`: the contract itself is broken |
+| has a syntax error, or uses `$this` in a static method | `InvalidContractException` |
+
+Assertion libraries work, because failures are exceptions:
+`#[Verify('\Assert\Assertion::email($email)')]`.
+
+While an expression runs, all contract checks are suspended. An invariant can therefore call public methods of its
+own class, `#[Invariant('$this->getBalance() >= 0')]`, without recursion.
+
+## Inheritance
+
+| Contract | Taken from parent classes and interfaces |
+|-------------|-----------------------------------------------------------------------------------------|
+| `Ensure` | always, when the method declares a postcondition itself or uses `#[Inherit]` |
+| `Invariant` | always, when the class declares an invariant itself or uses `#[Inherit]` |
+| `Verify` | only with `#[Inherit]` on the method or the class, or an `{@inheritdoc}` tag |
+
+A class without any contract attribute of its own and without `#[Inherit]` is not woven, even when its interface has
+contracts. Put `#[Inherit]` on every implementation of a contracted interface. Preconditions are opt-in because a
+subclass may accept more than its parent (Liskov: require no more, promise no less).
+
+## Pitfalls
+
+**Floats.** `0.1 + 0.2 === 0.3` is false. Keep money in integer minor units (cents), or compare with a tolerance:
+`'\abs($this->total - ($__old->total + $amount)) < 1e-9'`.
+
+**Shallow `$__old`.** `$__old` is `clone $this`. Objects inside it are the same instances as in `$this`, so
+`$__old->items->count()` already sees the change. Either store immutable values (arrays, scalars, value objects), or
+deep-copy in `__clone()`:
+
+```php
+public function __clone()
+{
+ $this->lines = clone $this->lines;
+}
+```
+
+The object is cloned only when an expression of the method contains `$__old`. When the class can not be cloned (a
+private `__clone()`, for example), `$__old` is undefined.
+
+**Arrays.** `===` on arrays compares keys, values, types and order, while `==` ignores order and types. Pick the one
+the rule means. For "nothing else changed" use `'$this->lines === $__old->lines'`.
+
+**Variadics.** `int ...$amounts` arrives as a list. `$amounts > 0` compares an array with a number and is always
+true. Check the items: `'$amounts !== [] && \min($amounts) > 0'`.
+
+**Constructors.** `#[Verify]` and `#[Ensure]` work on constructors. There `$__result` is always `null`, and `$__old`
+is a clone of the object before its properties are set, so reading a typed property from it fails. Check `$this`.
+
+**Nullables.** Guard first: `'$discount === null || ($discount > 0 && $discount <= 100)'`.
+
+**Implications.** "If shipped, it has a tracking number" is `'$this->status !== \App\Status::Shipped || $this->tracking !== null'`.
+
+**Dates.** `DateTimeImmutable` objects compare with `<`, `<=` and `==`. Pass the clock in as an argument or a
+property. Do not call `new \DateTimeImmutable()` inside a contract: a contract that depends on the current time
+can fail at random.
+
+**Strings.** Use `\mb_strlen()` for user-visible lengths and `\trim($name) !== ''` for "not blank".
+
+**Collections.** `'\count($items) > 0'`, `'\array_is_list($items)'`, every item:
+`'\count(\array_filter($items, static fn(int $i): bool => $i <= 0)) === 0'`, uniqueness:
+`'\count(\array_unique($ids)) === \count($ids)'`. Every expression runs on every call, so move an expensive
+check into a private method and keep it linear.
+
+**Uninitialized properties.** An invariant that reads a typed property before it is set throws an `Error`, which is
+reported as an `InvariantViolation` after the constructor. Initialize every property that an invariant reads.
+
+**Side effects.** A contract must not assign, increment, call mutating methods, log or perform I/O. Contracts are
+usually off in production, so the program must behave the same without them.
diff --git a/skills/design-by-contract/references/setup.md b/skills/design-by-contract/references/setup.md
new file mode 100644
index 0000000..f70691d
--- /dev/null
+++ b/skills/design-by-contract/references/setup.md
@@ -0,0 +1,80 @@
+# Project setup
+
+Contracts are checked only in classes that Go! AOP weaves. A class is woven when it is autoloaded through Composer
+after the kernel has started, and its file is inside `includePaths`.
+
+## Install
+
+```bash
+composer require php-deal/framework
+```
+
+PHP 8.4 or newer is required. Ask the user before adding the dependency to a project.
+
+## Start the kernel
+
+Start the kernel once, right after the Composer autoloader, before any class with contracts is loaded:
+
+```php
+use PhpDeal\ContractApplication;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+ContractApplication::getInstance()->init([
+ 'debug' => true, // re-weave changed files automatically
+ 'appDir' => __DIR__ . '/..', // the directory that contains vendor/
+ 'cacheDir' => __DIR__ . '/../var/cache/contracts', // writable, add it to .gitignore
+ 'includePaths' => [__DIR__ . '/../src'], // directories with contracts, keep it narrow
+]);
+```
+
+Typical places: `public/index.php`, `bin/console` and `tests/bootstrap.php` (set `bootstrap="tests/bootstrap.php"` in
+`phpunit.xml.dist`). In production the kernel is usually skipped:
+
+```php
+if (($_SERVER['APP_ENV'] ?? 'prod') !== 'prod') {
+ ContractApplication::getInstance()->init([/* ... */]);
+}
+```
+
+## Projects that already use Go! AOP
+
+Go! AOP runs one kernel per application. Register the aspects in the existing kernel instead:
+
+```php
+use Go\Core\AspectContainer;
+use Go\Core\AspectKernel;
+use PhpDeal\ContractApplication;
+
+final class ApplicationAspectKernel extends AspectKernel
+{
+ protected function configureAop(AspectContainer $container): void
+ {
+ ContractApplication::registerAspects($container);
+ }
+}
+```
+
+## PHPStan
+
+PhpDeal ships a PHPStan extension: private members used only by contracts are not reported as unused. With
+`phpstan/extension-installer` it is enabled automatically, otherwise add it to `phpstan.neon`:
+
+```neon
+includes:
+ - vendor/php-deal/framework/extension.neon
+```
+
+## Check that weaving works
+
+Write one test that breaks a precondition and expects `PhpDeal\Exception\PreconditionViolation`. If no exception is
+thrown, the class is not woven. Check the following:
+
+- the kernel starts before the class is autoloaded (no `require` of the class file, no class loaded earlier in the
+ bootstrap);
+- the file is inside `includePaths` and not inside `excludePaths`;
+- the cache is stale: delete `cacheDir` and run again.
+
+If the first run after deleting the cache crashes with a segmentation fault (exit code 139) and later runs pass,
+the PHP opcache JIT is crashing while classes are woven. Run once with `php -d opcache.jit=off vendor/bin/phpunit`,
+or turn the JIT off for the CLI in tests. This is a PHP problem, not a broken contract.
diff --git a/skills/design-by-contract/references/spec-to-contracts.md b/skills/design-by-contract/references/spec-to-contracts.md
new file mode 100644
index 0000000..fac3654
--- /dev/null
+++ b/skills/design-by-contract/references/spec-to-contracts.md
@@ -0,0 +1,172 @@
+# From business rules to contracts
+
+## Contents
+
+- [Reading a specification](#reading-a-specification)
+- [Contract or code?](#contract-or-code)
+- [Rule patterns](#rule-patterns)
+- [State machines](#state-machines)
+- [Aggregates and collections](#aggregates-and-collections)
+- [Rule table](#rule-table)
+
+## Reading a specification
+
+Go through the text sentence by sentence and mark:
+
+- **Nouns** that have state: they become classes or value objects (`Order`, `StockItem`, `Money`).
+- **Verbs** that change state: they become command methods (`reserve()`, `ship()`, `cancel()`).
+- **Questions** that callers ask: they become query methods (`available()`, `canCancel()`, `total()`).
+- **Constraints** ("must", "only", "never", "at most", "always", "unless", "until"): they become contracts or code.
+- **Examples** ("given 10 items, after reserving 4..."): they become tests.
+
+Keep one rule per line, with an ID and the original words. Split compound sentences: "Shipping removes the goods
+from stock and from the reservations" is two postconditions.
+
+## Contract or code?
+
+| Question | If yes |
+|--------------------------------------------------------------------------|-----------------------------------------------|
+| Does the rule describe a reaction that users or other systems see (a message, a status, a refund)? | Code with a domain exception or a result type |
+| Can the input come straight from a person, a file or a remote system? | Validate in code, at the boundary |
+| Must the rule still hold in production when the contract kernel is off? | Code (and an `Ensure` documenting the result) |
+| Is it an obligation of the calling code, which can check it first? | `#[Verify]` |
+| Is it a promise about the effect or the result of a method? | `#[Ensure]` |
+| Is it true of the object whenever no method is running? | `#[Invariant]` |
+| Is it about time, order of events in other systems, performance, security or persistence? | Not a contract |
+
+Contracts and code work together. The code handles the expected business cases. The contracts state what must then
+be true, and catch the cases that "can not happen":
+
+```php
+/**
+ * @throws CountBelowReserved R9: counts come from staff, a wrong count is an expected case
+ */
+#[Verify('$counted >= 0')] // R9: the form only accepts whole numbers >= 0
+#[Ensure('$this->onHand === $counted')] // R9: the count replaces the stock on hand
+#[Ensure('$this->reserved === $__old->reserved')] // frame condition: reservations are untouched
+public function recordCount(int $counted): void
+{
+ if ($counted < $this->reserved) {
+ throw new CountBelowReserved('Count is below the reserved quantity');
+ }
+ $this->onHand = $counted;
+}
+```
+
+## Rule patterns
+
+| Specification wording | Contract |
+|---------------------------------------------------------|---------------------------------------------------------------------------|
+| "The amount is positive" | `#[Verify('$amount > 0')]` |
+| "Between 1 and 100 percent" | `#[Verify('$percent >= 1 && $percent <= 100')]` |
+| "One of EUR, USD" | `#[Verify('\in_array($currency, self::CURRENCIES, true)')]` |
+| "A name is not blank and at most 80 characters" | `#[Verify('\trim($name) !== \'\' && \mb_strlen($name) <= 80')]` |
+| "The code looks like ABC-1234" | `#[Verify('\preg_match(self::CODE_PATTERN, $code) === 1')]` |
+| "Only when enough is available" | `#[Verify('$quantity <= $this->available()')]` |
+| "Only while the order is open" | `#[Verify('$this->status === \App\Order\Status::Open')]` |
+| "The end is after the start" | `#[Verify('$end > $start')]` |
+| "Adds the amount to the balance" | `#[Ensure('$this->balance === $__old->balance + $amount')]` |
+| "Does not change the items" | `#[Ensure('$this->items === $__old->items')]` |
+| "Returns a non-negative price" | `#[Ensure('$__result >= 0')]` |
+| "The discount never exceeds 30% of the total" | `#[Ensure('$__result <= \intdiv($total * 30, 100)')]` |
+| "Returns the order, now paid" | `#[Ensure('$__result->isPaid()')]` |
+| "The balance is never negative" | `#[Invariant('$this->balance >= 0')]` |
+| "Reserved never exceeds the stock" | `#[Invariant('$this->reserved <= $this->onHand')]` |
+| "Order numbers are unique within a batch" | `#[Invariant('\count(\array_unique($this->numbers)) === \count($this->numbers)')]` |
+
+Longer rules, written as `!A || B` for "if A then B" and with closures for sums:
+
+```php
+// "A shipped order always has a tracking number"
+#[Invariant('$this->status !== \App\Order\Status::Shipped || $this->tracking !== null')]
+// "The total equals the sum of the lines"
+#[Invariant('$this->total === \array_sum(\array_map(static fn(\App\Order\Line $line): int => $line->amount, $this->lines))')]
+```
+
+When a rule needs more than one line of logic, move it into a private method with a name from the business
+vocabulary: `#[Invariant('$this->linesAddUpToTotal()')]`. The PHPStan extension of PhpDeal then sees that the method
+is used.
+
+## State machines
+
+Specifications often describe a lifecycle: "an order is created as draft, can be placed, then paid or cancelled;
+a paid order can be shipped". Model the states as an enum and give each transition:
+
+- a precondition listing the allowed source states;
+- a postcondition naming the target state;
+- invariants for the data that each state requires.
+
+```php
+use PhpDeal\Attribute\{Ensure, Invariant, Verify};
+
+#[Invariant('$this->status !== \App\Order\Status::Paid || $this->paidAt !== null')]
+final class Order
+{
+ private \App\Order\Status $status = \App\Order\Status::Draft;
+ private ?\DateTimeImmutable $paidAt = null;
+
+ #[Verify('$this->status === \App\Order\Status::Placed')]
+ #[Ensure('$this->status === \App\Order\Status::Paid')]
+ #[Ensure('$this->paidAt === $at')]
+ public function markPaid(\DateTimeImmutable $at): void
+ {
+ $this->status = \App\Order\Status::Paid;
+ $this->paidAt = $at;
+ }
+
+ #[Verify('\in_array($this->status, [\App\Order\Status::Draft, \App\Order\Status::Placed], true)')]
+ #[Ensure('$this->status === \App\Order\Status::Cancelled')]
+ public function cancel(): void
+ {
+ $this->status = \App\Order\Status::Cancelled;
+ }
+
+ #[Ensure('$__result === \in_array($this->status, [\App\Order\Status::Draft, \App\Order\Status::Placed], true)')]
+ public function canCancel(): bool
+ {
+ return \in_array($this->status, [\App\Order\Status::Draft, \App\Order\Status::Placed], true);
+ }
+}
+```
+
+When users trigger the transition directly ("the Cancel button"), the controller asks `canCancel()` and shows a
+message. The precondition then only catches code that forgets to ask.
+
+## Aggregates and collections
+
+- Put rules that span several objects on the object that owns them (the aggregate root): "the lines of an order
+ add up to its total" is an invariant of `Order`, not of `Line`.
+- Value objects (`Money`, `Quantity`, `EmailAddress`) state their rules as constructor preconditions and invariants.
+ Most other contracts then become shorter, because a `Money` is always valid.
+- A method that adds to a collection usually has three postconditions: the count grew by one, the new item is
+ there, and the old items are unchanged.
+
+```php
+#[Ensure('\count($this->lines) === \count($__old->lines) + 1')]
+#[Ensure('$this->lines[\array_key_last($this->lines)] === $line')]
+#[Ensure('\array_slice($this->lines, 0, -1) === $__old->lines')]
+public function addLine(\App\Order\Line $line): void
+{
+ $this->lines[] = $line;
+}
+```
+
+Here `===` works on `$__old->lines` because the array is copied by the clone, and the `Line` objects are compared
+by identity.
+
+## Rule table
+
+Keep a table while you work, and give it to the user at the end. The [worked example](../examples/inventory) results
+in:
+
+| Rule | Contract or code | Where | Test |
+|------|---------------------------------------------------------------------|--------------------------------|-----------------------------------------------|
+| R1 | `Verify('\preg_match(self::SKU_PATTERN, $sku) === 1')` | `StockItem::__construct` | `testSkuMustMatchThePattern` |
+| R2 | `Invariant('$this->onHand >= 0')` | `StockItem` | random sequences |
+| R3 | `Invariant('$this->reserved >= 0 && $this->reserved <= $this->onHand')` | `StockItem` | random sequences |
+| R4 | `Ensure('$__result === $this->onHand - $this->reserved')` | `StockItem::available` | `testExampleOfTheSpecification` |
+| R5 | `Verify('$quantity > 0')`, two `Ensure` | `StockItem::receive` | boundaries, random sequences |
+| R6 | two `Verify`, two `Ensure` | `StockItem::reserve` | `testAvailableQuantityCanBeReserved`, boundaries |
+| R7 | `Verify`, two `Ensure` | `StockItem::release` | boundaries, random sequences |
+| R8 | `Verify`, two `Ensure` | `StockItem::ship` | example, boundaries |
+| R9 | code: `CountBelowReserved`; `Verify('$counted >= 0')`, two `Ensure` | `StockItem::recordCount` | `testCountBelowTheReservationsIsRejected` |
diff --git a/skills/design-by-contract/references/testing.md b/skills/design-by-contract/references/testing.md
new file mode 100644
index 0000000..2aa8ae9
--- /dev/null
+++ b/skills/design-by-contract/references/testing.md
@@ -0,0 +1,212 @@
+# Tests derived from contracts
+
+In a woven class every call checks the contracts. That changes what a test has to do:
+
+- **Postconditions and invariants need no assertions of their own.** Each valid call checks them, and a broken one
+ throws. A test only has to make many different valid calls.
+- **Preconditions tell you how to choose inputs.** The `#[Verify]` expressions describe the valid input space, so you
+ can read off the boundaries and sample valid arguments from them.
+- **The specification stays the oracle.** Contracts and code are both written from your reading of the
+ specification, so they can share the same mistake. The examples of the specification, with explicit expected
+ values, catch it.
+
+The [worked example](../examples/inventory/StockItemTest.php) shows each kind of test below.
+
+## Contents
+
+- [Bootstrap](#bootstrap)
+- [1. Specification examples](#1-specification-examples)
+- [2. Precondition boundaries](#2-precondition-boundaries)
+- [3. Business errors](#3-business-errors)
+- [4. Random valid sequences](#4-random-valid-sequences)
+- [When a test reports a violation](#when-a-test-reports-a-violation)
+- [Contracts that the tests do not reach](#contracts-that-the-tests-do-not-reach)
+
+## Bootstrap
+
+The test run must weave the classes, otherwise every contract is silently skipped:
+
+```php
+// tests/bootstrap.php
+use PhpDeal\ContractApplication;
+
+require \dirname(__DIR__) . '/vendor/autoload.php';
+
+ContractApplication::getInstance()->init([
+ 'debug' => true,
+ 'appDir' => \dirname(__DIR__),
+ 'cacheDir' => \dirname(__DIR__) . '/var/cache/contracts-test',
+ 'includePaths' => [\dirname(__DIR__) . '/src'],
+]);
+```
+
+Do not `require` the class files directly in tests: only classes loaded through the Composer autoloader are woven.
+
+## 1. Specification examples
+
+Turn each example or acceptance criterion into a test with explicit expected values, and name the test after the
+rule or the example:
+
+```php
+public function testExampleOfTheSpecification(): void
+{
+ $item = new StockItem('ABC-1234');
+ $item->receive(10);
+ $item->reserve(4);
+ $item->ship(3);
+
+ self::assertSame(7, $item->onHand());
+ self::assertSame(1, $item->reserved());
+ self::assertSame(6, $item->available());
+}
+```
+
+When the specification has no examples, write one per rule from your rule table and tell the user that they are
+your own examples.
+
+## 2. Precondition boundaries
+
+For each `#[Verify]`, find the boundary values and test both sides:
+
+| Precondition | Inside the boundary (passes) | Outside the boundary (violation) |
+|-------------------------------------|------------------------------|----------------------------------|
+| `$quantity > 0` | `1` | `0`, `-1` |
+| `$quantity <= $this->available()` | `available()` | `available() + 1` |
+| `$percent >= 1 && $percent <= 100` | `1`, `100` | `0`, `101` |
+| `\preg_match(self::SKU, $sku) === 1`| `'ABC-1234'` | `''`, `'abc-1234'`, `'ABC1234'` |
+| nullable and positive | `null`, `1` | `0` |
+| enum in an allowed list | each allowed case | each other case |
+
+The violating calls fit in one data provider. Also check that the state did not change, since preconditions run
+before the method body:
+
+```php
+/**
+ * @param callable(StockItem): void $call
+ */
+#[DataProvider('callsBreakingPreconditions')]
+public function testCallerMustMeetThePreconditions(callable $call): void
+{
+ $item = self::itemWith(onHand: 5, reserved: 2);
+
+ try {
+ $call($item);
+ self::fail('A precondition violation was expected');
+ } catch (PreconditionViolation) {
+ self::assertSame(5, $item->onHand());
+ self::assertSame(2, $item->reserved());
+ }
+}
+
+/**
+ * @return iterable
+ */
+public static function callsBreakingPreconditions(): iterable
+{
+ yield 'R6: reserve more than is available' => [static fn(StockItem $item) => $item->reserve(4)];
+ yield 'R8: ship more than is reserved' => [static fn(StockItem $item) => $item->ship(3)];
+}
+```
+
+A failing precondition test is also the first thing to check when contracts seem to do nothing: if no violation
+is thrown, the class is not woven (see [setup.md](setup.md)).
+
+## 3. Business errors
+
+Rules that the code handles itself, such as rejected input or a user-visible message, get ordinary tests. Assert the
+exception, its message and the unchanged state:
+
+```php
+public function testCountBelowTheReservationsIsRejected(): void
+{
+ $item = self::itemWith(onHand: 5, reserved: 2);
+
+ try {
+ $item->recordCount(1);
+ self::fail('The count was expected to be rejected');
+ } catch (CountBelowReserved $error) {
+ self::assertSame('Count is below the reserved quantity', $error->getMessage());
+ self::assertSame(5, $item->onHand());
+ }
+}
+```
+
+## 4. Random valid sequences
+
+This is contract-based testing: generate valid calls from the preconditions and let the postconditions and
+invariants judge the outcome. No extra library is needed. A seeded `Random\Randomizer` makes every failure
+reproducible:
+
+```php
+#[DataProvider('seeds')]
+public function testRandomValidOperationsKeepEveryContract(int $seed): void
+{
+ $random = new Randomizer(new Mt19937($seed));
+ $item = new StockItem('XYZ-0001');
+ for ($step = 0; $step < 200; ++$step) {
+ $operation = $random->getInt(0, 3);
+ if ($operation === 0) {
+ $item->receive($random->getInt(1, 50)); // Verify: $quantity > 0
+ } elseif ($operation === 1 && $item->available() > 0) {
+ $item->reserve($random->getInt(1, $item->available())); // Verify: <= available()
+ } elseif ($operation === 2 && $item->reserved() > 0) {
+ $item->ship($random->getInt(1, $item->reserved())); // Verify: <= reserved
+ } elseif ($operation === 3) {
+ $item->recordCount($random->getInt($item->reserved(), $item->onHand() + 10));
+ }
+ }
+
+ self::assertSame($item->onHand() - $item->reserved(), $item->available());
+}
+
+/**
+ * @return iterable
+ */
+public static function seeds(): iterable
+{
+ foreach ([1, 2, 3, 42, 2026] as $seed) {
+ yield "seed {$seed}" => [$seed];
+ }
+}
+```
+
+How to derive the generator from the contracts:
+
+- Each command method is one operation. Skip an operation when no valid argument exists, for example nothing to
+ ship.
+- Turn each precondition into a range for `getInt()`, or into a choice for `pickArrayKeys()` and `shuffleArray()`.
+ `$a > 0 && $a <= $this->x()` becomes `getInt(1, $this->x())`.
+- Bias the ranges towards the boundaries: include the minimum, the maximum and values next to them.
+- For strings that match a pattern, build them from parts, for example
+ `$random->getBytesFromString('ABCDEFGHIJKLMNOPQRSTUVWXYZ', 3) . '-' . $random->getBytesFromString('0123456789', 4)`.
+- End with one plain assertion so that PHPUnit does not report the test as risky.
+
+When the project already uses a property-based testing library such as [Eris](https://github.com/giorgiosironi/eris),
+generate the inputs with it instead. The contracts stay the same.
+
+## When a test reports a violation
+
+The exception names the contract, the class, the method and the arguments. Its file and line point to the method
+that declares the contract:
+
+```
+PhpDeal\Exception\PostconditionViolation: Postcondition "$this->onHand === $__old->onHand - $quantity" violated
+in Example\Inventory\StockItem->ship(3)
+```
+
+Then decide which part is wrong:
+
+- **The code** breaks a rule of the specification: fix the code.
+- **The contract** is stronger than the specification, or reads it wrongly: fix the contract, and record why.
+- **The test** calls the method outside its preconditions: fix the generator.
+
+Do not delete or weaken a contract only to get a green run.
+
+## Contracts that the tests do not reach
+
+After the tests pass, compare the rule table with the tests. Each `#[Ensure]` should run in at least one test, and so
+should each method of a class with an `#[Invariant]`. A contract that never runs proves nothing.
+
+To prove that a contract catches bugs, break the code on purpose: change one line in a method body (an off-by-one,
+a forgotten update, a removed check), run the tests, and expect a violation of the contract for that rule. Restore
+the line afterwards. When nothing fails, the contract is too weak, or no test reaches it.
diff --git a/skills/design-by-contract/scripts/lint-contracts.php b/skills/design-by-contract/scripts/lint-contracts.php
new file mode 100644
index 0000000..3ae3201
--- /dev/null
+++ b/skills/design-by-contract/scripts/lint-contracts.php
@@ -0,0 +1,693 @@
+
+ *
+ * This source file is subject to the license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+declare(strict_types=1);
+
+namespace PhpDeal\Skill;
+
+use FilesystemIterator;
+use ParseError;
+use PhpToken;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
+use SplFileInfo;
+
+/**
+ * Static checker for the contract expressions of php-deal/framework
+ *
+ * Contract expressions are strings, so neither PHP nor PHPStan see mistakes in them until a woven method is called.
+ * The checker reads `#[Verify]`, `#[Ensure]` and `#[Invariant]` attributes from PHP files without loading or
+ * weaving them, and reports syntax errors, unknown variables, `$__old`/`$__result` in the wrong kind of contract,
+ * `$this` in static methods and names that `use` imports would not resolve.
+ *
+ * Usage: php lint-contracts.php [--strict] ...
+ */
+final class ContractLinter
+{
+ private const array CONTRACTS = ['Verify', 'Ensure', 'Invariant'];
+
+ private const array MODIFIERS = [\T_PUBLIC, \T_PROTECTED, \T_PRIVATE, \T_STATIC, \T_ABSTRACT, \T_FINAL, \T_READONLY];
+
+ private const array CLASS_LIKE = [\T_CLASS, \T_INTERFACE, \T_TRAIT, \T_ENUM];
+
+ private const array SUPERGLOBALS = ['GLOBALS', '_SERVER', '_GET', '_POST', '_FILES', '_COOKIE', '_SESSION', '_REQUEST', '_ENV'];
+
+ private const array SKIPPED_DIRECTORIES = ['vendor', 'cache', 'node_modules', '.git'];
+
+ private const array MUTATIONS = [
+ \T_INC, \T_DEC, \T_PLUS_EQUAL, \T_MINUS_EQUAL, \T_MUL_EQUAL, \T_DIV_EQUAL, \T_CONCAT_EQUAL, \T_MOD_EQUAL,
+ \T_POW_EQUAL, \T_COALESCE_EQUAL, \T_AND_EQUAL, \T_OR_EQUAL, \T_XOR_EQUAL, \T_SL_EQUAL, \T_SR_EQUAL, \T_UNSET,
+ ];
+
+ /**
+ * Functions whose result changes from call to call: a contract that uses them can fail at random
+ */
+ private const array NONDETERMINISTIC = ['time', 'microtime', 'hrtime', 'rand', 'mt_rand', 'random_int', 'random_bytes', 'uniqid', 'lcg_value'];
+
+ /**
+ * Functions that compare loosely unless their "strict" argument is true, with the position of that argument
+ */
+ private const array LOOSE_BY_DEFAULT = ['in_array' => 3, 'array_search' => 3, 'array_keys' => 3];
+
+ private const string PREFIX = 'contractCount;
+ }
+
+ /**
+ * Checks every PHP file in the given files and directories
+ *
+ * @param list $paths
+ *
+ * @return list
+ */
+ public function lintPaths(array $paths): array
+ {
+ $issues = [];
+ foreach ($paths as $path) {
+ foreach (self::findFiles($path) as $file) {
+ $code = \file_get_contents($file);
+ if ($code === false) {
+ $issues[] = new Issue($file, 0, Severity::Error, 'The file can not be read');
+ continue;
+ }
+ \array_push($issues, ...$this->lintCode($code, $file));
+ }
+ }
+
+ return $issues;
+ }
+
+ /**
+ * Checks the contracts declared in a piece of PHP code
+ *
+ * @return list
+ */
+ public function lintCode(string $code, string $file = 'code.php'): array
+ {
+ if (!\str_contains($code, 'PhpDeal\\Attribute')) {
+ return [];
+ }
+ try {
+ $tokens = self::significant(PhpToken::tokenize($code, \TOKEN_PARSE));
+ } catch (ParseError $error) {
+ return [new Issue($file, $error->getLine(), Severity::Error, 'PHP syntax error: ' . $error->getMessage())];
+ }
+
+ $issues = [];
+ $pending = [];
+ $count = \count($tokens);
+ for ($index = 0; $index < $count; ++$index) {
+ $token = $tokens[$index];
+ if ($token->id === \T_ATTRIBUTE) {
+ $index = $this->readAttributeGroup($tokens, $index, $file, $pending, $issues);
+ continue;
+ }
+ if ($pending === [] || \in_array($token->id, self::MODIFIERS, true)) {
+ continue;
+ }
+ $target = self::readTarget($tokens, $index);
+ foreach ($pending as $contract) {
+ \array_push($issues, ...$this->check($contract, $target, $file));
+ }
+ $pending = [];
+ }
+
+ return $issues;
+ }
+
+ /**
+ * Reads one `#[...]` group and collects its contract attributes
+ *
+ * @param list $tokens
+ * @param list $pending
+ * @param list $issues
+ *
+ * @return int Index of the closing bracket of the group
+ */
+ private function readAttributeGroup(array $tokens, int $start, string $file, array &$pending, array &$issues): int
+ {
+ $depth = 1;
+ $count = \count($tokens);
+ $index = $start + 1;
+ for (; $index < $count && $depth > 0; ++$index) {
+ $token = $tokens[$index];
+ if ($token->text === '[' || $token->text === '(') {
+ ++$depth;
+ continue;
+ }
+ if ($token->text === ']' || $token->text === ')') {
+ --$depth;
+ continue;
+ }
+ $previous = $tokens[$index - 1]->text;
+ if ($depth !== 1 || ($previous !== '[' && $previous !== ',' && $tokens[$index - 1]->id !== \T_ATTRIBUTE)) {
+ continue;
+ }
+ $kind = self::contractKind($token);
+ if ($kind === null) {
+ continue;
+ }
+ ++$this->contractCount;
+ $contract = self::readArgument($tokens, $index + 1, $kind, $token->line);
+ if ($contract instanceof Issue) {
+ $issues[] = $contract->in($file);
+ } else {
+ $pending[] = $contract;
+ }
+ }
+
+ return $index - 1;
+ }
+
+ /**
+ * @param list $tokens
+ */
+ private static function readArgument(array $tokens, int $index, string $kind, int $line): FoundContract|Issue
+ {
+ if (($tokens[$index]->text ?? '') !== '(') {
+ return new Issue('', $line, Severity::Error, "#[{$kind}] needs an expression");
+ }
+ ++$index;
+ if (($tokens[$index]->text ?? '') === 'expression' && ($tokens[$index + 1]->text ?? '') === ':') {
+ $index += 2;
+ }
+ $argument = $tokens[$index] ?? null;
+ $next = $tokens[$index + 1]->text ?? '';
+ if ($argument !== null && $argument->text === '"') {
+ return new Issue('', $line, Severity::Error, "#[{$kind}] uses a double-quoted string, PHP would try to interpolate its variables: use single quotes");
+ }
+ if ($argument === null || $argument->id !== \T_CONSTANT_ENCAPSED_STRING || ($next !== ')' && $next !== ',')) {
+ return new Issue('', $line, Severity::Warning, "#[{$kind}] is not a single string literal and can not be checked");
+ }
+
+ $literal = $argument->text;
+ if ($literal[0] === '"') {
+ return new FoundContract($kind, \stripcslashes(\substr($literal, 1, -1)), $line, true);
+ }
+ $expression = \preg_replace('/\\\\([\\\\\'])/', '$1', \substr($literal, 1, -1)) ?? '';
+
+ return new FoundContract($kind, $expression, $line, false);
+ }
+
+ /**
+ * Describes the declaration that follows the attributes
+ *
+ * @param list $tokens
+ */
+ private static function readTarget(array $tokens, int $index): Target
+ {
+ $token = $tokens[$index];
+ $isStatic = false;
+ for ($back = $index - 1; $back >= 0 && \in_array($tokens[$back]->id, self::MODIFIERS, true); --$back) {
+ $isStatic = $isStatic || $tokens[$back]->id === \T_STATIC;
+ }
+ if (\in_array($token->id, self::CLASS_LIKE, true)) {
+ return new Target(TargetType::ClassLike, $tokens[$index + 1]->text ?? '', $token->text);
+ }
+ if ($token->id !== \T_FUNCTION) {
+ return new Target(TargetType::Other, $token->text, $token->text);
+ }
+
+ $index += ($tokens[$index + 1]->text ?? '') === '&' ? 2 : 1;
+ $name = $tokens[$index]->text ?? '';
+ $parameters = [];
+ $depth = 0;
+ $count = \count($tokens);
+ for (++$index; $index < $count; ++$index) {
+ $text = $tokens[$index]->text;
+ if ($text === '(' || $text === '[' || $tokens[$index]->id === \T_ATTRIBUTE) {
+ ++$depth;
+ } elseif ($text === ')' || $text === ']') {
+ --$depth;
+ if ($depth === 0) {
+ break;
+ }
+ } elseif ($tokens[$index]->id === \T_VARIABLE) {
+ $parameters[] = \substr($text, 1);
+ }
+ }
+ $returnType = '';
+ if (($tokens[$index + 1]->text ?? '') === ':') {
+ for ($index += 2; $index < $count && $tokens[$index]->text !== '{' && $tokens[$index]->text !== ';'; ++$index) {
+ $returnType .= $tokens[$index]->text;
+ }
+ }
+
+ return new Target(TargetType::Method, $name, 'function', $parameters, $isStatic, \strtolower($returnType));
+ }
+
+ /**
+ * @return list
+ */
+ private function check(FoundContract $contract, Target $target, string $file): array
+ {
+ $issues = [];
+ $report = static function (Severity $severity, string $message) use ($contract, $file, &$issues): void {
+ $issues[] = new Issue($file, $contract->line, $severity, $message, $contract->kind, $contract->expression);
+ };
+
+ if ($contract->doubleQuoted) {
+ $report(Severity::Warning, 'Write contracts in single quotes, as in the documentation');
+ }
+ $isClassContract = $contract->kind === 'Invariant';
+ if ($isClassContract && $target->type !== TargetType::ClassLike) {
+ $report(Severity::Error, '#[Invariant] belongs on a class or an interface, not on ' . $target->describe());
+
+ return $issues;
+ }
+ if (!$isClassContract && $target->type !== TargetType::Method) {
+ $report(Severity::Error, "#[{$contract->kind}] belongs on a method, not on " . $target->describe());
+
+ return $issues;
+ }
+ if (\trim($contract->expression) === '') {
+ $report(Severity::Error, 'The expression is empty');
+
+ return $issues;
+ }
+
+ // Same wrapper as the evaluator of php-deal: a closure that returns the expression
+ try {
+ $tokens = self::significant(PhpToken::tokenize(self::PREFIX . $contract->expression . self::SUFFIX, \TOKEN_PARSE));
+ } catch (ParseError $error) {
+ $report(Severity::Error, 'Syntax error: ' . $error->getMessage());
+
+ return $issues;
+ }
+ $tokens = \array_slice($tokens, self::prefixLength(), -self::SUFFIX_LENGTH);
+ $locals = self::localVariables($tokens);
+ $seen = [];
+ foreach ($tokens as $index => $token) {
+ if ($token->id === \T_VARIABLE) {
+ if (($tokens[$index - 1] ?? null)?->id === \T_DOUBLE_COLON) {
+ continue; // a static property, self::$name
+ }
+ $name = \substr($token->text, 1);
+ if (!isset($seen[$name]) && !isset($locals[$name])) {
+ $seen[$name] = true;
+ self::checkVariable($name, $contract, $target, $report);
+ }
+ continue;
+ }
+ if ($token->text === '=' || \in_array($token->id, self::MUTATIONS, true)) {
+ $report(Severity::Warning, "A contract must not change state, \"{$token->text}\" found");
+ }
+ if ($token->id === \T_STRING) {
+ self::checkName($tokens, $index, $report);
+ }
+ if ($token->id === \T_STRING || $token->id === \T_NAME_FULLY_QUALIFIED) {
+ self::checkCall($tokens, $index, $report);
+ }
+ }
+
+ return $issues;
+ }
+
+ /**
+ * @param callable(Severity, string): void $report
+ */
+ private static function checkVariable(string $name, FoundContract $contract, Target $target, callable $report): void
+ {
+ $where = $target->type === TargetType::Method ? "{$target->name}()" : $target->name;
+ switch ($name) {
+ case 'this':
+ if ($target->isStatic) {
+ $report(Severity::Error, "\$this is not available in the static method {$where}: use self:: or static::");
+ }
+
+ return;
+ case '__old':
+ if ($contract->kind !== 'Ensure') {
+ $report(Severity::Error, "\$__old is available only in #[Ensure], not in #[{$contract->kind}]");
+ } elseif ($target->isStatic) {
+ $report(Severity::Error, "\$__old is not available in the static method {$where}");
+ } elseif (\strtolower($target->name) === '__construct') {
+ $report(Severity::Warning, '$__old in a constructor is the object before its properties are set');
+ }
+
+ return;
+ case '__result':
+ if ($contract->kind === 'Verify') {
+ $report(Severity::Error, '$__result is not known before the call: check the result with #[Ensure]');
+ } elseif ($contract->kind === 'Invariant') {
+ $report(Severity::Warning, '$__result in an invariant is the result of whichever public method ran last');
+ } elseif (\strtolower($target->name) === '__construct') {
+ $report(Severity::Warning, '$__result is always null in a constructor: check $this instead');
+ } elseif ($target->returnType === 'void' || $target->returnType === 'never') {
+ $report(Severity::Warning, "\$__result is always null: {$where} returns {$target->returnType}");
+ }
+
+ return;
+ }
+ if (\in_array($name, $target->parameters, true)) {
+ return;
+ }
+ if (\in_array($name, self::SUPERGLOBALS, true)) {
+ $report(Severity::Warning, "A contract should not depend on \${$name}");
+
+ return;
+ }
+ if ($contract->kind === 'Invariant') {
+ $report(Severity::Error, "Unknown variable \${$name}: an invariant can use only \$this and the members of {$where}");
+
+ return;
+ }
+ $available = \array_map(static fn(string $parameter): string => '$' . $parameter, $target->parameters);
+ $available = [...$available, ...($target->isStatic ? [] : ['$this']), ...($contract->kind === 'Ensure' ? ['$__result', '$__old'] : [])];
+ $report(Severity::Error, "Unknown variable \${$name} in {$where}, available: " . ($available === [] ? 'none' : \implode(', ', $available)));
+ }
+
+ /**
+ * Reports unqualified function and class names: `use` imports do not apply inside contracts
+ *
+ * @param list $tokens
+ * @param callable(Severity, string): void $report
+ */
+ private static function checkName(array $tokens, int $index, callable $report): void
+ {
+ $name = $tokens[$index]->text;
+ $previous = $tokens[$index - 1] ?? null;
+ $next = $tokens[$index + 1]->text ?? '';
+ if ($previous !== null && \in_array($previous->id, [\T_OBJECT_OPERATOR, \T_NULLSAFE_OBJECT_OPERATOR, \T_DOUBLE_COLON, \T_FUNCTION, \T_FN, \T_CONST], true)) {
+ return;
+ }
+ if (\in_array(\strtolower($name), ['self', 'parent', 'static', 'true', 'false', 'null'], true)) {
+ return;
+ }
+ if ($next === '(' && ($previous === null || $previous->id !== \T_NEW)) {
+ $report(Severity::Warning, \function_exists($name)
+ ? "Write global functions fully qualified: \\{$name}()"
+ : "{$name}() is not a PHP function: a contract does not see \"use function\" imports, write the fully qualified name");
+
+ return;
+ }
+ $isClass = $next === '::' || ($previous !== null && \in_array($previous->id, [\T_NEW, \T_INSTANCEOF], true));
+ if (!$isClass) {
+ return;
+ }
+ if (\class_exists($name, false) || \interface_exists($name, false) || \enum_exists($name, false)) {
+ $report(Severity::Warning, "Write class names fully qualified: \\{$name}");
+
+ return;
+ }
+ $report(Severity::Error, "Class {$name} would be looked up in the global namespace: a contract does not see \"use\" imports, write the fully qualified name");
+ }
+
+ /**
+ * Reports function calls and instantiations that make a contract unreliable
+ *
+ * @param list $tokens
+ * @param callable(Severity, string): void $report
+ */
+ private static function checkCall(array $tokens, int $index, callable $report): void
+ {
+ $name = \strtolower(\ltrim($tokens[$index]->text, '\\'));
+ $previous = $tokens[$index - 1] ?? null;
+ $isNew = $previous !== null && $previous->id === \T_NEW;
+ if ($previous !== null && !$isNew && \in_array($previous->id, [\T_OBJECT_OPERATOR, \T_NULLSAFE_OBJECT_OPERATOR, \T_DOUBLE_COLON, \T_FUNCTION, \T_FN], true)) {
+ return;
+ }
+ $hasArguments = ($tokens[$index + 1]->text ?? '') === '(' && ($tokens[$index + 2]->text ?? '') !== ')';
+ if ($isNew && \str_starts_with($name, 'datetime') && !$hasArguments) {
+ $report(Severity::Warning, 'The contract reads the current time, so it can fail at random: pass the time in as an argument');
+
+ return;
+ }
+ if ($isNew || ($tokens[$index + 1]->text ?? '') !== '(') {
+ return;
+ }
+ if (\in_array($name, self::NONDETERMINISTIC, true)) {
+ $report(Severity::Warning, "{$name}() returns a different value on every call, so the contract can fail at random");
+
+ return;
+ }
+ $strictPosition = self::LOOSE_BY_DEFAULT[$name] ?? null;
+ if ($strictPosition !== null && self::countArguments($tokens, $index + 1) < $strictPosition) {
+ $report(Severity::Warning, "{$name}() compares loosely without its strict argument: pass true");
+ }
+ }
+
+ /**
+ * Counts the arguments of the call whose opening parenthesis is at $open
+ *
+ * @param list $tokens
+ */
+ private static function countArguments(array $tokens, int $open): int
+ {
+ $depth = 0;
+ $commas = 0;
+ $count = \count($tokens);
+ for ($index = $open; $index < $count; ++$index) {
+ $text = $tokens[$index]->text;
+ if ($text === '(' || $text === '[' || $text === '{') {
+ ++$depth;
+ } elseif ($text === ')' || $text === ']' || $text === '}') {
+ if (--$depth === 0) {
+ break;
+ }
+ } elseif ($depth === 1 && $text === ',') {
+ ++$commas;
+ }
+ }
+ $isEmpty = ($tokens[$open + 1]->text ?? ')') === ')';
+
+ return $isEmpty ? 0 : $commas + 1;
+ }
+
+ /**
+ * Variables declared inside the expression: closure and arrow function parameters, `use` lists and assignments
+ *
+ * @param list $tokens
+ *
+ * @return array
+ */
+ private static function localVariables(array $tokens): array
+ {
+ $locals = [];
+ $count = \count($tokens);
+ foreach ($tokens as $index => $token) {
+ if ($token->id === \T_VARIABLE && ($tokens[$index + 1]->text ?? '') === '=' && $token->text !== '$this') {
+ $locals[\substr($token->text, 1)] = true;
+ }
+ if ($token->id !== \T_FN && $token->id !== \T_FUNCTION && $token->id !== \T_USE) {
+ continue;
+ }
+ $depth = 0;
+ for ($inner = $index + 1; $inner < $count; ++$inner) {
+ $text = $tokens[$inner]->text;
+ if ($text === '(') {
+ ++$depth;
+ } elseif ($text === ')') {
+ if (--$depth === 0) {
+ break;
+ }
+ } elseif ($depth > 0 && $tokens[$inner]->id === \T_VARIABLE) {
+ $locals[\substr($text, 1)] = true;
+ } elseif ($depth === 0 && $text !== '&') {
+ break;
+ }
+ }
+ }
+
+ return $locals;
+ }
+
+ private static function prefixLength(): int
+ {
+ return \count(self::significant(PhpToken::tokenize(self::PREFIX)));
+ }
+
+ private static function contractKind(PhpToken $token): ?string
+ {
+ if (!\in_array($token->id, [\T_STRING, \T_NAME_QUALIFIED, \T_NAME_FULLY_QUALIFIED], true)) {
+ return null;
+ }
+ $position = \strrpos($token->text, '\\');
+ $name = $position === false ? $token->text : \substr($token->text, $position + 1);
+
+ return \in_array($name, self::CONTRACTS, true) ? $name : null;
+ }
+
+ /**
+ * @param array $tokens
+ *
+ * @return list
+ */
+ private static function significant(array $tokens): array
+ {
+ return \array_values(\array_filter($tokens, static fn(PhpToken $token): bool => !$token->isIgnorable()));
+ }
+
+ /**
+ * @return list
+ */
+ private static function findFiles(string $path): array
+ {
+ if (\is_file($path)) {
+ return [$path];
+ }
+ if (!\is_dir($path)) {
+ return [];
+ }
+ $files = [];
+ $iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($path, FilesystemIterator::SKIP_DOTS));
+ foreach ($iterator as $file) {
+ if (!$file instanceof SplFileInfo || $file->getExtension() !== 'php') {
+ continue;
+ }
+ $relative = \str_replace('\\', '/', \substr($file->getPathname(), \strlen($path)));
+ $parts = \explode('/', $relative);
+ if (\array_intersect($parts, self::SKIPPED_DIRECTORIES) === []) {
+ $files[] = $file->getPathname();
+ }
+ }
+ \sort($files);
+
+ return $files;
+ }
+}
+
+/**
+ * A contract attribute read from the source
+ */
+final readonly class FoundContract
+{
+ public function __construct(
+ public string $kind,
+ public string $expression,
+ public int $line,
+ public bool $doubleQuoted,
+ ) {}
+}
+
+enum TargetType
+{
+ case Method;
+ case ClassLike;
+ case Other;
+}
+
+/**
+ * The declaration a contract attribute is attached to
+ */
+final readonly class Target
+{
+ /**
+ * @param list $parameters Parameter names of a method, without "$"
+ */
+ public function __construct(
+ public TargetType $type,
+ public string $name,
+ public string $keyword,
+ public array $parameters = [],
+ public bool $isStatic = false,
+ public string $returnType = '',
+ ) {}
+
+ public function describe(): string
+ {
+ return match ($this->type) {
+ TargetType::Method => "the method {$this->name}()",
+ TargetType::ClassLike => "the {$this->keyword} {$this->name}",
+ TargetType::Other => "\"{$this->name}\"",
+ };
+ }
+}
+
+enum Severity: string
+{
+ case Error = 'error';
+ case Warning = 'warning';
+}
+
+/**
+ * A problem found in a contract
+ */
+final readonly class Issue
+{
+ public function __construct(
+ public string $file,
+ public int $line,
+ public Severity $severity,
+ public string $message,
+ public ?string $kind = null,
+ public ?string $expression = null,
+ ) {}
+
+ public function in(string $file): self
+ {
+ return new self($file, $this->line, $this->severity, $this->message, $this->kind, $this->expression);
+ }
+
+ public function __toString(): string
+ {
+ $contract = $this->kind !== null && $this->expression !== null ? " #[{$this->kind}('{$this->expression}')]" : '';
+
+ return "{$this->file}:{$this->line}: {$this->severity->value}:{$contract} {$this->message}";
+ }
+}
+
+/**
+ * Command line entry point
+ *
+ * @param list $arguments
+ */
+function main(array $arguments): int
+{
+ $strict = \in_array('--strict', $arguments, true);
+ $paths = \array_values(\array_filter($arguments, static fn(string $argument): bool => !\str_starts_with($argument, '--')));
+ if ($paths === [] || \in_array('--help', $arguments, true)) {
+ \fwrite(\STDERR, "Checks the php-deal contract expressions of PHP files.\n\n"
+ . "Usage: php lint-contracts.php [--strict] ...\n\n"
+ . " --strict fail on warnings too\n\n"
+ . "Exit code: 0 when no error is found, 1 otherwise.\n");
+
+ return $paths === [] ? 2 : 0;
+ }
+ foreach ($paths as $path) {
+ if (!\file_exists($path)) {
+ \fwrite(\STDERR, "No such file or directory: {$path}\n");
+
+ return 2;
+ }
+ }
+
+ $linter = new ContractLinter();
+ $issues = $linter->lintPaths($paths);
+ $errors = \count(\array_filter($issues, static fn(Issue $issue): bool => $issue->severity === Severity::Error));
+ $warnings = \count($issues) - $errors;
+ foreach ($issues as $issue) {
+ echo $issue, \PHP_EOL;
+ }
+ echo \sprintf('%d contract(s) checked: %d error(s), %d warning(s)', $linter->getContractCount(), $errors, $warnings), \PHP_EOL;
+
+ return $errors > 0 || ($strict && $warnings > 0) ? 1 : 0;
+}
+
+if (\PHP_SAPI === 'cli' && \get_included_files()[0] === __FILE__) {
+ $arguments = \is_array($_SERVER['argv'] ?? null) ? $_SERVER['argv'] : [];
+ exit(main(\array_values(\array_filter(\array_slice($arguments, 1), \is_string(...)))));
+}
diff --git a/tests/Skill/ContractLinterTest.php b/tests/Skill/ContractLinterTest.php
new file mode 100644
index 0000000..598cf3d
--- /dev/null
+++ b/tests/Skill/ContractLinterTest.php
@@ -0,0 +1,280 @@
+total >= 0')]
+ #[Invariant('\count(\array_filter($this->items, static fn(int $item): bool => $item < 0)) === 0')]
+ final class Cart
+ {
+ private const int LIMIT = 10;
+ public static int $fee = 1;
+ private array $items = [];
+ private int $total = 0;
+
+ #[Verify('$quantity > 0 && $quantity <= self::LIMIT')] // a trailing comment
+ #[Verify(expression: '$price >= self::$fee')]
+ #[Verify('$tags === [] || \array_is_list($tags)')]
+ #[Ensure('$this->total === $__old->total + $quantity * $price')]
+ #[Ensure('$__result instanceof \Countable || $__result === null')]
+ public function add(int $quantity, int $price, string ...$tags): ?\Countable
+ {
+ return null;
+ }
+
+ #[Verify('\App\Money::isValid($amount) && $amount !== \PHP_INT_MAX')]
+ #[Verify('\in_array($amount, [1, 2], true) && self::rand() > 0 && $amount > new \DateTimeImmutable("2020-01-01")->getTimestamp()')]
+ #[Ensure('$__result >= 0')]
+ public static function round(int $amount = 0): int
+ {
+ return $amount;
+ }
+ }
+ PHP);
+
+ self::assertSame([], $issues);
+ }
+
+ /**
+ * @param list $expected Messages, prefixed by the severity
+ */
+ #[DataProvider('brokenContracts')]
+ public function testMistakesAreReported(string $code, array $expected): void
+ {
+ $messages = \array_map(
+ static fn(Issue $issue): string => $issue->severity->value . ': ' . $issue->message,
+ self::lint($code),
+ );
+
+ self::assertSame($expected, $messages);
+ }
+
+ /**
+ * @return iterable}>
+ */
+ public static function brokenContracts(): iterable
+ {
+ yield 'syntax error' => [
+ "class A { #[Verify('\$amount >')] public function f(int \$amount): void {} }",
+ ['error: Syntax error: syntax error, unexpected token ")"'],
+ ];
+ yield 'empty expression' => [
+ "class A { #[Verify(' ')] public function f(): void {} }",
+ ['error: The expression is empty'],
+ ];
+ yield 'misspelled parameter' => [
+ "class A { #[Verify('\$amout > 0')] public function f(int \$amount): void {} }",
+ ['error: Unknown variable $amout in f(), available: $amount, $this'],
+ ];
+ yield 'result in a precondition' => [
+ "class A { #[Verify('\$__result > 0')] public function f(): int { return 1; } }",
+ ['error: $__result is not known before the call: check the result with #[Ensure]'],
+ ];
+ yield 'result of a void method' => [
+ "class A { #[Ensure('\$__result === null')] public function f(): void {} }",
+ ['warning: $__result is always null: f() returns void'],
+ ];
+ yield 'old state in a precondition' => [
+ "class A { #[Verify('\$__old->a === 1')] public function f(): void {} }",
+ ['error: $__old is available only in #[Ensure], not in #[Verify]'],
+ ];
+ yield 'old state in a static method' => [
+ "class A { #[Ensure('\$__old !== null')] public static function f(): void {} }",
+ ['error: $__old is not available in the static method f()'],
+ ];
+ yield 'this in a static method' => [
+ "class A { #[Verify('\$this->a > 0')] final public static function f(): void {} }",
+ ['error: $this is not available in the static method f(): use self:: or static::'],
+ ];
+ yield 'argument in an invariant' => [
+ "#[Invariant('\$amount > 0')] class A {}",
+ ['error: Unknown variable $amount: an invariant can use only $this and the members of A'],
+ ];
+ yield 'result in an invariant' => [
+ "#[Invariant('\$__result !== null')] interface A {}",
+ ['warning: $__result in an invariant is the result of whichever public method ran last'],
+ ];
+ yield 'invariant on a method' => [
+ "class A { #[Invariant('true')] public function f(): void {} }",
+ ['error: #[Invariant] belongs on a class or an interface, not on the method f()'],
+ ];
+ yield 'precondition on a class' => [
+ "#[Verify('true')] final readonly class A {}",
+ ['error: #[Verify] belongs on a method, not on the class A'],
+ ];
+ yield 'precondition on a property' => [
+ "class A { #[Verify('true')] public int \$a = 1; }",
+ ['error: #[Verify] belongs on a method, not on "int"'],
+ ];
+ yield 'interpolated string' => [
+ 'class A { #[Verify("$a > 0")] public function f(int $a): void {} }',
+ ['error: #[Verify] uses a double-quoted string, PHP would try to interpolate its variables: use single quotes'],
+ ];
+ yield 'double-quoted string' => [
+ 'class A { #[Verify("true")] public function f(): void {} }',
+ ['warning: Write contracts in single quotes, as in the documentation'],
+ ];
+ yield 'expression that can not be read' => [
+ 'class A { #[Verify(self::RULE)] public function f(): void {} }',
+ ['warning: #[Verify] is not a single string literal and can not be checked'],
+ ];
+ yield 'unqualified function' => [
+ "class A { #[Verify('is_int(\$a)')] public function f(int \$a): void {} }",
+ ['warning: Write global functions fully qualified: \is_int()'],
+ ];
+ yield 'imported function' => [
+ "class A { #[Verify('isPositive(\$a)')] public function f(int \$a): void {} }",
+ ['warning: isPositive() is not a PHP function: a contract does not see "use function" imports, write the fully qualified name'],
+ ];
+ yield 'imported class' => [
+ "class A { #[Verify('Money::isValid(\$a)')] public function f(int \$a): void {} }",
+ ['error: Class Money would be looked up in the global namespace: a contract does not see "use" imports, write the fully qualified name'],
+ ];
+ yield 'unqualified global class' => [
+ "class A { #[Verify('\$a instanceof DateTimeInterface')] public function f(object \$a): void {} }",
+ ['warning: Write class names fully qualified: \DateTimeInterface'],
+ ];
+ yield 'assignment' => [
+ "class A { #[Ensure('\$this->a = 1')] public function f(): void {} }",
+ ['warning: A contract must not change state, "=" found'],
+ ];
+ yield 'increment' => [
+ "class A { #[Ensure('++\$this->a > 1')] public function f(): void {} }",
+ ['warning: A contract must not change state, "++" found'],
+ ];
+ yield 'superglobal' => [
+ "class A { #[Verify('\$_SERVER !== []')] public function f(): void {} }",
+ ['warning: A contract should not depend on $_SERVER'],
+ ];
+ yield 'result in a constructor' => [
+ "class A { #[Ensure('\$__result !== null')] public function __construct() {} }",
+ ['warning: $__result is always null in a constructor: check $this instead'],
+ ];
+ yield 'old state in a constructor' => [
+ "class A { #[Ensure('\$__old->a === 0')] public function __construct(public int \$a = 1) {} }",
+ ['warning: $__old in a constructor is the object before its properties are set'],
+ ];
+ yield 'current time' => [
+ "class A { #[Verify('\$at < new \\DateTimeImmutable()')] public function f(\\DateTimeImmutable \$at): void {} }",
+ ['warning: The contract reads the current time, so it can fail at random: pass the time in as an argument'],
+ ];
+ yield 'random value' => [
+ "class A { #[Verify('\\random_int(0, 1) === 0')] public function f(): void {} }",
+ ['warning: random_int() returns a different value on every call, so the contract can fail at random'],
+ ];
+ yield 'loose in_array' => [
+ "class A { #[Verify('\\in_array(\$c, [1, 2])')] public function f(int \$c): void {} }",
+ ['warning: in_array() compares loosely without its strict argument: pass true'],
+ ];
+ yield 'contract without expression' => [
+ 'class A { #[Verify] public function f(): void {} }',
+ ['error: #[Verify] needs an expression'],
+ ];
+ }
+
+ public function testFilesWithoutPhpDealAreSkipped(): void
+ {
+ $linter = new ContractLinter();
+
+ self::assertSame([], $linter->lintCode("')] function f() {}"));
+ self::assertSame(0, $linter->getContractCount());
+ }
+
+ public function testBrokenPhpIsReported(): void
+ {
+ $issues = new ContractLinter()->lintCode("severity);
+ self::assertStringStartsWith('broken.php:3: error: PHP syntax error:', (string) $issues[0]);
+ }
+
+ public function testIssueNamesFileLineAndContract(): void
+ {
+ $issues = self::lint("class A {\n #[Verify('\$b > 0')]\n public function f(int \$a): void {}\n}");
+
+ self::assertSame(
+ ["file.php:10: error: #[Verify('\$b > 0')] Unknown variable \$b in f(), available: \$a, \$this"],
+ \array_map(static fn(Issue $issue): string => (string) $issue, $issues),
+ );
+ }
+
+ /**
+ * The worked example of the skill and the demo are what agents copy: they must stay free of warnings
+ */
+ public function testExampleAndDemoAreClean(): void
+ {
+ $linter = new ContractLinter();
+ $issues = $linter->lintPaths([self::ROOT . '/skills/design-by-contract/examples', self::ROOT . '/demo']);
+
+ self::assertSame([], \array_map(static fn(Issue $issue): string => (string) $issue, $issues));
+ self::assertGreaterThan(20, $linter->getContractCount());
+ }
+
+ public function testCommandLineReportsAndFails(): void
+ {
+ [$exitCode, $output] = self::runScript(self::ROOT . '/tests/Fixtures/Verify/Account.php');
+
+ self::assertSame(1, $exitCode);
+ self::assertStringContainsString("Account.php:47: error: #[Verify('\$amount >')] Syntax error", $output);
+ self::assertStringContainsString('2 error(s), 0 warning(s)', $output);
+ }
+
+ public function testCommandLinePassesCleanCode(): void
+ {
+ [$exitCode, $output] = self::runScript('--strict', self::ROOT . '/demo');
+
+ self::assertSame(0, $exitCode);
+ self::assertSame("7 contract(s) checked: 0 error(s), 0 warning(s)\n", $output);
+ }
+
+ public function testCommandLineNeedsAPath(): void
+ {
+ self::assertSame(2, self::runScript()[0]);
+ self::assertSame(2, self::runScript(self::ROOT . '/does-not-exist')[0]);
+ }
+
+ /**
+ * @return list
+ */
+ private static function lint(string $code): array
+ {
+ $header = "lintCode($header . $code, 'file.php');
+ }
+
+ /**
+ * @return array{int, string}
+ */
+ private static function runScript(string ...$arguments): array
+ {
+ $process = \proc_open([\PHP_BINARY, self::SCRIPT, ...\array_values($arguments)], [1 => ['pipe', 'w'], 2 => ['pipe', 'w']], $pipes);
+ self::assertIsResource($process);
+ $output = (string) \stream_get_contents($pipes[1]);
+ \fclose($pipes[1]);
+ \fclose($pipes[2]);
+
+ return [\proc_close($process), $output];
+ }
+}
diff --git a/tests/bootstrap.php b/tests/bootstrap.php
index 7f036da..5f51fff 100644
--- a/tests/bootstrap.php
+++ b/tests/bootstrap.php
@@ -6,9 +6,10 @@
require \dirname(__DIR__) . '/vendor/autoload.php';
+// The worked example of the Agent Skill is woven too, so that the test suite keeps it correct
ContractApplication::getInstance()->init([
'debug' => true,
'appDir' => \dirname(__DIR__),
'cacheDir' => __DIR__ . '/cache',
- 'includePaths' => [__DIR__ . '/Fixtures'],
+ 'includePaths' => [__DIR__ . '/Fixtures', \dirname(__DIR__) . '/skills/design-by-contract/examples'],
]);