Implement first-class callable immediate invocation and precise binary

expression type inference

Author: AJenbo

docs/CHANGELOG.md

@@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Closure and arrow function inlay hints.** When a closure or arrow function is passed to a callable-typed parameter, inlay hints show inferred parameter types and the return type. Types are derived from the enclosing callable signature with generic substitution from sibling arguments.
 - **Return type inference from method bodies.** Methods without a declared return type or `@return` docblock now have their return type inferred from `return` statements, improving completion, hover, and diagnostics for untyped code.
 - **Untyped property type inference from constructor.** Properties without type declarations are resolved by inspecting the constructor body for assignments and promoted parameter defaults. PHPDoc generation uses the inferred type. Contributed by @lucasacoutinho in https://github.com/AJenbo/phpantom_lsp/pull/81.
-- **Binary expression type inference.** Hover and variable resolution now show result types for all binary operators: arithmetic (`int|float`), concatenation (`string`), comparison and logical (`bool`), bitwise (`int`), and `+` distinguishes array union from numeric addition based on operand types.
+- **Binary expression type inference.** Hover and variable resolution now show result types for all binary operators with operand-type-aware arithmetic (`int + int` → `int`, `int + float` → `float`, `int / int` → `int|float`). Concatenation returns `string`, comparison and logical return `bool`, bitwise returns `int` (or `string` when both operands are strings), spaceship returns `int`, and `+` distinguishes array union from numeric addition. Compound assignments (`/=`, `*=`, `%=`, `**=`, `.=`, `<<=`, `&=`, `|=`, `^=`, `??=`) update the variable's type with the same operand-aware rules. Incrementing a numeric string literal (`$a = "123"; $a++`) produces `int|float`. Parenthesized binary expressions resolve correctly through the structural inference path.
 - **`array_reduce`, `array_sum`, and `array_product` return type inference.** `array_reduce()` resolves to the type of its initial value argument. `array_sum()` and `array_product()` resolve to `int|float`.
 - **`global` keyword variable resolution.** Variables imported with `global $var` now resolve to their top-level type, enabling completion, hover, and go-to-definition.
 - **Nested array shape inference from multi-level key assignments.** Assignments like `$b['a']['b'] = 'x'` now produce a nested array shape type (`array{a: array{b: string}}`), enabling array key completion for arrays built incrementally with nested keys.
@@ -33,9 +33,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **`isset()` narrowing.** `isset($x)` in a condition now strips `null` from the variable's type in the truthy branch (matching `$x !== null` semantics). `!isset($x)` narrows to `null` only. Both simple variables and property access (`$obj->prop`) are supported, and multiple arguments (`isset($a, $b)`) narrow all listed variables. Guard clauses (`if (!isset($x)) { return; }`) strip null from the variable in the code that follows.
+- **First-class callable invocation return types.** Immediately invoking a first-class callable (`Foo::method(...)()`, `$this->method(...)()`, `self::method(...)()`, `static::method(...)()`, `parent::method(...)()`, `func(...)()`) now resolves to the underlying method or function's return type. Previously these expressions returned no type.
+- **`isset()` and `empty()` narrowing.** `isset($x)` in a condition now strips `null` from the variable's type in the truthy branch (matching `$x !== null` semantics). `!isset($x)` narrows to `null` only. `!empty($x)` strips `null` from nullable types (e.g. `string|null` narrows to `string`). Both simple variables and property access (`$obj->prop`) are supported, and multiple arguments (`isset($a, $b)`) narrow all listed variables. Guard clauses (`if (!isset($x)) { return; }`) strip null from the variable in the code that follows.
 - **Hover scales linearly on large files.** Processing many hover requests on the same file (e.g. a test suite with 80+ assertion calls) no longer takes O(n²) time. The first hover on a method body walks it once and caches scope snapshots; every subsequent hover on the same file content is an O(log n) lookup with no re-walk.
 
+- **`@return numeric` pseudo-type.** Functions annotated with `@return numeric` now resolve to the `numeric` pseudo-type instead of `string`. Arithmetic on `numeric` operands correctly infers `int|float`, and `$a++` on a `numeric` variable yields `int|float`. The underlying cause was that same-file function calls in multi-namespace files fell through to an incorrect fallback when the file-level namespace differed from the function's namespace.
 - **`parent::__construct()` with `@extends` generics.** Calling `parent::__construct($arg)` in a child class that specifies `@extends Parent<Concrete>` no longer produces false-positive type errors for the substituted parameter types.
 - **Array access on bare `array` and `mixed` types.** Accessing a key on a parameter typed as plain `array` (e.g. `$params['key']`) now resolves to `mixed` instead of an empty type, eliminating false-positive type errors downstream (e.g. `$x = $params['key'] ?? null` followed by an `is_string()` guard).
 - **Analyzer and LSP no longer hang on files with deeply nested loops.** Files with multiple levels of foreach/while/for inside if-branches no longer cause exponential blowup.

docs/todo/bugs.md

@@ -9,81 +9,6 @@ to second-guess upstream output.
 
 
 
