fix: correct stale docs and add regression tests for default/required flow

- Fix README claiming transform() runs on null (wrong since v0.12.0)
- Fix PipelineType docblock claiming transform() executes on null
- Fix validate() signature to accept mixed $input matching tryValidate()
- Fix llms.txt validate() signature to match source
- Fix tryValidate() PHPDoc "original value" to clarify post-coerce on failure
- Fix satisfies() comment "required already checked" (required is checked last)
- Fix CHANGELOG "4-step" wording to "5-step"
- Add 6 regression tests for default()->required() and transform(skipNull: false) interactions

Author: lemmon

CHANGELOG.md

@@ -13,7 +13,7 @@ All notable changes to this project will be documented in this file.
 - **CRITICAL BUG**: Fixed `default()` and `required()` interaction -- `required()` was rejecting null values before `default()` had a chance to provide a fallback
   - **Issue**: Chaining `->default($value)->required()` always threw "Value is required" for null inputs because `required` checked for null before `default` was applied
   - **Root Cause**: `tryValidate()` had a scattered, multi-branch architecture with `default` and `required` checks duplicated across 5+ locations (early returns, pre-pipeline, mid-loop, post-loop), making the interaction order unpredictable
-  - **Fix**: Simplified `tryValidate()` to a clean linear 4-step flow: coerce, type check, pipeline, then default-before-required at the end
+  - **Fix**: Simplified `tryValidate()` to a clean linear 5-step flow: coerce, type check, pipeline, default, required
   - **Impact**: `default()` and `required()` now work cooperatively -- `default()` is the last-resort fallback for null, `required()` only fails if the value is still null after default
   - **Real-World Benefit**: Enables patterns like `->pipe(fn($x) => null)->default($fallback)->required()` where a pipeline step intentionally nullifies a value and `default()` catches it before `required()` enforces presence
 

README.md

@@ -26,7 +26,7 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 **Key Design Principles:**
 
 - **Type-Safe Architecture**: Modern PHP 8.1+ enums provide IDE autocomplete, refactoring safety, and eliminate magic strings throughout the codebase
-- **Smart Null Handling**: Validations skip `null` unless `required()`. `transform()` runs on `null`, while `pipe()` and `nullifyEmpty()` skip `null` for type safety.
+- **Smart Null Handling**: Validations skip `null` unless `required()`. `transform()` and `pipe()` skip `null` by default for type safety. Use `transform($fn, skipNull: false)` to process null values.
 - **Form Safety First**: Empty strings coerce to `null` (not dangerous `0`/`false`) to prevent real-world issues like accidental zero bank balances
 - **Fluent API with Execution Order Guarantee**: Validation rules read like natural language and execute in the exact order written -- `Validator::isString()->pipe('trim')->nullifyEmpty()->required()`
 - **Last-Resort Default**: `default()` is a flag applied after the pipeline -- fills in null only as a last resort, before `required()` enforces presence
@@ -39,7 +39,7 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 ## Features
 
 - **Type-safe architecture** - PHP 8.1+ enums with IDE autocomplete, refactoring safety, and zero magic strings
-- **Smart null handling** - validations skip `null` unless `required()`, `transform()` runs on `null`, `pipe()`/`nullifyEmpty()` skip `null`
+- **Smart null handling** - validations skip `null` unless `required()`, `transform()`/`pipe()`/`nullifyEmpty()` skip `null` by default
 - **Type-safe validation** for strings, integers, floats, arrays, and objects
 - **Fluent, chainable API** with guaranteed execution order -- methods execute exactly as written in the chain
 - **Schema-level error aggregation** with fail-fast behavior per field for clear, early feedback

llms.txt

@@ -21,7 +21,7 @@
 - **Entry Point:** `Validator` static factory (e.g., `Validator::isString()`).
 - **Fluency:** Validators are mutable during configuration but used sequentially.
 - **Execution:**
-  - `validate(mixed $value, string $key = '', array $input = [])` throws `ValidationException`.
+  - `validate(mixed $value, string $key = '', mixed $input = null)` throws `ValidationException`.
   - `tryValidate(mixed $value, string $key = '', mixed $input = null)` returns tuple `[bool $valid, mixed $data, ?array $errors]`.
 - **Fail-Fast:** Each validator chain stops at the first failing rule; schema validators aggregate errors across fields.
 - **Error Structure:** `ValidationException` contains nested array of error messages. Use `getFlattenedErrors()` for API format `[{path: string, message: string}]`.

