Fix interface method return type inheritance and global fallback

Author: AJenbo

docs/CHANGELOG.md

@@ -47,6 +47,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`__get` magic method template resolution.** Property access on a class whose `__get` uses method-level `@template` with `key-of<T>` bounds and `T[K]` return types now infers the concrete type from the property name. For example, `$bag->a` on a `DataBag<array{a: int, b: string}>` resolves to `int`.
 - **`(object)` cast type inference.** Casting a scalar to object now resolves to `object{scalar: <type>}` and casting a typed array shape resolves to an object shape with matching properties.
+- **Interface method return type inheritance.** When a class implements a same-file interface with `@implements Interface<ConcreteType>` and overrides a method without a return type, the interface method's template-substituted return type is now propagated.
+- **Class loader global fallback.** Unqualified class names used in namespaced code without a `use` statement (e.g. `implements IteratorAggregate` in `namespace App`) now fall back to global scope lookup when the namespace-qualified name doesn't exist.
 - **Literal `true`/`false` preserved in template inference.** Passing `true` or `false` to a generic constructor now keeps the precise type as the template argument (e.g. `C<false>`) instead of widening to `bool`.
 - **`@psalm-method` overrides `@method`.** When a class has both `@method int foo()` and `@psalm-method string foo()`, the vendor-prefixed tag now takes priority instead of using whichever appeared first in the docblock.
 - **Multi-namespace class resolution.** In files with multiple `namespace` blocks, short class names now resolve against the correct namespace for the current scope instead of picking the first same-named class in the file.

docs/todo/bugs.md

@@ -17,22 +17,30 @@ to second-guess upstream output.
 `tests/psalm_assertions/template_class_template_extends.php`.
 
 Constructor generic inference through inherited constructors,
-case-insensitive method lookup, and function-level `@template`
-inference through generic wrapper params are now fixed.
+case-insensitive method lookup, function-level `@template`
+inference through generic wrapper params, and function name
+resolution in multi-namespace files are now fixed.
 Remaining gaps:
 
-- **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.
+- **Multi-namespace file class/function shadowing**: class names
+  from earlier namespaces leak into later namespaces in single-file
+  tests, causing wrong resolution. Works correctly in real projects.
 - **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.
+- **`@template-implements` return type inheritance from stub interfaces**:
+  when a class implements a stub-loaded interface (e.g. `IteratorAggregate`)
+  with `@template-implements Interface<T>` and overrides a method without
+  a return type, the interface method's substituted return type is not
+  propagated. Works correctly for same-file interfaces.
 
 **Tests:** SKIPs in `tests/psalm_assertions/template_class_template_extends.php`
-(lines 427, 500, 682, 980, 981).
+(lines 427, 500, 682, 737-738, 843, 980-981).
 
 
 ## B14. Template/generic resolution in namespace-level and complex scenarios

src/inheritance.rs

@@ -552,6 +552,36 @@ pub(crate) fn resolve_class_with_inheritance(
         current = ClassRef::Owned(parent);
     }
 
+    // 3. Enrich methods from implemented interfaces.
+    //    When a class overrides an interface method without a return type,
+    //    propagate the interface method's return type (with template
+    //    substitution from `@implements` generics).
+    for iface_name in &class.interfaces {
+        let Some(iface) = class_loader(iface_name) else {
+            continue;
+        };
+
+        // Build substitution map from @implements/@template-implements generics.
+        let iface_subs =
+            build_substitution_map(&ClassRef::Borrowed(class), &iface, &HashMap::new());
+
+        for method in &iface.methods {
+            // Only enrich methods that the class already has (i.e. overrides).
+            if let Some(existing) = merged
+                .methods
+                .make_mut()
+                .iter_mut()
+                .find(|m| m.name == method.name)
+            {
+                let mut ancestor_method = (**method).clone();
+                if !iface_subs.is_empty() {
+                    apply_substitution_to_method(&mut ancestor_method, &iface_subs);
+                }
+                enrich_method_from_ancestor(Arc::make_mut(existing), &ancestor_method);
+            }
+        }
+    }
+
     // Refine the `value` property on backed enums.  The `BackedEnum`
     // interface declares `public readonly int|string $value`, but each
     // concrete backed enum knows its specific backing type.  Replace

src/resolution.rs

@@ -839,6 +839,16 @@ impl Backend {
             if let Some(cls) = self.find_or_load_class(stripped) {
                 return Some(cls);
             }
+            // When the name is namespace-qualified (e.g. "App\IteratorAggregate")
+            // and the direct lookup failed, try the short name as a global class.
+            // This handles the case where resolve_parent_class_names prepended the
+            // file namespace to an unqualified global class name.
+            if stripped.contains('\\') {
+                let short = crate::util::short_name(stripped);
+                if let Some(cls) = self.find_or_load_class(short) {
+                    return Some(cls);
+                }
+            }
             self.resolve_class_name(name, classes, use_map, namespace)
         }
     }

tests/psalm_assertions/template_class_template_extends.php

@@ -424,7 +424,7 @@ public function getIterator() {
 
     $i = (new SomeIterator())->getIterator();
 
-    assertType('Traversable<int, Foo>', $i); // SKIP — getIterator return type not inferred from @template-implements IteratorAggregate
+    assertType('Traversable<int, Foo>', $i); // SKIP — stub-loaded interface (IteratorAggregate) template resolution not propagating to child method
 }
 
 // Test: extendClassThatParameterizesTemplatedParent