Keep generic types on concrete collection classes

[delacry]

Fixes #49.

A value typed as a concrete class (ImmutableHashSet, ImmutableArrayList, or your own class using the logic traits) got worse PHPStan types than the same value typed as its interface. Some trait docblocks didn't match the interfaces, and our type tests only went through the interfaces, so nobody noticed.

/** @param ImmutableHashSet<int> $set */
$set->chunked(2);
// before: ImmutableList
// now:    ImmutableList<ListInterface<int>>

$set->add(4);
// before: ImmutableSet<int|NE>  (unresolved template)
// now:    ImmutableSet<int>

$set->groupBy(fn (int $x): bool => $x > 1, fn (int $x): bool => $x % 2 === 0);
// before: ImmutableMap<bool, ImmutableSet<int>>  (wrong, runtime gives lists of bools)
// now:    ImmutableMap<bool, ImmutableList<bool>>

What changed:

• chunked(), windowed(), zip() and zipWithNext() in CollectionLogic declare their generic return types. The Collection interface stays as it is: ImmutableList<ListInterface<E>> fits its ListInterface<ListInterface<E>>, so PHPDocs that spell out the result keep working.
• groupBy() in the traits uses the same conditional return type as the interfaces.
• add(), addFirst() and addAll() on immutable lists and sets widen the type as documented, instead of leaking NE.

One thing can break, described in UPGRADE-0.2.md: a class built on the base traits that rebuilds itself and validates its elements can now receive a foreign element from add(). Declare @method self add(YourType $element) to keep it strict. The extending guide and test fixtures show this.

The new tests/Type/Collection/ConcreteClassTypeTest.php fails on 0.2.x and passes here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[delacry]

I realized that my previous fix went too far, as I narrowed few return types to ImmutableList in the Collection..

So I force-pushed smaller fix, Collection keeps ListInterface as the return type of chunked(), windowed(), zip() and zipWithNext().. only CollectionLogic declares the deneric types now, so a concrete class gets ImmutableList<ListInterface<E>> for chunks

@nikophil if you already tried the branch - chunks on concrete classes are now typed ImmutableList<ListInterface<int>> instead of ImmutableList<ImmutableList<int>>, and ->first()->first() is still int

#57 is rebased on top, with no changes