Substitute generic return types when the native hint is nullable

`should_override_type_typed` used `unwrap_nullable()`, which only strips
the
`?Foo` (Nullable) form and not the `Foo|null` (Union-with-null) form. A
nullable-union native such as `object|null` therefore reached the union
branch with its `null` member attached; since `object` and `null` are
both
scalar names, the branch judged the type unrefinable and discarded a
generic
docblock return like `@psalm-return ?T`, leaving the bare native.

Use `non_null_type()` (strips null from both Nullable and Union forms)
so the
non-null part is analysed, matching the function's documented `Foo|null
→ Foo`
intent. Fixes inherited generic returns such as Doctrine's
`ServiceEntityRepository<T>::find(): ?T` resolving to `object|null`.

Adds an assert_type regression fixture.

Signed-off-by: Anders Jenbo <anders@jenbo.dk>

Author: MrSrsen

docs/CHANGELOG.md

@@ -43,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`@method` tags override inherited methods of the same name.** A `@method` annotation on a class now takes precedence over a method inherited from a more distant ancestor. The common repository pattern, where a base repository declares `@method Entity|null findOneBy(...)` while its vendor parent returns a generic `object`, now resolves to the concrete entity type, so members accessed on the result are no longer flagged as unverifiable.
 - **`??=` keeps the resolved type.** After `$x ??= new Foo()`, the variable resolves to `Foo` (or the union of its existing non-null type and the assigned value), so property and method access on `$x` is no longer reported as unresolvable.
 - **Generics with fewer arguments than parameters.** `@extends Collection<User>` against `Collection<TKey, TValue>` now binds `User` to the value parameter, so inherited element types resolve correctly.
+- **Nullable generic return types resolve through inheritance.** A method whose native return hint is nullable (`object|null`) and whose docblock returns a template (`@return ?T`) now resolves to the bound type, so a repository's `find()` returns `Entity|null` instead of the bare `object|null`. Contributed by @MrSrsen in https://github.com/PHPantom-dev/phpantom_lsp/pull/152.
 - **Conditional `is null` return types** resolve consistently regardless of how the call site is parsed, and an explicitly passed `null` now selects the null branch.
 - **Go-to-definition, rename, and highlight accuracy.** References in `@see` tags to qualified names like `App\Foo::bar()` now land on the correct location, and renaming a property selects the whole `$name` instead of `$nam`.
 - **`@phpstan-require-extends` and `@phpstan-require-implements` navigation.** Class and interface names in these trait constraint tags now support go-to-definition and hover, and an import used only by such a tag is no longer flagged as unused. Contributed by @calebdw in https://github.com/PHPantom-dev/phpantom_lsp/pull/172.

src/docblock/tags.rs

@@ -1297,8 +1297,19 @@ pub fn should_override_type_typed(docblock_type: &PhpType, native_type: &PhpType
 
     // Unwrap nullable wrappers for further analysis.  `?Foo` → `Foo`,
     // `Foo|null` → `Foo`.  For non-nullable types, use as-is.
-    let doc_inner = docblock_type.unwrap_nullable();
-    let native_inner = native_type.unwrap_nullable();
+    //
+    // `non_null_type()` strips nullability from BOTH representations — the
+    // `?Foo` (`Nullable`) form and the `Foo|null` (`Union` with a `null`
+    // member) form.  Plain `unwrap_nullable()` only handled the former, so a
+    // nullable-union native such as `object|null` reached the union branch
+    // below with its `null` member still attached.  Since `object` and `null`
+    // are both "scalar names", that branch then judged the whole type
+    // unrefinable and discarded a generic docblock return like
+    // `@psalm-return ?T`, leaving the bare native (`object|null`).
+    let doc_owned = docblock_type.non_null_type();
+    let doc_inner = doc_owned.as_ref().unwrap_or(docblock_type);
+    let native_owned = native_type.non_null_type();
+    let native_inner = native_owned.as_ref().unwrap_or(native_type);
 
     // If the docblock type is a bare, unparameterised primitive scalar
     // (`int`, `string`, `bool`, etc.), there's no value in overriding.

tests/phpstan_nsrt/inherited-generic-return-nullable.php

@@ -0,0 +1,61 @@
+<?php declare(strict_types = 1);
+
+// Regression: a class-level generic return type whose method has a *nullable*
+// native return hint (e.g. `object|null`) must still be resolved through the
+// `@extends`/`@psalm-return` template binding, not collapse to the native hint.
+//
+// This is the Doctrine `ServiceEntityRepository<T>::find(): ?T` shape: before
+// the fix, `should_override_type_typed` analysed `object|null` with its `null`
+// member attached, judged it unrefinable (both `object` and `null` are "scalar
+// names"), and discarded the generic docblock return — so `$repo->find()`
+// resolved to `object|null` instead of `Entity|null`.
+
+namespace InheritedGenericReturnNullable;
+
+use function PHPStan\Testing\assertType;
+
+class Entity {}
+
+/**
+ * @template T of object
+ */
+class EntityRepository
+{
+	/**
+	 * @return object|null
+	 * @psalm-return ?T
+	 */
+	public function find(mixed $id): object|null {}
+}
+
+/**
+ * @template T of object
+ * @template-extends EntityRepository<T>
+ */
+class ServiceEntityRepository extends EntityRepository {}
+
+/** @extends ServiceEntityRepository<Entity> */
+class EntityRepo extends ServiceEntityRepository {}
+
+/** @extends EntityRepository<Entity> */
+class DirectRepo extends EntityRepository {}
+
+/** @template V */
+class CollectionNonNull
+{
+	/** @return V */
+	public function get(): object {}
+}
+
+/** @extends CollectionNonNull<Entity> */
+class EntityCollection extends CollectionNonNull {}
+
+function t(EntityRepo $multi, DirectRepo $single, EntityCollection $coll): void
+{
+	// Two-level @extends (Doctrine's exact shape): native object|null + @psalm-return ?T
+	assertType('Entity|null', $multi->find(1));
+	// Single-level @extends: native object|null + @psalm-return ?T
+	assertType('Entity|null', $single->find(1));
+	// Control: non-nullable native object + @return V already worked before the fix
+	assertType('Entity', $coll->get());
+}