src/Lemmon/Validator/FieldValidator.php

@@ -122,7 +122,7 @@ public function satisfies(callable|FieldValidator $validation, ?string $message
                 }
                 return $value;
             },
-            'skipNull' => true, // Validations always skip null (required already checked)
+            'skipNull' => true, // Validations skip null (optional fields should not run custom rules)
         ];
         return $this;
     }
@@ -351,11 +351,11 @@ public function pipe(callable ...$transformers): self
      *
      * @param mixed $value The value to validate.
      * @param string $key The key of the field being validated.
-     * @param array<string, mixed> $input The entire input array.
+     * @param mixed $input The entire input payload (array or object).
      * @return mixed The validated and potentially coerced value.
      * @throws ValidationException If validation fails.
      */
-    public function validate(mixed $value, string $key = '', array $input = []): mixed
+    public function validate(mixed $value, string $key = '', mixed $input = null): mixed
     {
         [$valid, $data, $errors] = $this->tryValidate($value, $key, $input);
         if (!$valid) {
@@ -372,7 +372,7 @@ public function validate(mixed $value, string $key = '', array $input = []): mix
      * @param mixed|null $input The entire input payload (array or object).
      * @return array{bool, mixed, array<string>|null} A tuple containing:
      *                                                 - bool: true if validation is successful, false otherwise.
-     *                                                 - mixed: The validated and potentially coerced value, or the original value on failure.
+     *                                                 - mixed: The validated and potentially coerced value on success, or the (possibly coerced) input value on failure.
      *                                                 - array|null: An array of error messages on failure, or null on success.
      */
     public function tryValidate(mixed $value, string $key = '', mixed $input = null): array

src/Lemmon/Validator/PipelineType.php

@@ -19,9 +19,8 @@ enum PipelineType: string
 
     /**
      * Transformation operations that modify or convert values.
-     * Null handling depends on the transformation type:
-     * - `pipe()` transformations skip null (type-preserving, expect specific type)
-     * - `transform()` transformations execute on null (can handle null and change types)
+     * Both `pipe()` and `transform()` skip null by default.
+     * Use `transform($fn, skipNull: false)` to process null values.
      */
     case TRANSFORMATION = 'transformation';
 }

tests/FieldValidatorTest.php

@@ -573,3 +573,55 @@
     // Empty string nullified, then fails required validation
     $validator->validate('');
 })->throws(ValidationException::class, 'Field cannot be empty');
+
+it('should apply default before required check for null input', function () {
+    $validator = Validator::isString()->default('fallback')->required();
+
+    expect($validator->validate(null))->toBe('fallback');
+    expect($validator->validate('actual'))->toBe('actual');
+});
+
+it('should apply default after pipeline nullifies value', function () {
+    $validator = Validator::isString()
+        ->pipe('trim')
+        ->nullifyEmpty()
+        ->default('fallback')
+        ->required();
+
+    expect($validator->validate('   '))->toBe('fallback');
+    expect($validator->validate('hello'))->toBe('hello');
+});
+
+it('should fail required when no default catches null', function () {
+    $validator = Validator::isString()
+        ->pipe('trim')
+        ->nullifyEmpty()
+        ->required('Cannot be blank');
+
+    $validator->validate('   ');
+})->throws(ValidationException::class, 'Cannot be blank');
+
+it('should apply default after transform with skipNull false produces null', function () {
+    $validator = Validator::isString()
+        ->transform(fn($v) => null, skipNull: false)
+        ->default('rescued');
+
+    expect($validator->validate(null))->toBe('rescued');
+    expect($validator->validate('anything'))->toBe('rescued');
+});
+
+it('should fail required after transform with skipNull false produces null and no default', function () {
+    $validator = Validator::isString()
+        ->transform(fn($v) => null, skipNull: false)
+        ->required('Still needed');
+
+    $validator->validate('anything');
+})->throws(ValidationException::class, 'Still needed');
+
+it('should apply default from transform with skipNull false then pass required', function () {
+    $validator = Validator::isString()
+        ->transform(fn($v) => $v ?? 'from-transform', skipNull: false)
+        ->required();
+
+    expect($validator->validate(null))->toBe('from-transform');
+});