Infer array key/value generics in constructors and evaluate

key-of/value-of after substitution

Author: AJenbo

docs/CHANGELOG.md

@@ -53,6 +53,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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).
 - **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.
+- **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>`). Array literal arguments to `@param array<TKey, TValue>` constructor parameters now infer key and value types separately (e.g. `["a" => new Foo()]` infers `TKey=string, TValue=Foo`). `key-of<T>`, `value-of<T>`, and indexed access types (`T[K]`) now evaluate to concrete types after template substitution (e.g. `value-of<array{name: string, user: User}>` resolves to `string|User`).
 - **Vendor functions and constants.** Functions and constants defined in vendor packages are now indexed at startup, eliminating false-positive "Function not found" diagnostics.
 - **Use-imported classes no longer shadowed by global-namespace stubs.** The use-map is now checked first for unqualified names, fixing Laravel Facade static method resolution.
 - **Same-name class in a different namespace no longer shadows inherited members.** Parent resolution no longer picks up a same-named class from the current namespace instead of the intended global-namespace parent.

docs/todo/bugs.md

@@ -25,14 +25,17 @@ Remaining gaps:
   function names in namespaced code are not resolved to their FQN,
   so function-level template inference fails in single-file tests
   with multiple namespaces. Works correctly in real projects.
-- **`array<TKey, TValue>` constructor inference**: multi-arg array
-  generic params in constructors (e.g. `@param array<TKey,TValue> $kv`)
-  do not infer key/value types separately.
-- **`key-of<T>` and indexed access types** (`T[K]`): advanced type
-  operators not yet supported.
+- **Method-level `@template` with `key-of<T>` bound and `T[K]` return**:
+  `key-of<T>`, `value-of<T>`, and `T[K]` now evaluate correctly after
+  class-level template substitution. However, inferring a method-level
+  template parameter `K` from a string literal argument (to resolve
+  `T[K]` at a specific call site) is not yet supported.
+- **`__get` magic method template resolution**: `$foo->a` on a class
+  using `__get` with `@template K as key-of<TData>` / `@return TData[K]`
+  does not infer `K` from the property name.
 
 **Tests:** SKIPs in `tests/psalm_assertions/template_class_template_extends.php`
-(lines 177, 227, 427, 500, 681-682, 737-738, 843 (namespace)).
+(lines 177, 227, 427, 500, 682, 737-738, 843 (namespace)).
 
 
 ## B14. Template/generic resolution in namespace-level and complex scenarios

src/completion/variable/rhs_resolution.rs

@@ -1404,6 +1404,17 @@ fn resolve_generic_wrapper_template(
     rctx: &crate::completion::resolver::ResolutionCtx<'_>,
     ctx: &VarResolutionCtx<'_>,
 ) -> Option<PhpType> {
+    // ── Built-in array-like types ───────────────────────────────
+    // `array`, `list`, `non-empty-array`, `non-empty-list` are not
+    // real classes — infer key/value types directly from the array
+    // literal argument.
+    if matches!(
+        wrapper_name,
+        "array" | "list" | "non-empty-array" | "non-empty-list"
+    ) {
+        return resolve_array_literal_generic(tpl_position, arg_text, rctx);
+    }
+
     // Load the wrapper class.
     let wrapper_cls = (ctx.class_loader)(wrapper_name)
         .map(Arc::unwrap_or_clone)
@@ -1439,6 +1450,75 @@ fn resolve_generic_wrapper_template(
     wrapper_subs.get(wrapper_tpl.as_str()).cloned()
 }
 
+/// Infer a generic type argument from an array literal.
+///
+/// For `@param array<TKey, TValue> $kv` with argument `["a" => 1]`:
+/// - `tpl_position == 0` → key type (`string`)
+/// - `tpl_position == 1` → value type (`int`)
+///
+/// For single-param wrappers like `list<T>`, position 0 is the element type.
+fn resolve_array_literal_generic(
+    tpl_position: usize,
+    arg_text: &str,
+    rctx: &crate::completion::resolver::ResolutionCtx<'_>,
+) -> Option<PhpType> {
+    let trimmed = arg_text.trim();
+
+    // Must be an array literal.
+    let inner = if trimmed.starts_with('[') && trimmed.ends_with(']') {
+        trimmed[1..trimmed.len() - 1].trim()
+    } else if let Some(s) = trimmed.strip_prefix("array(") {
+        s.strip_suffix(')')?.trim()
+    } else {
+        // Not an array literal — cannot infer.
+        return None;
+    };
+
+    if inner.is_empty() {
+        return Some(PhpType::never());
+    }
+
+    let elements = crate::completion::conditional_resolution::split_text_args(inner);
+
+    // Determine whether elements are key=>value pairs.
+    // Check the first element for `=>`.
+    let first = elements.first()?.trim();
+    let has_keys = first.contains("=>");
+
+    if has_keys {
+        // Collect key types (position 0) or value types (position 1)
+        // from the first element (sufficient for inference).
+        let arrow_pos = first.find("=>")?;
+        match tpl_position {
+            0 => {
+                let key_text = first[..arrow_pos].trim();
+                Backend::resolve_arg_text_to_type(key_text, rctx)
+            }
+            1 => {
+                let val_text = first[arrow_pos + 2..].trim();
+                Backend::resolve_arg_text_to_type(val_text, rctx)
+            }
+            _ => None,
+        }
+    } else {
+        // No keys — this is a list-style array.
+        // Position 0 in `array<T>` or `list<T>` is the element type.
+        // Position 0 in `array<TKey, TValue>` would be `int` (implicit key).
+        // Position 1 in `array<TKey, TValue>` is the element type.
+        match tpl_position {
+            0 => {
+                // Implicit integer keys.
+                Some(PhpType::Named("int".to_string()))
+            }
+            1 => {
+                // Element type from first element.
+                Backend::resolve_arg_text_to_type(first, rctx)
+            }
+            _ => None,
+        }
+    }
+}
+
 /// Resolve `$arr[0]` / `$arr[$key]` by extracting the generic element
 /// type from the base array's annotation or assignment.
 fn resolve_rhs_array_access<'b>(