Fix multi-namespace type resolution and foreach narrowing bugs

Author: AJenbo

docs/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **Multi-namespace function return type resolution.** In files with multiple `namespace { }` blocks, function return types were resolved against the first namespace instead of the function's own namespace. This caused incorrect type inference for variables assigned from function calls in later namespace blocks.
+- **Short class name resolution in type hints.** When resolving an unqualified class name from a property or return type annotation, the resolver now prefers the class in the same namespace as the owning type before falling back to first-match.
+- **Foreach narrowing with break in else.** When a foreach body contained an `if` with an `else { break; }` branch, the variable state from the break path was not included in the post-loop type, causing the merged type to be too narrow.
+- **Foreach element type from untyped arrays.** Variables bound in a `foreach` over an untyped `array` (e.g. from a function returning bare `array`) now resolve to `mixed` instead of empty, so assignments from the loop variable propagate correctly.
+- **Foreach target type after non-empty literal array.** When iterating a non-empty literal array such as `["a", "b", "c"]`, the pre-loop sentinel value of the target variable (e.g. `null` from `$tag = null`) no longer survives as a possible post-loop type.
+
 ### Changed
 
 - **Updated embedded phpstorm-stubs.** Generic annotations for `ArrayIterator`, `ArrayObject`, `SplDoublyLinkedList`, `SplQueue`, `SplStack`, `SplPriorityQueue`, `SplFixedArray`, `SplObjectStorage`, and `array_reduce` are now provided by upstream stubs directly, removing the need for runtime patches.

docs/todo/bugs.md

@@ -21,18 +21,18 @@ case-insensitive method lookup, and function-level `@template`
 inference through generic wrapper params are now fixed.
 Remaining gaps:
 
-- **Function name resolution in multi-namespace files**: bare
-  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.
+- **Multi-namespace class shadowing in `IteratorAggregate` resolution**:
+  When a multi-namespace file defines a class like `SomeIterator` in
+  an earlier namespace, resolving `getIterator()` return type
+  `ArrayIterator<K, V>` may pick up the wrong class.
 - **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.
 
 **Tests:** SKIPs in `tests/psalm_assertions/template_class_template_extends.php`
-(lines 177, 227, 427, 500, 682, 843 (namespace)).
+(lines 427, 500, 682, 980, 981).
 
 
 ## B14. Template/generic resolution in namespace-level and complex scenarios
@@ -65,37 +65,6 @@ only by this infrastructure limitation.
 640, 667, 701, 710, 788, 800).
 
 
-## B15. Loop exit type narrowing
-
-**Discovered:** SKIP audit of `tests/psalm_assertions/loop_while.php`,
-`loop_foreach.php`.
-
-Loop exit truthiness narrowing (e.g. `while ($a) { ... }` narrowing
-`$a` to `null` after the loop) works for do-while loops but not for
-while loops when the variable is reassigned inside the loop body.
-Remaining issues:
-
-- While loop exit narrowing not applied to variables reassigned
-  inside the loop body (e.g. `$a = $a->parent` in `while ($a)`
-  should yield `null` after exit)
-- `instanceof` loop exit narrowing does not strip the matched type
-  (e.g. `while ($a instanceof A)` should narrow to `B` for `A|B`)
-- Property access on loop-narrowed variable returns no type
-- `foreach` loop variable not narrowed away from initial `null`
-  after non-empty iteration (would require tracking iterable
-  emptiness)
-- Break-in-else branch type not merged with loop variable
-- Assignment from untyped array value inside null check not
-  widened to `mixed`
-
-Related to T20 (type narrowing reconciliation engine) and T29
-(definite vs possible variable existence tracking).
-
-**Tests:** SKIPs in `loop_while.php` (lines 39, 67, 91, 115, 152),
-`loop_foreach.php` (lines 81, 128, 156, 188, 208).
-
-
-
 
 ## B16. PDOStatement fetch mode-dependent return types
 

src/completion/types/resolution.rs

@@ -298,9 +298,25 @@ fn resolve_named_type(
     };
 
     // ── Class lookup ───────────────────────────────────────────────
