From 1bcd003bc8cf84c80a30156bb051276ca17f4508 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 17:25:47 +0000 Subject: [PATCH 1/2] Add a design-by-contract Agent Skill and Claude Code plugin The skill teaches AI coding agents to turn a business specification into self-checking PHP code: extract and number the rules, map each one to a precondition, postcondition, invariant or business error, write the classes, check the expressions, and derive PHPUnit tests from the contracts (specification examples, precondition boundaries, business errors and seeded random sequences of valid calls). This is the AI-assisted take on contract-based test generation from #36. - skills/design-by-contract: SKILL.md, references for setup, expressions, rule patterns and testing, and a worked inventory example that the test suite weaves and runs, so it can not go stale - scripts/lint-contracts.php: a dependency-free checker for contract expressions (syntax, unknown variables, $__old/$__result misuse, $this in static methods, names that `use` imports would not resolve, quoting) - .claude-plugin: the repository is a plugin marketplace, so Claude Code users install it with /plugin marketplace add php-deal/framework Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FxhC1FD8xw9sMh2etSB3ir --- .claude-plugin/marketplace.json | 16 + .claude-plugin/plugin.json | 14 + .gitattributes | 1 + .php-cs-fixer.dist.php | 2 +- AGENTS.md | 10 +- CHANGELOG.md | 4 + README.md | 30 + composer.json | 6 +- phpstan.neon.dist | 1 + phpunit.xml.dist | 4 + skills/design-by-contract/SKILL.md | 172 +++++ .../examples/inventory/CountBelowReserved.php | 12 + .../examples/inventory/SPEC.md | 18 + .../examples/inventory/StockItem.php | 110 ++++ .../examples/inventory/StockItemTest.php | 168 +++++ .../references/expressions.md | 123 ++++ skills/design-by-contract/references/setup.md | 76 +++ .../references/spec-to-contracts.md | 172 +++++ .../design-by-contract/references/testing.md | 208 ++++++ .../scripts/lint-contracts.php | 615 ++++++++++++++++++ tests/Skill/ContractLinterTest.php | 259 ++++++++ tests/bootstrap.php | 3 +- 22 files changed, 2019 insertions(+), 5 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json create mode 100644 skills/design-by-contract/SKILL.md create mode 100644 skills/design-by-contract/examples/inventory/CountBelowReserved.php create mode 100644 skills/design-by-contract/examples/inventory/SPEC.md create mode 100644 skills/design-by-contract/examples/inventory/StockItem.php create mode 100644 skills/design-by-contract/examples/inventory/StockItemTest.php create mode 100644 skills/design-by-contract/references/expressions.md create mode 100644 skills/design-by-contract/references/setup.md create mode 100644 skills/design-by-contract/references/spec-to-contracts.md create mode 100644 skills/design-by-contract/references/testing.md create mode 100644 skills/design-by-contract/scripts/lint-contracts.php create mode 100644 tests/Skill/ContractLinterTest.php 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..150941d --- /dev/null +++ b/skills/design-by-contract/SKILL.md @@ -0,0 +1,172 @@ +--- +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`. +- 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. + +### 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. +- `$__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. +- Invariants are checked after the constructor and after every **public** method, not after private ones. + +[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 and assignments. 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 | Class::method | Test`, with one row per rule; +- 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..a09973c --- /dev/null +++ b/skills/design-by-contract/references/expressions.md @@ -0,0 +1,123 @@ +# 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'`. + +**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..157f819 --- /dev/null +++ b/skills/design-by-contract/references/setup.md @@ -0,0 +1,76 @@ +# 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. 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..cfbef76 --- /dev/null +++ b/skills/design-by-contract/references/testing.md @@ -0,0 +1,208 @@ +# 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. 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..2f8e075 --- /dev/null +++ b/skills/design-by-contract/scripts/lint-contracts.php @@ -0,0 +1,615 @@ + + * + * 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, + ]; + + 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); + } + } + + 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}"); + } + + 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 ($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"); + } + + /** + * 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..f380512 --- /dev/null +++ b/tests/Skill/ContractLinterTest.php @@ -0,0 +1,259 @@ +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')] + #[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 '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'], ]); From 1015334bb429a7cef81e3141e828c27770da7bd2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 17:31:36 +0000 Subject: [PATCH 2/2] Apply feedback from a test run of the skill A fresh agent implemented a new specification (meeting-room bookings) with the skill alone; its feedback is folded in here. - Checker: warn about $__result and $__old in constructors, contracts that read the clock or random values, and in_array()/array_search()/ array_keys() without their strict argument - Skill: constructors, private and final classes are supported; check the items of a variadic, not the list; record implied API data as assumptions; weaving check when there is no composer.json; "Where" column in the rule table - References: break-the-code tip to prove that contracts catch bugs, and a note on opcache JIT crashes on the first weaving run Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FxhC1FD8xw9sMh2etSB3ir --- skills/design-by-contract/SKILL.md | 24 ++++-- .../references/expressions.md | 6 ++ skills/design-by-contract/references/setup.md | 4 + .../design-by-contract/references/testing.md | 4 + .../scripts/lint-contracts.php | 78 +++++++++++++++++++ tests/Skill/ContractLinterTest.php | 21 +++++ 6 files changed, 130 insertions(+), 7 deletions(-) diff --git a/skills/design-by-contract/SKILL.md b/skills/design-by-contract/SKILL.md index 150941d..33ad764 100644 --- a/skills/design-by-contract/SKILL.md +++ b/skills/design-by-contract/SKILL.md @@ -54,7 +54,8 @@ Copy this checklist and work through it: ### 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`. + 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 @@ -67,7 +68,9 @@ Copy this checklist and work through it: 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. +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 @@ -109,14 +112,19 @@ 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. +- 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. -- Invariants are checked after the constructor and after every **public** method, not after private ones. +- `#[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. @@ -135,8 +143,9 @@ 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 and assignments. Fix every error and warning. It can not check types or -the existence of properties: the tests in the next step do that. +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 @@ -159,7 +168,8 @@ make a test pass unless the specification supports the weaker version. End with: -- a table `Rule | Contract or code | Class::method | Test`, with one row per rule; +- 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. diff --git a/skills/design-by-contract/references/expressions.md b/skills/design-by-contract/references/expressions.md index a09973c..7ea357d 100644 --- a/skills/design-by-contract/references/expressions.md +++ b/skills/design-by-contract/references/expressions.md @@ -101,6 +101,12 @@ 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'`. diff --git a/skills/design-by-contract/references/setup.md b/skills/design-by-contract/references/setup.md index 157f819..f70691d 100644 --- a/skills/design-by-contract/references/setup.md +++ b/skills/design-by-contract/references/setup.md @@ -74,3 +74,7 @@ thrown, the class is not woven. Check the following: 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/testing.md b/skills/design-by-contract/references/testing.md index cfbef76..2aa8ae9 100644 --- a/skills/design-by-contract/references/testing.md +++ b/skills/design-by-contract/references/testing.md @@ -206,3 +206,7 @@ Do not delete or weaken a contract only to get a green run. 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 index 2f8e075..3ae3201 100644 --- a/skills/design-by-contract/scripts/lint-contracts.php +++ b/skills/design-by-contract/scripts/lint-contracts.php @@ -47,6 +47,16 @@ final class ContractLinter \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 = '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; @@ -331,6 +344,8 @@ private static function checkVariable(string $name, FoundContract $contract, Tar $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; @@ -339,6 +354,8 @@ private static function checkVariable(string $name, FoundContract $contract, Tar $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}"); } @@ -399,6 +416,67 @@ private static function checkName(array $tokens, int $index, callable $report): $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 * diff --git a/tests/Skill/ContractLinterTest.php b/tests/Skill/ContractLinterTest.php index f380512..598cf3d 100644 --- a/tests/Skill/ContractLinterTest.php +++ b/tests/Skill/ContractLinterTest.php @@ -43,6 +43,7 @@ public function add(int $quantity, int $price, string ...$tags): ?\Countable } #[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 { @@ -165,6 +166,26 @@ public static function brokenContracts(): iterable "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'],