Add type-guard narrowing for is_array, is_object, and scalars

Author: AJenbo

docs/CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Fix unsafe `new static()` code action.** When PHPStan reports `new.static`, three quickfixes are offered: add `@phpstan-consistent-constructor` to the class docblock (preferred), add `final` to the class, or add `final` to the constructor. The diagnostic is eagerly cleared after applying any of the fixes.
 - **Keyword completions.** Context-aware PHP keyword suggestions in statement positions. Keywords are filtered by scope: `return` and `yield` only inside functions, `break` only inside loops and `switch`, `continue` only inside loops, `case` and `default` only inside `switch`, `namespace` only at the top level, and `extends`/`implements` only in declaration headers. Class-like bodies restrict completions to member keywords (`public`, `function`, `const`, etc.) appropriate for the specific kind (class, interface, trait, or enum). Enum backing types (`int`, `string`) are suggested after `enum Name:`. Modifier chains (`public static `) trigger member-keyword completions. Contributed by @ryangjchandler in https://github.com/AJenbo/phpantom_lsp/pull/43.
 - **Attribute completion.** Typing inside `#[…]` now only offers classes decorated with `#[\Attribute]`, filtered by the target of the declaration the attribute applies to. An attribute targeting only methods will not appear when writing `#[…]` above a class, and vice versa. Multi-attribute lists (`#[A, B]`) and namespace-qualified prefixes are supported.
+- **Type-guard narrowing.** `is_array()`, `is_string()`, `is_int()`, `is_float()`, `is_bool()`, `is_object()`, `is_numeric()`, and `is_callable()` now narrow union types inside `if` bodies, `else` bodies, `elseif` bodies, and after guard clauses. When a parameter has a PHPDoc union like `null|list<Request>|Request` with a native hint `null|array|Request`, `is_array()` narrows to `list<Request>`, preserving the generic element type so that `foreach` iteration resolves correctly.
 - **Deferred code action computation.** Code actions now use the two-phase `codeAction/resolve` model. The lightbulb menu appears instantly because expensive edit computation (extract function, inline variable, etc.) is deferred until the user actually picks an action. PHPStan quickfixes clear their diagnostic immediately when applied instead of relying on heuristic content scanning on every keystroke.
 - **Extract function/method.** Select one or more complete statements inside a function or method body and extract them into a new function or private method (`refactor.extract`). Multiple return values use array destructuring. Type hints are inferred automatically. Early returns within the selection are supported, including guard clauses.
 - **Extract variable.** Select an expression and extract it into a new local variable assigned just before the enclosing statement (`refactor.extract`). Smart name generation from method calls (`getName()` → `$name`), property access (`->email` → `$email`), and function calls.

docs/todo.md

@@ -23,7 +23,6 @@ within the same impact tier.
 
 | #   | Item                                                                                                                                             | Impact | Effort |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------ |
-| B7  | [PHPDoc `@param` generic array type not merged with native `array` hint](todo/bugs.md#b7-phpdoc-param-generic-array-type-not-merged-with-native-array-hint) | Low | Medium |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union) | Medium | Medium |
 | H6  | `return.type` — update return type to match actual returns                                                                                       | Medium | Medium |
 |     | **Release 0.7.0**                                                                                                                                |        |        |

docs/todo/bugs.md

@@ -1,34 +1,3 @@
 # PHPantom — Bug Fixes
 
-## B7: PHPDoc `@param` generic array type not merged with native `array` hint
-
-When a method has a native type hint `array` and a PHPDoc `@param` with
-a generic type like `list<Request>`, PHPantom doesn't merge the PHPDoc
-element type with the native `array` for narrowing purposes. After an
-`is_array()` guard, the variable narrows to `array` but loses the `Request`
-element type from the docblock.
-
-Real-world example — `MobilePayConnection.php`:
-
-```php
-/**
- * @param null|list<Request>|Request $request
- */
-protected function connect(string $uri, null|array|Request $request, ...): MobilePayResponse
-{
-    if (is_array($request)) {
-        foreach ($request as $item) {
-            $serializedObjects[] = $item->jsonSerialize();
-            //                     ^^^^^ unresolved
-        }
-    }
-}
-```
-
-After `is_array($request)`, `$request` narrows from `null|array|Request`
-to `array`. The `@param` says the array case is `list<Request>`, so
-`$item` should be `Request`. But the LSP doesn't unify the narrowed
-native `array` with the docblock's `list<Request>`.
-
-**Impact:** 1 diagnostic in the shared project
-(`MobilePayConnection:76`).
+No outstanding items.

example.php

@@ -218,6 +218,45 @@ public function demo(): void
 }
 
 
+// ── Type Guard Narrowing (is_array, is_object, …) ──────────────────────────
+
+class TypeGuardNarrowingDemo
+{
+    /**
+     * @param null|list<Pen>|Pen $input
+     */
+    public function demo(null|array|Pen $input): void
+    {
+        // is_array() narrows the union to the array-like PHPDoc member,
+        // preserving the generic element type for foreach iteration.
+        if (is_array($input)) {
+            foreach ($input as $pen) {
+                $pen->write();                    // list<Pen> → Pen
+            }
+        }
+
+        // Else branch: non-array members survive
+        if (is_array($input)) {
+            // array branch
+        } else {
+            // $input is null|Pen here
+        }
+
+        // Guard clause: is_array() + early return
+        if (is_array($input)) {
+            return;
+        }
+        // $input is null|Pen after the guard
+
+        // is_object() narrows to class members only
+        $mixed = pickRockOrBanana();              // Rock|Banana
+        if (is_object($mixed)) {
+            $mixed->weigh();                      // both Rock and Banana have weigh()
+        }
+    }
+}
+
+
 // ── instanceof self/static/parent Narrowing ────────────────────────────────
 
 class InstanceofSelfDemo extends ScaffoldingSedan
@@ -5715,6 +5754,23 @@ function runDemoAssertions(): void
         );
     }
 
+    // ── Type guard narrowing ────────────────────────────────────────────
+    /** @var list<Pen> $tgPens */
+    $tgPens = [new Pen('a'), new Pen('b')];
+    /** @var null|list<Pen>|Pen $tgInput */
+    $tgInput = $tgPens;
+    if (is_array($tgInput)) {
+        foreach ($tgInput as $tgPen) {
+            assert($tgPen instanceof Pen, 'is_array() narrowed foreach element must be Pen');
+        }
+    }
+    $tgSingle = new Pen('solo');
+    /** @var list<Pen>|Pen $tgMixed */
+    $tgMixed = $tgSingle;
+    if (!is_array($tgMixed)) {
+        assert($tgMixed instanceof Pen, 'Else branch of is_array() must be Pen');
+    }
+
     echo "All assertions passed.\n";
 }