optimize code, tests and AGENTS.md with fable 5

Author: dominikzogg

AGENTS.md

@@ -1,24 +1,99 @@
 # Project Context — chubbyphp-typescript
 
-PHP port of JavaScript's `Array` API with TypeScript-style generics. Keep behavior close to JavaScript `Array`; the test suite is the spec.
-
-## Where To Work
-- `src/Arr.php` is the main implementation.
-- `tests/Unit/ArrTest.php` is the main spec and is organized by JS API section order.
-- `tests/Integration/DocumentationExamplesTest.php` verifies the PHP examples in `README.md` and `doc/Arr.md`.
-- Update `doc/Arr.md` and `README.md` when public behavior changes.
-
-## Important Conventions
-- Keep `declare(strict_types=1);`, typed properties, `final` classes, and the detailed PHPDoc generics/callable signatures in `Arr`.
-- Method ordering rule for `Arr.php`: (1) magic methods `__*`; (2) interface methods, in the order listed in `implements`; (3) the rest sorted by MDN JS `Array` order (statics first, then instance methods); (4) non-JS methods at the end. Mirror that order in `tests/Unit/ArrTest.php`, `doc/Arr.md`, and `tests/Integration/DocumentationExamplesTest.php`.
-- `thisArg` support is intentional: bind only non-static `Closure` callables; other callables ignore it.
-
-## Important Behavior
-- Preserve sparse-array semantics. `length` may be greater than the number of populated indexes.
-- Holes read back as `null` through `at()`, `values()`, `toArray()`, and `jsonSerialize()`, but `offsetExists()`/`isset()` must still distinguish between missing indexes and explicit `null` values.
-- Favor JavaScript `Array` semantics over idiomatic PHP shortcuts.
-
-## Verification
-- Use Composer scripts as the default workflow: `composer test:unit`, `composer test:integration`, `composer test:static-analysis`, `composer test:cs`, or `composer test`.
-- PHPUnit runs in random order, so avoid hidden test coupling.
-- Keep every PHP example in `README.md` and `doc/Arr.md` executable and in sync with `tests/Integration/DocumentationExamplesTest.php`; add one integration test per documented example block.
+PHP (^8.3) port of JavaScript's `Array` API with TypeScript-style generics.
+
+**Golden rule:** behave exactly like JavaScript `Array`, not like idiomatic PHP.
+When unsure what JS does, do not guess — run it: `node` is available.
+
+```bash
+node -e 'console.log([1, , 3].findIndex(x => x === undefined))'  # prints 1
+```
+
+## File Map
+
+| Path | Purpose |
+|---|---|
+| `src/Arr.php` | The whole implementation (one class) |
+| `src/RangeError.php`, `src/NumberFormatError.php` | Project exception classes |
+| `tests/Unit/ArrTest.php` | Main spec, organized in JS API order (see ordering rule) |
+| `tests/Unit/Test262*Test.php` | Ports of the official test262 suite, one file per `Array` method |
+| `tests/Integration/DocumentationExamplesTest.php` | Mirrors every PHP example block in `README.md` / `doc/Arr.md` |
+| `tests/Stub/*.php` | Shared test fixtures |
+| `doc/Arr.md` | API documentation with runnable examples |
+
+## Commands (run from repo root)
+
+| Command | What it checks |
+|---|---|
+| `composer test` | Everything below, in order — **must exit 0 before you are done** |
+| `composer test:lint` | `php -l` on all files |
+| `composer test:static-analysis` | PHPStan level 9 (analyzes `src/` only, not tests) |
+| `composer test:cs` | php-cs-fixer dry-run (covers `src/` AND `tests/`) |
+| `composer test:unit` | PHPUnit Unit suite with coverage |
+| `composer test:integration` | PHPUnit Integration suite |
+| `composer test:infection` | Mutation testing, fails below 90% MSI (needs `test:unit` coverage first) |
+| `composer fix:cs` | Auto-fix code style |
+
+Quality gates to preserve:
+- 100% line and method coverage of `src/Arr.php` (check the coverage summary `composer test:unit` prints).
+- Mutation score ≥ 90%. Kill mutants with **exact** assertions: assert exact strings/values,
+  test boundary values (`0`, `-1`, `length`, `length - 1`, `21`, `-6`), and test negative numbers,
+  empty arrays, and sparse arrays for every new branch.
+
+## Hard Conventions
+
+- Keep `declare(strict_types=1);`, `final` classes, typed properties, and the detailed
+  PHPDoc generics/callable signatures (`@template T`, `callable(null|T, int, self<T>): bool`, ...).
+- Method ordering in `Arr.php`: (1) magic methods `__*`; (2) interface methods in the order
+  listed in `implements`; (3) JS API methods in MDN order (statics first, then instance methods);
+  (4) non-JS helpers (`toArray()`, private helpers) at the end.
+  Mirror the same order in `tests/Unit/ArrTest.php`, `doc/Arr.md`, and
+  `tests/Integration/DocumentationExamplesTest.php`.
+- `thisArg` support: bind only non-static `Closure` callables via `Closure::bindTo`;
+  every other callable type silently ignores `$thisArg`.
+
+## JavaScript Semantics Cheat Sheet (read before touching `src/Arr.php`)
+
+- PHP `null` plays the role of JS `undefined` everywhere.
+- **Sparse arrays:** `length` can exceed the number of stored indexes ("holes").
+  Reading a hole returns `null`, but `offsetExists()`/`isset()` returns `false` for holes
+  and `true` for explicit `null` values. Never collapse that distinction.
+- **Methods that SKIP holes** (callback not invoked / index not matched):
+  `every`, `some`, `filter`, `forEach`, `map` (keeps holes in result), `reduce`, `reduceRight`,
+  `flat`, `indexOf`, `lastIndexOf`.
+- **Methods that DO NOT skip holes** (hole is treated as `null`):
+  `find`, `findIndex`, `findLast`, `findLastIndex`, `includes`, `join`, `keys`, `entries`, `values`, `fill`, `at`.
+- **Always-dense results:** `toReversed`, `toSorted`, `toSpliced`, `with` never return sparse
+  arrays — holes materialize as explicit `null`s.
+- Iteration methods capture `$len = $this->internalLength` **before** the loop
+  (JS uses the initial length even if the callback mutates the array).
+- `$this->internalArray` keys are in **insertion order, not index order**
+  (`$a[2] = ...; $a[0] = ...;`). When order matters, never `foreach` over it directly;
+  loop `for ($i = 0; $i < $len; ++$i)` and check `\array_key_exists($i, ...)`.
+- Floats stringify via `numberToString()` which implements ECMAScript `Number::toString`
+  (shortest round-trip): `0.1` → `"0.1"`, `1.0` → `"1"`, `-0.0` → `"0"`, `INF` → `"Infinity"`,
+  `NAN` → `"NaN"`, `1e21` → `"1e+21"`, `1e-7` → `"1e-7"`. Do not use `sprintf('%g')` or `(string)` casts.
+- `sort()` moves explicit `null`s (JS `undefined`) to the end without calling the comparator;
+  holes end up after those (length stays, trailing indexes unset).
+- Out-of-range / non-numeric `ArrayAccess` offsets become string "properties" stored separately
+  (they never affect `length`), mirroring JS property access; offsets that cannot be stringified throw.
+
+## Testing Rules
+
+- The test suite is the spec. PHPUnit runs tests in **random order** — no hidden coupling between tests.
+- `tests/Unit/Test262*Test.php`: each test method names the original test262 file in its PHPDoc.
+  Non-portable test262 cases are recorded as two comment lines:
+  `// SKIPPED: test/built-ins/Array/...js` followed by `// Reason: ...`.
+  Adapted cases explain the adaptation in a comment. Keep that style when adding or changing tests.
+- If you change public behavior: update `tests/Unit/ArrTest.php`, the matching `Test262*Test.php`,
+  `doc/Arr.md`, and `README.md` together.
+- Every PHP example block in `README.md` and `doc/Arr.md` must stay executable and have exactly
+  one matching test in `tests/Integration/DocumentationExamplesTest.php` (`testDoc<Method>Example`).
+- PHPStan does not analyze `tests/`, but php-cs-fixer does — run `composer fix:cs` after writing tests.
+
+## Done Checklist
+
+1. JS behavior verified against `node` (not assumed).
+2. `composer test` exits 0 (includes 90% MSI and code style).
+3. Coverage still 100% for `src/Arr.php`.
+4. Docs + integration examples updated if public behavior changed.