-## B7. `empty()` narrowing resolves to `null` instead of `mixed|null`
-
-**Discovered:** Psalm `TypeReconciliation/EmptyTest.php` porting
-(Phase 3.5B).
-
-When `empty($a)` is true for a `mixed` parameter, the variable should
-retain its base type intersected with falsy values (`mixed|null`), not
-collapse entirely to `null`.
-
-**When fixed:** Create `tests/psalm_assertions/type_reconciliation_empty.php`
-with this content and verify it passes:
-
-```php
-<?php
-// Source: Psalm TypeReconciliation/EmptyTest.php
-namespace PsalmTest_type_reconciliation_empty_1 {
-    /** @param mixed $a */
-    function foo($a): void {
-        if (empty($a)) {
-            assertType('mixed|null', $a);
-        }
-    }
-}
-```
-
-## B8. Binary expression type inference gaps
-
-**Discovered:** SKIP audit across `tests/phpstan_nsrt/binary.php`
-and `tests/psalm_assertions/binary_operation.php`.
-
-The hover/forward-walk pipeline does not resolve types for many
-binary expressions:
-
-- **String concatenation with int LHS:** `$integer . $string`
-  resolves to no type instead of `string`.
-- **Spaceship operator:** `'foo' <=> 'bar'` resolves to no type
-  instead of `int`.
-- **Bitwise on strings:** `"x" & "y"`, `$string & "x"`, `~"a"`
-  resolve to `int` instead of `string`. PHP applies bitwise ops
-  character-by-character when both operands are strings.
-- **Logical operators:** `true && false`, `true || false`,
-  `true xor false`, `!true` resolve to no type instead of `bool`.
-  `xor` on bools resolves to `int` instead of `bool`.
-- **Compound assignment:** `/=`, `*=`, `%=`, `**=`, `<<=`, `&=`,
-  `|=`, `^=` resolve to no type instead of the correct result type.
-- **Mixed arithmetic:** `1 + $mixed`, `$mixed / 1` resolve to no
-  type instead of `float|int`.
-- **Exponent:** `4 ** 5` resolves to `int|float` instead of `int`
-  (when both operands are non-negative integers).
-- **Numeric string increment:** `$a = "123"; $a++` resolves to
-  `string` instead of `float|int`.
-- **String concat compound:** `$d -= getNumeric()` with numeric
-  return resolves to `int` instead of `float|int`.
-
-**Tests:** SKIPs in `tests/phpstan_nsrt/binary.php` (lines 153,
-168, 183-188, 218-224, 229-242, 247-250) and
-`tests/psalm_assertions/binary_operation.php` (lines 10, 17, 56,
-68-69, 87, 100, 165, 175-176).
-
-## B10. First-class callable invocation return types
-
-**Discovered:** SKIP audit of
-`tests/phpstan_nsrt/static-late-binding.php`.
-
-`Foo::method(...)` creates a `Closure` from a method, and
-`Foo::method(...)()` immediately invokes it. The return type of the
-invocation should match the method's return type. Currently hover
-returns no type for these expressions.
-
-This also affects `static::method(...)()`, `self::method(...)()`,
-`parent::method(...)()`, and `$this->method(...)()`.
-
-**Tests:** SKIPs in `tests/phpstan_nsrt/static-late-binding.php`
-(lines 72-78, 88, 90-97).
-
 ## B11. Unbound template parameter resolves to raw name instead of `mixed`
 
 **Discovered:** SKIP audit of

example.php

@@ -2489,6 +2489,14 @@ public function demo(): void
         $make = makePen(...);
         $pen = $make();
         $pen->color();                    // assigned result from callable invocation
+
+        // Immediate invocation: method(...)() returns the method's return type
+        makePen(...)()->write();          // function first-class callable invoked immediately
+        Pen::make(...)()->color();        // static method first-class callable invoked immediately
+        $src->dispatch(...)()->write();   // instance method first-class callable invoked immediately
+
+        $immediate = Pen::make(...)();
+        $immediate->color();              // assigned result from immediate static callable invocation
     }
 }
 
@@ -6231,6 +6239,14 @@ function runDemoAssertions(): void
     $methodResult = $methodCallable();
     assert($methodResult instanceof Pen, 'dispatch(...)() must return Pen');
 
+    // Immediate invocation: method(...)() returns the method's return type
+    $immediateFunc = makePen(...)();
+    assert($immediateFunc instanceof Pen, 'makePen(...)() immediate must return Pen');
+    $immediateStatic = Pen::make(...)();
+    assert($immediateStatic instanceof Pen, 'Pen::make(...)() immediate must return Pen');
+    $immediateMethod = $src2->dispatch(...)();
+    assert($immediateMethod instanceof Pen, '$obj->dispatch(...)() immediate must return Pen');
+
     // ── Class alias (use ... as) ────────────────────────────────────────
     $aliasProfile = new Profile($userForProfile);
     assert($aliasProfile instanceof UserProfile, 'Profile alias must be UserProfile');