feat: instanceof narrowing on array access expressions

After `if ($row['page'] instanceof Page)`, the type of
$row['page'] inside the if-body is now narrowed to Page.

This eliminates false-positive unresolved_member_access diagnostics
on patterns like $row['page']->getId() that are guarded by an
instanceof check.

Author: AJenbo

docs/CHANGELOG.md

@@ -128,7 +128,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Infinite loop on array key reassignment patterns.** Files containing `$arr['key'] = f($arr['key'])` or similar read-then-write patterns on the same array key no longer hang the analyzer.
 - **Stack overflow on large codebases and large files.** The `analyze` command and files with hundreds of class definitions no longer crash with stack overflows.
 - **`analyze` and `fix` commands run at consistent speed regardless of invocation style.** Running from within a project directory is no longer ~8x slower than using `--project-root`.
-- **Type narrowing.** Comprehensive fixes to type narrowing: non-exiting `if` branches no longer leak narrowed types into post-merge scope; `is_float()`, `is_null()`, and other `is_*()` guards correctly narrow multi-member unions; negated `instanceof` on nullable unions preserves `null`; `is_object()` narrows to all class types in a union (not just the first); `instanceof` on `mixed` or `object` narrows to the checked type; `=== null` and `== null` narrow to `null` in the truthy branch; `assert($x instanceof Foo)` followed by any `if` block no longer loses the narrowed type; falsy guard clauses strip both `false` and `null`; template-constrained types are expanded before guard filtering. `is_numeric()`, `is_bool()`, and `is_scalar()` guard clauses now narrow union types correctly. `exit` and `die` are recognized as unconditional exits for guard clause narrowing. Property access expressions (`$a->foo`) are now narrowed through chained if/elseif/else conditions using `is_string()`, `instanceof`, and other type guards. Array shape keys are now narrowed through null-check guard clauses and conditional reassignment (e.g. `$a["test"]` resolves to `int` instead of `?int` after `if ($a["test"] === null) { return; }`). After `instanceof` check plus reassignment inside the if-body, the post-merge type collapses to the common parent class instead of producing a redundant `Child|Parent` union. Property access after OR'd `instanceof` checks (`$a instanceof B || $a instanceof C`) now resolves to the union of all branches' property types. After `while` and `do-while` loops exit, the loop condition's inverse is applied to narrow variable types (e.g. `do { $a = $a->next; } while ($a)` narrows `$a` to `null` after the loop; `while ($a instanceof Foo)` narrows `$a` to the excluded type after exit). Branch merging no longer loses nullable information when two branches produce the same class with different nullability (e.g. merging `A` with `A|null` correctly yields `A|null` instead of silently dropping the null).
+- **Type narrowing.** Comprehensive fixes to type narrowing: non-exiting `if` branches no longer leak narrowed types into post-merge scope; `is_float()`, `is_null()`, and other `is_*()` guards correctly narrow multi-member unions; negated `instanceof` on nullable unions preserves `null`; `is_object()` narrows to all class types in a union (not just the first); `instanceof` on `mixed` or `object` narrows to the checked type; `=== null` and `== null` narrow to `null` in the truthy branch; `assert($x instanceof Foo)` followed by any `if` block no longer loses the narrowed type; falsy guard clauses strip both `false` and `null`; template-constrained types are expanded before guard filtering. `is_numeric()`, `is_bool()`, and `is_scalar()` guard clauses now narrow union types correctly. `exit` and `die` are recognized as unconditional exits for guard clause narrowing. Property access expressions (`$a->foo`) are now narrowed through chained if/elseif/else conditions using `is_string()`, `instanceof`, and other type guards. Array shape keys are now narrowed through null-check guard clauses and conditional reassignment (e.g. `$a["test"]` resolves to `int` instead of `?int` after `if ($a["test"] === null) { return; }`). Array element access expressions are now narrowed through `instanceof` checks (e.g. `if ($row['page'] instanceof Page)` narrows `$row['page']` to `Page` inside the if-body). After `instanceof` check plus reassignment inside the if-body, the post-merge type collapses to the common parent class instead of producing a redundant `Child|Parent` union. Property access after OR'd `instanceof` checks (`$a instanceof B || $a instanceof C`) now resolves to the union of all branches' property types. After `while` and `do-while` loops exit, the loop condition's inverse is applied to narrow variable types (e.g. `do { $a = $a->next; } while ($a)` narrows `$a` to `null` after the loop; `while ($a instanceof Foo)` narrows `$a` to the excluded type after exit). Branch merging no longer loses nullable information when two branches produce the same class with different nullability (e.g. merging `A` with `A|null` correctly yields `A|null` instead of silently dropping the null).
 - **Mixin resolution.** Static method calls on instances of a class with `@mixin` now resolve through the mixin. `@method` and `@property` tags declared on a mixin class are propagated to the consuming class. `$this` return types on mixin methods resolve to the consumer class. `IteratorIterator` is now patched with `@template` parameters and `@mixin TIterator` (matching PHPStan's stubs).
 - **Generics.** Constructor generic inference now works through inherited constructors: child classes without their own constructor infer template parameters from the parent's constructor arguments, with correct remapping through multi-level `@extends` chains (including swapped or renamed template parameters). Function-level `@template` parameters bound to generic wrapper types (e.g. `@param Container<TItem> $c`) are inferred from arguments that extend the wrapper class. Method calls are now case-insensitive, matching PHP semantics (e.g. `$obj->getId()` finds `getID()`). Closure literals passed to `@template` parameters are recognised as `Closure`. Class-level template parameters are preserved through chained method calls. Template parameters fall back to their declared bound (or `mixed` when unbounded) when subclasses omit `@extends` or `@use` annotations. Unbound template parameters at call sites resolve to their declared bounds or `mixed` instead of leaking raw names. Method-level templates resolve correctly through generic wrappers and nested call chains. Return type generic arguments are preserved for template substitution, fixing false "expects TRelatedModel, got Translation" diagnostics. Iterating over a subclass that extends a generic collection with scalar type arguments (e.g. `IntCollection extends Collection<int, int>`) now yields the concrete scalar type instead of the raw template parameter name. Calling a method on a union of generic types (e.g. `$var->get()` where `$var` is `C<A>|C<B>`) now resolves to the union of each branch's return type (`A|B`) instead of only the first branch. Empty array literals passed to generic constructors or functions infer `never` for element type parameters (e.g. `new ArrayCollection([])` resolves to `ArrayCollection<never, never>`).
 - **Type narrowing.** Comprehensive fixes to type narrowing: non-exiting `if` branches no longer leak narrowed types into post-merge scope; `is_float()`, `is_null()`, and other `is_*()` guards correctly narrow multi-member unions; negated `instanceof` on nullable unions preserves `null`; `is_object()` narrows to all class types in a union (not just the first); `instanceof` on `mixed` or `object` narrows to the checked type; `=== null` and `== null` narrow to `null` in the truthy branch; `assert($x instanceof Foo)` followed by any `if` block no longer loses the narrowed type; falsy guard clauses strip both `false` and `null`; template-constrained types are expanded before guard filtering. `is_numeric()`, `is_bool()`, and `is_scalar()` guard clauses now narrow union types correctly. `exit` and `die` are recognized as unconditional exits for guard clause narrowing. Property access expressions (`$a->foo`) are now narrowed through chained if/elseif/else conditions using `is_string()`, `instanceof`, and other type guards. Array shape keys are now narrowed through null-check guard clauses and conditional reassignment (e.g. `$a["test"]` resolves to `int` instead of `?int` after `if ($a["test"] === null) { return; }`). After `instanceof` check plus reassignment inside the if-body, the post-merge type collapses to the common parent class instead of producing a redundant `Child|Parent` union.

docs/todo/type-inference.md

@@ -481,14 +481,6 @@ design.
 This fixed `Order:646,647` (`json_decode` → `mixed` → `is_object`
 guard → property access).
 
-**Remaining:** `instanceof` narrowing on array element access
-expressions (T20 concern). The narrowing system only matches bare
-variable names (`$var`), not subscript expressions (`$arr[0]`).
-The `PurchaseFileService` case that originally motivated this item
-is now resolved by the `DB::select()` return type patch (B14) combined
-with `stdClass` property access suppression, but the general gap
-remains for any `$arr[$i] instanceof Foo` pattern.
-
 ## T25. Call-site template argument inference for callable parameters
 
 **Impact: Medium · Effort: Medium — partially done**

src/completion/resolver.rs

@@ -35,6 +35,7 @@ use crate::Backend;
 use crate::docblock;
 use crate::inheritance::resolve_property_type_hint;
 use crate::php_type::PhpType;
+use crate::subject_expr::BracketSegment;
 use crate::subject_expr::SubjectExpr;
 use crate::types::*;
 use crate::util::{find_class_by_name, is_self_or_static, resolve_class_keyword};
@@ -672,6 +673,72 @@ fn resolve_target_classes_expr_inner_impl(
 
         // ── Array access on variable or call expression ─────────
         SubjectExpr::ArrayAccess { base, segments } => {
+            // Check if the scope has a narrowed type for this array
+            // access (e.g. `$row['page']` narrowed via `instanceof`).
+            if let Some(scope_resolver) = ctx.scope_var_resolver {
+                // Build the scope key with double-quote format used by
+                // `expr_to_subject_key` (e.g. `$row["page"]`).
+                let scope_key = {
+                    let mut k = base.to_subject_text();
+                    for seg in segments {
+                        match seg {
+                            BracketSegment::StringKey(s) => {
+                                k.push_str(&format!("[\"{}\"]", s));
+                            }
+                            BracketSegment::ElementAccess => {
+                                k.push_str("[]");
+                            }
+                        }
+                    }
+                    k
+                };
+                let from_scope = scope_resolver(&scope_key);
+                if !from_scope.is_empty() {
+                    return from_scope;
+                }
+            }
+            // When no scope resolver is available (top-level completion),
+            // try resolving the full array access key through the forward
+            // walker.  This picks up instanceof narrowing on array elements
+            // (e.g. `$row['page'] instanceof Page` narrows `$row["page"]`).
+            if ctx.scope_var_resolver.is_none() && matches!(base.as_ref(), SubjectExpr::Variable(_))
+            {
+                let scope_key = {
+                    let mut k = base.to_subject_text();
+                    for seg in segments {
+                        match seg {
+                            BracketSegment::StringKey(s) => {
+                                k.push_str(&format!("[\"{}\"]", s));
+                            }
+                            BracketSegment::ElementAccess => {
+                                k.push_str("[]");
+                            }
+                        }
+                    }
+                    k
+                };
+                let dummy_class;
+                let effective_class = match current_class {
+                    Some(cc) => cc,
+                    None => {
+                        dummy_class = ClassInfo::default();
+                        &dummy_class
+                    }
+                };
+                let resolved = crate::completion::variable::resolution::resolve_variable_types(
+                    &scope_key,
+                    effective_class,
+                    all_classes,
+                    ctx.content,
+                    ctx.cursor_offset,
+                    class_loader,
+                    Loaders::with_function(ctx.function_loader),
+                );
+                if !resolved.is_empty() {
+                    return resolved;
+                }
+            }
+
             // When the base is a call expression (e.g. `$c->items()[0]`),
             // resolve the call's raw return type and use it as a candidate
             // for array-segment walking.  This mirrors the variable path

src/completion/variable/forward_walk.rs

@@ -8803,10 +8803,10 @@ fn collect_condition_property_keys(expr: &Expression<'_>) -> Vec<String> {
 
 fn collect_condition_property_keys_inner(expr: &Expression<'_>, keys: &mut Vec<String>) {
     match expr {
-        // instanceof: `$a->foo instanceof Foo`
+        // instanceof: `$a->foo instanceof Foo` or `$row["page"] instanceof Foo`
         Expression::Binary(bin) if bin.operator.is_instanceof() => {
             if let Some(key) = narrowing::expr_to_subject_key(bin.lhs)
-                && key.contains("->")
+                && (key.contains("->") || key.contains("[\""))
                 && !keys.contains(&key)
             {
                 keys.push(key);
@@ -8860,7 +8860,7 @@ fn collect_condition_property_keys_inner(expr: &Expression<'_>, keys: &mut Vec<S
                         Argument::Named(named) => named.value,
                     };
                     if let Some(key) = narrowing::expr_to_subject_key(arg_expr)
-                        && key.contains("->")
+                        && (key.contains("->") || key.contains("[\""))
                         && !keys.contains(&key)
                     {
                         keys.push(key);

tests/integration/completion_type_guard_narrowing.rs

@@ -535,3 +535,35 @@ async fn test_not_is_array_reassignment_to_array_foreach() {
         methods
     );
 }
+
+// ── instanceof narrowing on array access expressions ────────────────────
+
+#[tokio::test]
+async fn test_instanceof_narrows_array_access_expression() {
+    let backend = create_test_backend();
+    let uri = Url::parse("file:///instanceof_array_access.php").unwrap();
+    let text = concat!(
+        "<?php\n",
+        "class Page {\n",
+        "    public function getId(): int { return 1; }\n",
+        "}\n",
+        "class Table {\n",
+        "    /** @return array<int, array<string, mixed>> */\n",
+        "    public function getRows(): array { return []; }\n",
+        "}\n",
+        "function test(Table $table): void {\n",
+        "    foreach ($table->getRows() as $row) {\n",
+        "        if ($row['page'] instanceof Page) {\n",
+        "            $row['page']->\n",
+        "        }\n",
+        "    }\n",
+        "}\n",
+    );
+    let items = complete_at(&backend, &uri, text, 11, 28).await;
+    let methods = method_names(&items);
+    assert!(
+        methods.contains(&"getId"),
+        "After instanceof narrowing on array access, should see Page methods; got: {:?}",
+        methods
+    );
+}