Fix in_array guard clause type narrowing and class-string<T> static

return

Author: AJenbo

docs/CHANGELOG.md

@@ -67,6 +67,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **`in_array` guard clause no longer wipes out variable type.** When `in_array($item, $exclude, true)` was used as a guard clause (`if (...) { continue; }`) and the haystack's element type matched the variable's resolved type (e.g. both `BackedEnum`), the narrowing system incorrectly excluded the type entirely, leaving the variable untyped for all subsequent accesses. The `in_array` check filters by value, not by type, so the exclusion now skips when it would remove all type information.
 - **`class-string<T>` static method dispatch.** When a variable is typed as `class-string<Foo>` (via `@param` or `@template` bound), calling static methods on it (e.g. `$class::from()`, `$class::cases()`) now resolves the return type correctly. The `static` return type substitutes to the bound class, so `$class::from('x')->name` resolves and `foreach ($class::cases() as $item)` gives `$item` the correct type.
 - **`@var` docblock annotations no longer leak across class and method boundaries.** When the cursor was inside a nested block (foreach, if, while), a `@var` annotation for a same-named variable in a completely different class could bleed into the current scope, producing wrong type information. The backward docblock scanner now correctly detects sibling scopes regardless of nesting depth.
 

docs/todo.md

@@ -24,7 +24,6 @@ within the same impact tier.
 | #   | Item                                                                                                                                                      | Impact | Effort     |
 | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------- |
 | B10 | [`instanceof` ternary narrowing fails when target class is in a phar](todo/bugs.md#b10-instanceof-ternary-narrowing-fails-when-target-class-is-in-a-phar) | Low    | Low-Medium |
-| B11 | [`static` return type not resolved through `class-string<T>` context](todo/bugs.md#b11-static-return-type-not-resolved-through-class-stringt-context)     | Low    | Medium     |
 | B12 | [`Collection::reduce()` generic return type not inferred](todo/bugs.md#b12-collectionreduce-generic-return-type-not-inferred)                             | Low    | Medium     |
 | B13 | [Array shape tracking from keyed literal assignments in loops](todo/bugs.md#b13-array-shape-tracking-from-keyed-literal-assignments-in-loops)             | Low    | High       |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union)          | Medium | Medium     |

docs/todo/bugs.md

@@ -35,39 +35,6 @@ narrowing to occur).
 
 ---
 
-## B11. `static` return type not resolved through `class-string<T>` context
-**Impact: Low · Effort: Medium**
-
-Pattern:
-```php
-/** @param class-string<BackedEnum> $class */
-function enum(BackedEnum $value, string $class): void {
-    foreach ($class::cases() as $item) {
-        $name = $item->name;   // unresolved
-        $val  = $item->value;  // unresolved
-    }
-}
-```
-
-`UnitEnum::cases()` returns `static[]`. When called on a variable
-typed as `class-string<BackedEnum>`, the `static` return type should
-resolve to `BackedEnum[]`, making `$item` typed as `BackedEnum`.
-Currently `static` is not substituted through the `class-string<T>`
-context, so `$item` has no type and `->name` / `->value` are
-unresolvable.
-
-**Observed in:** `OptionList:27,30` — `$class::cases()` where
-`$class` is `class-string<BackedEnum>`.
-
-**Root cause:** The `class-string<T>` static dispatch fix (`caa6163`)
-resolves method signatures and return types for static calls on
-`class-string`-typed variables, but does not substitute `static` in
-the return type with the bound type `T`. The substitution
-`static → BackedEnum` needs to happen when the call target is
-resolved through a `class-string<BackedEnum>` context.
-
----
-
 ## B12. `Collection::reduce()` generic return type not inferred
 **Impact: Low · Effort: Medium**
 

src/completion/types/narrowing.rs

@@ -2161,6 +2161,9 @@ pub(in crate::completion) fn try_apply_in_array_narrowing(
         && let Some(element_type) = resolve_in_array_element_type(haystack_expr, ctx)
     {
         if negated {
+            if !results.is_empty() && would_exclude_all_results(&element_type, results, ctx) {
+                return;
+            }
             apply_instanceof_exclusion(&element_type, ctx, results);
         } else {
             apply_instanceof_inclusion(&element_type, false, ctx, results);
@@ -2191,11 +2194,44 @@ pub(in crate::completion) fn try_apply_in_array_narrowing_inverse(
         if negated {
             apply_instanceof_inclusion(&element_type, false, ctx, results);
         } else {
+            if !results.is_empty() && would_exclude_all_results(&element_type, results, ctx) {
+                return;
+            }
             apply_instanceof_exclusion(&element_type, ctx, results);
         }
     }
 }
 
+/// Check whether excluding `element_type` from `results` would remove
+/// every entry, leaving the variable completely untyped.
+///
+/// `in_array($var, $haystack)` checks whether a *value* is present in
+/// the array, not whether the *type* matches.  When the haystack's
+/// element type is the same as (or a supertype of) every entry in
+/// `results`, exclusion would incorrectly wipe out all type information.
+/// For example, `in_array($item, $exclude)` where both `$item` and
+/// `$exclude`'s elements are `BackedEnum` should not remove
+/// `BackedEnum` from the resolved types — the variable is still a
+/// `BackedEnum`, just not one of the excluded values.
+fn would_exclude_all_results(
+    element_type: &str,
+    results: &[ClassInfo],
+    ctx: &VarResolutionCtx<'_>,
+) -> bool {
+    let excluded = super::resolution::type_hint_to_classes(
+        element_type,
+        &ctx.current_class.name,
+        ctx.all_classes,
+        ctx.class_loader,
+    );
+    if excluded.is_empty() {
+        return false;
+    }
+    results
+        .iter()
+        .all(|r| excluded.iter().any(|e| e.name == r.name))
+}
+
 /// Apply `in_array` guard clause narrowing after an `if` statement
 /// whose then-body unconditionally exits.
 ///
@@ -2227,6 +2263,15 @@ pub(in crate::completion) fn apply_guard_clause_in_array_narrowing(
         if condition_negated {
             apply_instanceof_inclusion(&element_type, false, ctx, results);
         } else {
+            // Skip exclusion when it would remove ALL type information.
+            // `in_array($item, $exclude)` where both `$item` and the
+            // elements of `$exclude` are the same type (e.g. both are
+            // `BackedEnum`) only narrows which *value* of that type the
+            // variable holds, not the type itself.  Excluding would
+            // incorrectly wipe out the variable's type entirely.
+            if !results.is_empty() && would_exclude_all_results(&element_type, results, ctx) {
+                return;
+            }
             apply_instanceof_exclusion(&element_type, ctx, results);
         }
     }

src/diagnostics/unknown_members.rs

@@ -5345,4 +5345,144 @@ function test(object $data): void {
             "expected no diagnostics for object-typed parameter, got: {diags:?}"
         );
     }
+
+    // ── class-string<T> static return type resolution ───────────────
+
+    #[test]
+    fn no_diagnostic_for_class_string_static_return_in_foreach() {
+        // When a parameter is typed `class-string<BackedEnum>` and we
+        // call `$class::cases()`, the `static[]` return type should
+        // resolve to `BackedEnum[]`, making foreach items typed as
+        // `BackedEnum` with `->name` and `->value` available.
+        // UnitEnum and BackedEnum are loaded from stubs (cross-file),
+        // not defined inline, to reproduce the real-world scenario.
+        // Uses the exact pattern from OptionList.php including the
+        // ternary with dynamic method call.
+        let php = r#"<?php
+class OptionList {
+    /**
+     * @param class-string<BackedEnum> $class
+     */
+    public static function enum(BackedEnum $value, string $class, array $exclude = [], string $method = ''): void {
+        foreach ($class::cases() as $item) {
+            if (in_array($item, $exclude, true)) {
+                continue;
+            }
+
+            $name = $method ? $item->{$method}() : $item->name;
+
+            $val = $item->value;
+        }
+    }
+}
+"#;
+        let backend = create_enum_backend();
+        backend.config.lock().diagnostics.unresolved_member_access = Some(true);
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for class-string<BackedEnum> foreach item members, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_class_string_static_return_chained() {
+        // `$class::from('foo')` returns `static` which should resolve
+        // to `BackedEnum` when `$class` is `class-string<BackedEnum>`.
+        // Members like `->name` should be available on the result.
+        // UnitEnum and BackedEnum are loaded from stubs (cross-file),
+        // not defined inline, to reproduce the real-world scenario.
+        let php = r#"<?php
+class Svc {
+    /**
+     * @param class-string<BackedEnum> $class
+     */
+    public function resolve(string $class): void {
+        $result = $class::from('foo');
+        $name = $result->name;
+        $val  = $result->value;
+    }
+}
+"#;
+        let backend = create_enum_backend();
+        backend.config.lock().diagnostics.unresolved_member_access = Some(true);
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for class-string<BackedEnum> static return chain, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn in_array_guard_does_not_wipe_type_when_element_matches() {
+        // When `in_array($item, $exclude, true)` is used as a guard
+        // clause (`if (...) { continue; }`), the `in_array` narrowing
+        // should NOT exclude the variable's type when the haystack's
+        // element type matches the variable's type.  The check filters
+        // by value, not by type — `$item` is still a `BackedEnum`
+        // after the guard, just not one of the excluded values.
+        let php = r#"<?php
+class Foo {
+    public string $name;
+}
+
+class Svc {
+    /**
+     * @param array<int, Foo> $exclude
+     */
+    public function run(Foo $item, array $exclude): void {
+        if (in_array($item, $exclude, true)) {
+            return;
+        }
+        $name = $item->name;
+    }
+}
+"#;
+        let backend = Backend::new_test();
+        backend.config.lock().diagnostics.unresolved_member_access = Some(true);
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "in_array guard should not wipe variable type when element type matches, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn in_array_guard_still_narrows_union_type() {
+        // When the variable is a union type (e.g. `Foo|Bar`) and the
+        // haystack element type is one of the union members (e.g.
+        // `array<int, Foo>`), the guard clause SHOULD narrow: after
+        // `if (in_array($item, $fooList)) { return; }`, `$item` is
+        // not `Foo`, so it must be `Bar`.  The would-exclude-all
+        // check should NOT prevent this narrowing because removing
+        // `Foo` still leaves `Bar`.
+        let php = r#"<?php
+class Foo {
+    public string $fooName;
+}
+class Bar {
+    public string $barName;
+}
+
+class Svc {
+    /**
+     * @param Foo|Bar $item
+     * @param array<int, Foo> $fooList
+     */
+    public function run(object $item, array $fooList): void {
+        if (in_array($item, $fooList, true)) {
+            return;
+        }
+        $name = $item->barName;
+    }
+}
+"#;
+        let backend = Backend::new_test();
+        backend.config.lock().diagnostics.unresolved_member_access = Some(true);
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "in_array guard should still narrow union types, got: {diags:?}"
+        );
+    }
 }