doc/Arr.md

@@ -124,7 +124,7 @@ $a->concat(new Arr(3, 4), 5); // [1, 2, 3, 4, 5]
 
 ---
 
-### `copyWithin(int $target, int $start, ?int $end = null): self`
+### `copyWithin(int $target, int $start = 0, ?int $end = null): self`
 
 Shallow copies a portion of the array to another location within the same array, modifying it in place and returning it.
 
@@ -188,7 +188,7 @@ $arr->filter(static fn ($v) => $v > 25);  // [30, 40]
 
 ### `find(callable $callback, ?object $thisArg = null): mixed`
 
-Returns the first element that passes the callback, or `null`.
+Returns the first element that passes the callback, or `null`. Unlike most iteration methods, `find()` does not skip holes in sparse arrays: the callback receives `null` for them.
 
 ```php
 $arr = new Arr(5, 12, 8, 130, 44);
@@ -199,7 +199,7 @@ $arr->find(static fn ($v) => $v > 10);    // 12
 
 ### `findIndex(callable $callback, ?object $thisArg = null): int`
 
-Returns the index of the first element that passes the callback, or `-1`.
+Returns the index of the first element that passes the callback, or `-1`. Like `find()`, it does not skip holes in sparse arrays.
 
 ```php
 $arr = new Arr(5, 12, 8, 130, 44);
