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