feat: narrow toBeInstanceOf() subjects across ->and() chains

[maks-oleksyuk]

Problem

expect($x)->toBeInstanceOf(Y::class) only narrows PHPStan's known type for $x when that's the entire statement, on its own. Two related, common patterns weren't covered:

1. Within a chain: expect($items[0])->toBeInstanceOf(Post::class)->and($items[0]->title)->toBe('hello'); — $items[0]->title needs $items[0] narrowed, but that read happens before the statement finishes, and PHPStan's native statement-level narrowing only ever applies to code after a condition/statement — it can't reach into an earlier part of the same expression.
2. Past a chained statement: expect($response)->toBeInstanceOf(JsonResponse::class)->and($response->getStatusCode())->toBe(200); followed on the next line by decodeJsonBody($response); — narrowing didn't survive, because toBeInstanceOf() wasn't the chain's outermost call.

Both are extremely common Pest idioms (asserting a value's type, then immediately reading properties/methods off it, often chained with other assertions via ->and()), and without this, every real-world use forces either splitting the assertion into an awkward standalone statement or falling back to a manual assert($x instanceof Y);.

Fix

Two complementary extensions, because they hook into genuinely different PHPStan mechanisms:

• ExpectationChainSubjectNarrowingExtension (ExpressionTypeResolverExtension) — narrows a subject reused later in the same chain. Re-parses the file (via the existing PestFileDiscoverer), walks each statement's own ->var chain spine (never descending into closures — that would leak a fact from one it() block into a sibling one), and matches subjects structurally against earlier toBeInstanceOf() steps in the same statement, by source position.
• ExpectationInstanceTypeSpecifyingExtension (MethodTypeSpecifyingExtension) — walks the entire chain via ->var to collect every toBeInstanceOf() step, not just the outermost call, so narrowing correctly survives for code after the whole statement — using PHPStan's native scope-tracking, which already handles reassignment, branches, and loops correctly, unlike the position-based approach above.

These can't be merged into one extension: the "within-chain" one is a text/position-based workaround with no notion of control flow (deliberately scoped to within one statement, where that's safe), while the "past-statement" one needs PHPStan's real scope machinery, which PHPStan only ever invokes for a statement's outermost expression — it structurally cannot see into a sub-expression mid-statement.

Shared and()/expect() subject-resolution logic lives in one ExpectationChainSubjectResolver service both extensions inject, rather than being duplicated.

Testing

• New assertType coverage: expectation-chain-subject-narrowing.php (8 cases — array/plain-variable subjects, multiple distinct subjects narrowed in one chain, position-ordering guards, no leaking into an unrelated it() block) and expectation-instance-narrowing.php (+3 cases — chained toBeInstanceOf() narrowing past the statement, multiple follow-up steps, and()-introduced subject narrowing past the statement).
• pest --parallel: 482 passed. phpstan analyse: no errors. pint / rector --dry-run: clean.
• Verified against real-world usage in a consuming app: expect($x)->toBeInstanceOf(Y)->and(...)->and(...); chains that previously required assert() workarounds or splitting across statements now type-check cleanly as a single chain, both mid-chain and for code after.

[MrPunyapal]

Thanks @maks-oleksyuk — you spotted a real gap, and your arrow-function beforeEach fix just landed via #6! 🎉

Regarding this one (#7): narrowing \ oBeInstanceOf()\ subjects across ->and()\ chains shipped with broader scope in #12 — see \ ests/Type/data/expectation-narrowing.php\ for coverage including negation and rebind edge cases. Your branch now predates and conflicts semantically with that implementation, so closing in its favor rather than maintaining two narrowing paths. Hope to see more from you — your instincts are good!

[maks-oleksyuk]

Thanks for the quick look, and for merging #6!

On #7 — I actually rebased this onto 5.x after #12 landed and trimmed it down specifically because of the overlap you're describing. What's left (ExpectationChainSubjectNarrowingExtension) isn't semantically conflicting with #12 anymore — it only handles narrowing a subject within the same statement, for a later argument in the same fluent chain, e.g.:

expect($components)->toHaveCount(4)
    ->and($components[0])->toBeInstanceOf(TextInput::class)
    ->and($components[0]->getName())->toBe('email'); // <- needs $components[0] narrowed here, same statement

ExpectationNarrowingResolver/ExpectationTypeSpecifyingExtension from #12 narrow the subject for use in later statements (via TypeSpecifier), but not for a later argument inside the same chain/statement — that's a different mechanism (PHPStan only exposes narrowed types across statement boundaries via SpecifiedTypes, not mid-expression). I hit this for real in a Filament test asserting on $components[N]->getName() right after narrowing $components[N].

I dropped everything from the original PR that duplicated #12 (the old ExpectationInstanceTypeSpecifyingExtension + its test file are gone), and also found/fixed a real PHPStan 2.2.5/2.2.6 bug along the way that was breaking this under the prefer-lowest CI matrix (fixed by bumping the phpstan/phpstan constraint to ^2.2.7). Current CI is green: head aedc11a.

Happy to add a test case demonstrating the exact scenario #12 doesn't cover if that helps the review — let me know if you'd like me to reopen, or if you'd rather this land as a follow-up on top of #12 instead.

[MrPunyapal]

Thanks for pointing this out @maks-oleksyuk — you were right, and apologies for the premature close. The rebased scope is exactly right: intra-chain narrowing for a subject used later in the same statement is a genuinely different mechanism than #12's cross-statement \SpecifiedTypes, and your Filament-style case proves it.

I verified the gap on \5.x\ independently and added one more example covering member access on a narrowed dim-fetch subject (\ estMemberAccessOnNarrowedDimFetchSubjectResolves) — all green across the matrix. Merging. Great collaboration on this one! 🙏

[MrPunyapal]

Closing the loop @maks-oleksyuk — with scope narrowing withdrawn in v5.2.0 (see #12), the intra-chain extension no longer has anything to compose with. Your analysis of same-statement vs cross-statement mechanics was spot-on and shaped how we framed the boundary. Preserved in history if narrowing ever lands properly. Thanks again!