@@ -210,7 +210,7 @@ $arr->findIndex(static fn ($v) => $v > 10);  // 1
 
 ### `findLast(callable $callback, ?object $thisArg = null): mixed`
 
-Returns the last element that passes the callback, or `null`.
+Returns the last element that passes the callback, or `null`. Like `find()`, it does not skip holes in sparse arrays.
 
 ```php
 $arr = new Arr(5, 12, 8, 130, 44);
@@ -221,7 +221,7 @@ $arr->findLast(static fn ($v) => $v > 10);   // 44
 
 ### `findLastIndex(callable $callback, ?object $thisArg = null): int`
 
-Returns the index of the last element that passes the callback, or `-1`.
+Returns the index of the last element that passes the callback, or `-1`. Like `find()`, it does not skip holes in sparse arrays.
 
 ```php
 $arr = new Arr(5, 12, 8, 130, 44);
@@ -294,13 +294,15 @@ $arr->indexOf('z');      // -1
 
 ### `join(?string $separator = null): string`
 
-Joins all elements into a string separated by `$separator` (default `','`).
+Joins all elements into a string separated by `$separator` (default `','`). Floats are rendered like JavaScript's `String(number)` (shortest round-trip representation, `NaN`, `Infinity`, `1e+21`, ...).
 
 ```php
 $arr = new Arr('Wind', 'Rain', 'Fire');
 $arr->join();          // 'Wind,Rain,Fire'
 $arr->join(' - ');     // 'Wind - Rain - Fire'
 $arr->join(', ');      // 'Wind, Rain, Fire'
+
+(new Arr(0.1, 1.0, INF))->join();  // '0.1,1,Infinity'
 ```
 
 ---
@@ -478,7 +480,7 @@ $arr->toLocaleString('en-US', ['style' => 'currency', 'currency' => 'EUR']);  //
 
 ### `toReversed(): self`
 
-Returns a new array with the elements reversed (does not modify the original).
+Returns a new array with the elements reversed (does not modify the original). The result is never sparse: holes become explicit `null` values.
 
 ```php
 $arr = new Arr(1, 2, 3);
@@ -490,7 +492,7 @@ $arr->toReversed();   // [3, 2, 1]
 
 ### `toSorted(?callable $callback = null): self`
 
-Returns a new array with the elements sorted (does not modify the original).
+Returns a new array with the elements sorted (does not modify the original). The result is never sparse: holes become explicit `null` values sorted to the end.
 
 ```php
 $arr = new Arr(3, 1, 2);
@@ -502,7 +504,7 @@ $sorted = $arr->toSorted();
 
 ### `toSpliced(int $start, ?int $deleteCount = null, mixed ...$items): self`
 
-Returns a new array with elements removed/replaced (does not modify the original).
+Returns a new array with elements removed/replaced (does not modify the original). The result is never sparse: holes become explicit `null` values.
 
 ```php
 $arr = new Arr(1, 2, 3, 4);