diff --git a/AGENTS.md b/AGENTS.md index 6c0ea8e..0facbe5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,8 @@ Guidance for AI coding agents working on this repository. Human contributors: se ## Project -`php-deal/framework` is a Design by Contract library for PHP. Contracts are native attributes +`php-deal/framework` is an AI Design by Contract library for PHP: AI agents turn business specifications into +contracted code with the bundled Agent Skill, and the library enforces the contracts. Contracts are native attributes (`#[Verify]`, `#[Ensure]`, `#[Invariant]`, `#[Inherit]`) whose string arguments are PHP expressions. Aspects of [Go! AOP 4](https://github.com/goaop/framework) weave the annotated classes and evaluate the expressions on every call. @@ -88,6 +89,8 @@ lowest-dependencies job and `composer audit`. Global functions in expressions are written `\is_numeric(...)`, and class names fully qualified, because `use` imports do not apply inside expressions. - Keep comments short and useful. Public API classes need a class docblock that explains their purpose. +- The README leads with the AI workflow (specification โ†’ rules โ†’ contracts โ†’ code โ†’ tests). Present new features + from that angle first, then in the contract language reference. ## Testing tips diff --git a/CHANGELOG.md b/CHANGELOG.md index f74a376..41ab559 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,8 @@ All notable changes to this project are documented in this file. The format is b 2.0.0 - unreleased ------------------ -A rewrite for modern PHP. See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the migration steps. +A rewrite for modern PHP and for AI-driven development: an Agent Skill lets AI coding agents turn business +specifications into contracted code and tests. See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the migration steps. ### Added diff --git a/README.md b/README.md index 36314c5..956986b 100644 --- a/README.md +++ b/README.md @@ -2,37 +2,50 @@ # PhpDeal -**Design by Contract for modern PHP** +**AI Design by Contract for PHP** -Declare preconditions, postconditions and invariants with native attributes.
-PhpDeal checks them on every call, powered by [Go! AOP](https://github.com/goaop/framework). +Your AI agent turns business specifications into code that checks its own rules.
+PhpDeal enforces those rules on every call, as native PHP attributes powered by [Go! AOP](https://github.com/goaop/framework). [![CI](https://github.com/php-deal/framework/actions/workflows/ci.yml/badge.svg)](https://github.com/php-deal/framework/actions/workflows/ci.yml) [![Latest Version](https://img.shields.io/packagist/v/php-deal/framework.svg?label=release)](https://packagist.org/packages/php-deal/framework) [![Total Downloads](https://img.shields.io/packagist/dt/php-deal/framework.svg)](https://packagist.org/packages/php-deal/framework) [![PHP Version](https://img.shields.io/badge/php-%E2%89%A5%208.4-777BB4.svg?logo=php&logoColor=white)](https://www.php.net/releases/8.4/) +[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-design--by--contract-d97757.svg)](skills/design-by-contract/SKILL.md) [![Go! AOP](https://img.shields.io/badge/Go!%20AOP-4.x-1f6feb.svg)](https://github.com/goaop/framework) [![PHPStan](https://img.shields.io/badge/PHPStan-level%2010-2a5ea7.svg)](https://phpstan.org/user-guide/rule-levels) [![License](https://img.shields.io/packagist/l/php-deal/framework.svg)](LICENSE) +You write the rules in plain language: + +> **R1.** A deposit is a positive amount.
+> **R2.** A deposit adds the amount to the balance.
+> **R3.** The balance is never negative. + +Your agent turns them into contracts, the code and the tests: + ```php use PhpDeal\Attribute\{Ensure, Invariant, Verify}; -#[Invariant('$this->balance >= 0')] +#[Invariant('$this->balance >= 0')] // R3 class Account { private float $balance = 0.0; - #[Verify('$amount > 0')] - #[Ensure('$this->balance === $__old->balance + $amount')] + #[Verify('$amount > 0')] // R1 + #[Ensure('$this->balance === $__old->balance + $amount')] // R2 public function deposit(float $amount): void { $this->balance += $amount; } } +``` + +When the code or its caller breaks a rule, PhpDeal stops the call and names the rule: +```php new Account()->deposit(-10); // PhpDeal\Exception\PreconditionViolation: // Precondition "$amount > 0" violated in Account->deposit(-10.0) @@ -40,45 +53,193 @@ new Account()->deposit(-10); ## Contents -- [Why Design by Contract?](#why-design-by-contract) +- [Why AI Design by Contract?](#why-ai-design-by-contract) +- [How it works](#how-it-works) +- [Quick start](#quick-start) +- [What the agent delivers](#what-the-agent-delivers) +- [The contract checker](#the-contract-checker) - [Features](#features) -- [Installation](#installation) -- [Setup](#setup) -- [Contracts](#contracts) - - [Preconditions: `#[Verify]`](#preconditions-verify) - - [Postconditions: `#[Ensure]`](#postconditions-ensure) - - [Invariants: `#[Invariant]`](#invariants-invariant) - - [Inheritance: `#[Inherit]`](#inheritance-inherit) -- [Writing expressions](#writing-expressions) -- [Handling violations](#handling-violations) -- [PHPStan integration](#phpstan-integration) -- [AI coding agents](#ai-coding-agents) -- [Production](#production) +- **The contract language** + - [Setup](#setup) + - [Contracts](#contracts): [`#[Verify]`](#preconditions-verify), [`#[Ensure]`](#postconditions-ensure), + [`#[Invariant]`](#invariants-invariant), [`#[Inherit]`](#inheritance-inherit) + - [Writing expressions](#writing-expressions) + - [Handling violations](#handling-violations) + - [PHPStan integration](#phpstan-integration) + - [Production](#production) - [Upgrading from 1.x](#upgrading-from-1x) - [Contributing](#contributing) -## Why Design by Contract? +## Why AI Design by Contract? + +An AI agent writes code faster than anyone can review it. The hard question is no longer *how* to implement a +feature but *whether the code does what the business asked*. The usual answers fall short: + +- **Review** does not scale to every line an agent writes. +- **Tests written by the same agent** share its reading of the requirements. When the agent misreads a rule, the + code and the tests agree with each other, and both are wrong. +- **Requirements in a ticket** are forgotten by the next change, whether a person or an agent makes it. + +[Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract) closes that gap. Every business rule becomes +an executable contract that lives next to the code it constrains: + +- **Preconditions** (`#[Verify]`) are what the caller must guarantee before a call. +- **Postconditions** (`#[Ensure]`) are what the method promises after it returns. +- **Invariants** (`#[Invariant]`) are what is always true of an object between calls. + +PhpDeal checks them on every call. That gives each party something it lacked: + +| For... | Contracts give you | +|------------------|------------------------------------------------------------------------------------------------------------| +| **You** | A one-line, reviewable statement of each rule, traced to the specification, instead of hundreds of lines of code | +| **The agent** | An immediate, exact signal: which rule broke, in which method, with which arguments. It fixes the code instead of guessing | +| **The tests** | An oracle on every call. Any test that drives the object through valid calls also checks every postcondition and invariant | +| **The next change** | Rules that stay enforced. A later edit, by a person or an agent, can not quietly break one | + +A broken contract is a bug, reported at the exact place where it happens, before a corrupt state travels through +the application. + +## How it works + +PhpDeal ships an [Agent Skill](https://agentskills.io), [`design-by-contract`](skills/design-by-contract/SKILL.md), +that teaches your coding agent the whole workflow: + +```mermaid +flowchart LR + spec[Business
specification] --> rules[Numbered
rules] + rules --> contracts[Contracts:
Verify, Ensure,
Invariant] + contracts --> code[Code] + code --> checker[Contract
checker] + checker --> tests[Tests derived
from contracts] + tests --> report[Rule table,
assumptions,
open questions] + tests -- violation --> code +``` + +1. **Extract the rules.** The agent reads the specification, numbers every rule (`R1`, `R2`, ...), and writes down + ambiguities as open questions instead of guessing. +2. **Classify them.** Each rule becomes a precondition, a postcondition or an invariant. A business error that users + see, such as *"this room is already booked"*, stays as explicit code, because contracts are usually off in + production. +3. **Write the code** with the contracts on the classes and interfaces, each one tagged with its rule ID. +4. **Check the contracts.** A bundled checker finds mistakes inside the contract strings, which neither PHP nor + PHPStan see. +5. **Derive the tests.** These cover the examples of the specification, the boundaries of every precondition, + the business errors, and random sequences of valid calls sampled from the preconditions. The contracts judge + every step. +6. **Report.** The agent ends with a table that maps each rule to its contract, its code and its test, plus the + assumptions it made and the questions for the business. + +## Quick start + +**1. Install the library** (PHP 8.4+): -[Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract) treats the public API of a class as a formal -agreement between the class and its callers: +```bash +composer require php-deal/framework +``` -- **Preconditions** are the requirements upon the caller: what must be true before a method is called. -- **Postconditions** are the promises of the method: what is true after it returns. -- **Invariants** are the properties of an object that always hold between calls. +**2. Start the contract kernel** in your test bootstrap (and in development), before your classes are loaded. See +[Setup](#setup) for all options: + +```php +use PhpDeal\ContractApplication; -If the caller meets the requirements, the class delivers the promised service. A broken contract is a bug, and -PhpDeal reports it at the exact place where it happens instead of letting a corrupt state travel through the -application. The contracts live next to the code they describe, so they double as precise, executable -documentation. +require __DIR__ . '/../vendor/autoload.php'; + +ContractApplication::getInstance()->init([ + 'debug' => true, + 'appDir' => __DIR__ . '/..', + 'cacheDir' => __DIR__ . '/../var/cache/contracts', + 'includePaths' => [__DIR__ . '/../src'], +]); +``` + +**3. Give your agent the skill.** In [Claude Code](https://claude.com/claude-code), install the plugin from this +repository: + +``` +/plugin marketplace add php-deal/framework +/plugin install php-deal@php-deal +``` + +Other agents that read the [Agent Skills](https://agentskills.io) format can load the folder +[`skills/design-by-contract`](skills/design-by-contract) directly. Composer installs it too, at +`vendor/php-deal/framework/skills/design-by-contract`, in the version that matches your library. + +**4. Hand over the specification:** + +> Implement docs/booking-spec.md with Design by Contract, and write the tests. + +In Claude Code you can also call the skill explicitly with `/php-deal:design-by-contract`. + +## What the agent delivers + +The [worked example](skills/design-by-contract/examples/inventory) shows a complete run. Our CI weaves and runs it on +every change: + +- [`SPEC.md`](skills/design-by-contract/examples/inventory/SPEC.md): nine stock-keeping rules, written for people; +- [`StockItem.php`](skills/design-by-contract/examples/inventory/StockItem.php): the class, with each contract + tagged by its rule; +- [`StockItemTest.php`](skills/design-by-contract/examples/inventory/StockItemTest.php): the tests derived from the + rules and the contracts; +- a rule table: + +| Rule | Contract or code | Where | Test | +|------|----------------------------------------------------------------------------|----------------------------|-------------------------------------------| +| R3 | `#[Invariant('$this->reserved >= 0 && $this->reserved <= $this->onHand')]` | `StockItem` | random sequences | +| R6 | `#[Verify('$quantity <= $this->available()')]` | `StockItem::reserve()` | precondition boundaries | +| R8 | `#[Ensure('$this->onHand === $__old->onHand - $quantity')]` | `StockItem::ship()` | specification example, random sequences | +| R9 | code: throws `CountBelowReserved`, a business error | `StockItem::recordCount()` | `testCountBelowTheReservationsIsRejected` | + +The random sequences are contract-based testing with no extra library. The agent samples valid arguments from the +preconditions, and every postcondition and invariant checks every step: + +```php +$random = new Randomizer(new Mt19937($seed)); +for ($step = 0; $step < 200; ++$step) { + if ($item->available() > 0) { + $item->reserve($random->getInt(1, $item->available())); // sampled from #[Verify] + } + $item->receive($random->getInt(1, 50)); +} +``` + +**Does it catch bugs?** We gave an agent with no other context a new specification (meeting-room booking) and only +the skill. It wrote 46 contracts and 46 tests. Then it planted five bugs, one at a time: an off-by-one error, a wrong +overlap check, a cancel that deleted every booking, reused ids and a broken free-slot check. Contracts caught all +five. + +## The contract checker + +Contracts are PHP expressions in strings, so neither PHP nor PHPStan see their mistakes until the method runs. The +skill bundles a checker that agents run after every edit. You can run it too, in CI or by hand: + +```bash +php vendor/php-deal/framework/skills/design-by-contract/scripts/lint-contracts.php --strict src +``` + +It reports syntax errors, misspelled variables, `$__old` or `$__result` in the wrong contract, `$this` in static +methods, class names that `use` imports do not resolve, double-quoted strings, assignments, reads of the clock or +random values, and `\in_array()` without strict comparison. ## Features +**For AI-driven development** + +- ๐Ÿค– **Agent Skill** with the full workflow from specification to tested code, installable as a Claude Code plugin + and portable to any agent that reads the Agent Skills format. +- ๐Ÿงญ **Traceable rules**: every contract carries the ID of the business rule it enforces. +- ๐Ÿงช **Tests derived from contracts**: specification examples, precondition boundaries, business errors and seeded + random sequences. +- ๐Ÿ”Ž **Contract checker** that catches mistakes in expressions before they run. +- ๐ŸŽฏ **Exact feedback**: a violation names the contract, the class, the method and the arguments, and points to the + declaring line, so the agent fixes the right place. + +**The contract engine** + - โœ… **Native PHP attributes**: `#[Verify]`, `#[Ensure]`, `#[Invariant]` and `#[Inherit]`, repeatable where it makes sense. - ๐Ÿงฌ **Contract inheritance** from parent classes and interfaces, with clear and predictable rules. - ๐Ÿ”’ **Full access to the object**: expressions run in the scope of the class and can read private state. - ๐Ÿ•ฐ๏ธ **`$__old` and `$__result`** to compare the state before and after a call, and to check return values. -- ๐ŸŽฏ **Precise exceptions**: `PreconditionViolation`, `PostconditionViolation` and `InvariantViolation`, pointing to - the method that declares the contract. - โšก **Fast**: each expression is compiled once, contracts are read once per class, and the object is cloned only when a contract uses `$__old`. - ๐Ÿ” **Recursion-safe**: an invariant may call public methods of its own class. @@ -86,16 +247,18 @@ documentation. - ๐Ÿ” **PHPStan extension** included: properties and methods used only by contracts are not reported as unused. - ๐Ÿงช **Thoroughly tested**, analysed with PHPStan at level 10 with strict rules. -## Installation +--- -```bash -composer require php-deal/framework -``` +# The contract language -PhpDeal 2 requires **PHP 8.4** or newer and is built on **Go! AOP 4**. +The rest of this document is the reference for the contracts themselves: what your agent writes and what you +review. Everything in it works without an AI as well, and contracts can be written by hand. ## Setup +PhpDeal 2 requires **PHP 8.4** or newer and is built on **Go! AOP 4**. Contracts are checked only in classes +that Go! AOP weaves, so the kernel must start before they are loaded. + Initialize the contract kernel once, as early as possible in your front controller or test bootstrap, before the classes with contracts are loaded: @@ -367,35 +530,6 @@ 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 a1278f9..4a98301 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "php-deal/framework", - "description": "Design by Contract framework for PHP: preconditions, postconditions and invariants declared with native attributes", + "description": "AI Design by Contract for PHP: AI agents turn business specifications into code with preconditions, postconditions and invariants, checked on every call", "type": "library", "keywords": [ "dbc", @@ -11,7 +11,13 @@ "invariant", "attributes", "aop", - "goaop" + "goaop", + "ai", + "ai-agents", + "agent-skills", + "claude-code", + "specification", + "contract-based-testing" ], "license": "MIT", "authors": [