Save this content to: AGENTS.md

# Lemmon Validator

PHP validation library inspired by Valibot and Zod. Type-safe, fluent API for primitives, arrays, and objects.

## Project Context

Core validation logic lives in `src/Lemmon/Validator/`. Tests in `tests/` follow `XValidatorTest.php` naming. Key project files:

- `llms.txt` - Technical spec for external/consumer use; API signatures, null handling, transformation types
- `ROADMAP.md` - Single source of truth for planned and considered work (v1.0 path, post-1.0, not planned)
- `CHANGELOG` - Completed work

## Architecture

- **Namespace:** `Lemmon\Validator` (runtime), `Lemmon\Tests` (tests)
- **Core:** `Validator` static factory; `FieldValidator` base; `ValidationException` for errors; `ValidationError` value object (dotted path/exact segments/code/message/params) is the structured-error source of truth, exposed via `ValidationException::getErrors(string|array|null $path = null)`; `ValidationCode` stable-code catalog
- **Validators:** `isString`, `isInt`, `isFloat`, `isBool`, `isArray`, `isAssociative`, `isObject`, `isInstance`
- **Shared:** `NumericConstraintsTrait` (min, max, multipleOf, etc.); `PipelineStep` value object (internal pipeline entry); `PipelineContext` (internal per-run type context threaded through the pipeline); variant enums `IpVersion`, `Base64Variant`, `UuidVariant` for format methods
- **String formats:** email, URL, UUID, IP, hostname, domain, time, base64, hex, regex, datetime, date
- **Schema validation:** AssociativeValidator/ObjectValidator with nested error aggregation; shared `SchemaValidatorOptionsTrait` (`coerceAll`, `passthrough`, `strict`, schema clone helper); `passthrough()` keeps undeclared keys/properties (unvalidated); `strict()` rejects them (`UNRECOGNIZED_KEY`); default output is schema keys only
- **Logical combinators:** `Validator::allOf`, `anyOf`, `not` (built on `MixedValidator`, the type-agnostic base); instance `satisfiesAny`, `satisfiesAll`, `satisfiesNone`; `const()` for single allowed value; `enum()` for `BackedEnum` and `UnitEnum`
- **Behavior:** Optional by default (null allowed unless `required()`); form-safe coercion (empty string → null, not 0/false); pipeline order guaranteed; fail-fast per field; `satisfies()` accepts validators or callables with `(value, key, input)`; extend via `satisfies()`, not custom validators

## Build, Test, and Development Commands

- `composer test` - Run Pest test suite
- `composer lint` / `composer format` - Mago linting and formatting (dev dependency)
- `composer analyze` - PHPStan at max level
- `composer platform-check` - Verify PHP 8.3 and extension requirements
- `composer check` - Run all checks (platform, format, lint, Prettier, test, analyze); use before PR
- `npm run format` - Prettier for YAML, JSON, Markdown
- `npm run check` - Alias for `composer check`
- Pre-commit hook (Husky): Prettier check, Mago format --staged, Mago lint --staged

`config.platform.php` is set to `8.3.0` so dependency resolution targets PHP 8.3; `composer update`/`install` will not add packages that require PHP above 8.3.

Dev tooling: symfony/var-dumper, symfony/error-handler, ergebnis/composer-normalize.

## Coding Style & Formatting

PSR-12 for PHP. Mago for lint/format (`composer lint`, `composer format`). Prettier (`.prettierrc`) for YAML, JSON, Markdown. Add PHPDoc where behavior is non-obvious. Stick to ASCII punctuation in PHP code (e.g. `--`, not an em dash); Markdown and other docs may use proper typographic characters.