-    let found = find_class_by_name(all_classes, name)
-        .map(Arc::clone)
-        .or_else(|| class_loader(name));
+    // When `name` is a short name (no backslash), prefer a class in the
+    // same namespace as the owning class.  This prevents cross-namespace
+    // contamination in multi-namespace files where multiple namespaces
+    // define a class with the same short name.
+    let found = if !name.contains('\\') && owning_class_name.contains('\\') {
+        let owning_ns = owning_class_name.rsplit_once('\\').map(|(ns, _)| ns);
+        // Try same-namespace first.
+        let same_ns = all_classes
+            .iter()
+            .find(|c| c.name == name && c.file_namespace.as_deref() == owning_ns)
+            .map(Arc::clone);
+        same_ns
+            .or_else(|| find_class_by_name(all_classes, name).map(Arc::clone))
+            .or_else(|| class_loader(name))
+    } else {
+        find_class_by_name(all_classes, name)
+            .map(Arc::clone)
+            .or_else(|| class_loader(name))
+    };
 
     match found {
         Some(cls) => {

src/completion/variable/forward_walk.rs

@@ -5523,13 +5523,24 @@ fn process_if_statement_body<'b>(
     if !then_exits || then_exits_via_loop {
         surviving_scopes.push(&then_scope);
     }
-    for (ei_scope, ei_exits) in &elseif_scopes {
-        if !ei_exits {
+    for (idx, (ei_scope, ei_exits)) in elseif_scopes.iter().enumerate() {
+        if !ei_exits
+            || body
+                .else_if_clauses
+                .iter()
+                .nth(idx)
+                .is_some_and(|ei| exits_via_loop_control(ei.statement))
+        {
             surviving_scopes.push(ei_scope);
         }
     }
     if let Some(ref es) = else_scope {
-        if !else_exits {
+        if !else_exits
+            || body
+                .else_clause
+                .as_ref()
+                .is_some_and(|ec| exits_via_loop_control(ec.statement))
+        {
             surviving_scopes.push(es);
         }
     } else {
@@ -6074,6 +6085,7 @@ fn process_foreach<'b>(foreach: &'b Foreach<'b>, scope: &mut ScopeState, ctx: &F
         let foreach_offset = foreach.foreach.span().start.offset as usize;
         let before = &ctx.content[..foreach_offset.min(ctx.content.len())];
         let trimmed = before.trim_end();
+        let mut docblock_matched = false;
         if trimmed.ends_with("*/")
             && let Some(doc_start) = trimmed.rfind("/**")
         {
@@ -6088,8 +6100,16 @@ fn process_foreach<'b>(foreach: &'b Foreach<'b>, scope: &mut ScopeState, ctx: &F
             {
                 let resolved = resolve_type_to_resolved_types(&php_type, ctx);
                 scope.set(vn, resolved);
+                docblock_matched = true;
             }
         }
+        // When the iterable is a bare `array` (no generic parameters)
+        // and no @var docblock provided a concrete type, the element
+        // type is `mixed`.  Seed it so that assignments from the loop
+        // variable propagate `mixed` correctly through the body.
+        if !docblock_matched && iter_type.as_ref().is_some_and(|it| it.is_bare_array()) {
+            scope.set(vn, vec![ResolvedType::from_type_string(PhpType::mixed())]);
+        }
     }
 
     // ── Assignment-depth-bounded loop iteration ─────────────────
@@ -6168,6 +6188,24 @@ fn process_foreach<'b>(foreach: &'b Foreach<'b>, scope: &mut ScopeState, ctx: &F
     *scope = pre_loop_scope;
     scope.merge_branch(&post_loop);
 
+    // When the iterable is a non-empty literal array (e.g. `["a", "b",
+    // "c"]`), the loop body is guaranteed to execute at least once.
+    // The pre-loop sentinel value (e.g. `null` from `$tag = null`) must
+    // not survive as a possible post-loop type for the foreach target
+    // variable — override it with the post-loop value from the body walk.
+    if is_non_empty_array_literal(foreach.expression) {
+        let target_var = match &foreach.target {
+            ForeachTarget::Value(val) => extract_foreach_var_name(val.value),
+            ForeachTarget::KeyValue(kv) => extract_foreach_var_name(kv.value),
+        };
+        if let Some(ref vn) = target_var
+            && let Some(post_val) = post_loop.locals.get(&ustr::ustr(vn.as_str()))
+            && !post_val.is_empty()
+        {
+            scope.set(vn, post_val.clone());
+        }
+    }
+
     leave_loop(loop_depth);
 }
 
@@ -6545,6 +6583,20 @@ fn bind_foreach_value<'b>(
     }
 }
 
+/// Returns `true` when `expr` is a non-empty array literal such as
+/// `["a", "b", "c"]` or `array(1, 2, 3)`.
+///
+/// Used by `process_foreach` to detect iterables that are guaranteed to
+/// have at least one element, so that the pre-loop type of the target
+/// variable does not survive into the post-loop scope.
+fn is_non_empty_array_literal(expr: &Expression<'_>) -> bool {
+    match expr {
+        Expression::Array(arr) => !arr.elements.is_empty(),
+        Expression::LegacyArray(arr) => !arr.elements.is_empty(),
+        _ => false,
+    }
+}
+
 /// Extract the variable name from a foreach value expression, unwrapping
 /// a leading `&` (by-reference) if present.
 fn extract_foreach_var_name(expr: &Expression<'_>) -> Option<String> {

src/parser/ast_update.rs

@@ -248,7 +248,11 @@ impl Backend {
             for func in &mut functions {
                 let skip_names: Vec<String> =
                     func.template_params.iter().map(|a| a.to_string()).collect();
-                let resolver = Self::build_type_resolver(&use_map, &namespace, &skip_names);
+                // Use the function's own namespace (not the file-level one)
+                // so that multi-namespace files resolve return types
+                // against the correct namespace block.
+                let func_ns = func.namespace.clone().or_else(|| namespace.clone());
+                let resolver = Self::build_type_resolver(&use_map, &func_ns, &skip_names);
 
                 if let Some(ref ret) = func.return_type {
                     let resolved = ret.resolve_names(&resolver);