Address false-positive argument count errors on overloaded built-in

functions

Author: AJenbo

docs/CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Inherited methods missing through deep stub chains.** Methods like `getCode()` and `getMessage()` are now found on classes that inherit through multi-level chains where intermediate classes live in stubs (e.g. `QueryException` → `PDOException` → `RuntimeException` → `Exception`). Previously the inheritance chain broke when a stub file contained multiple namespace blocks, causing parent class names to be resolved against the wrong namespace.
 - **False-positive diagnostics for same-named variables in different methods.** When two methods in the same class both used a variable like `$order`, the diagnostic cache resolved it once and reused that type for every other method in the class. The second method saw the wrong type and flagged valid member accesses as unknown. Both the per-file subject cache and the cross-collector resolution cache are now scoped to the enclosing function/method/closure body, so each method resolves variables independently.
 - **False-positive diagnostics for `$this` inside traits.** Accessing host-class members via `$this->`, `self::`, `static::`, or `parent::` inside a trait method no longer produces "not found" warnings, including chain expressions like `static::where(...)->update(...)` and accesses inside closures or arrow functions nested within trait methods. Traits are incomplete by nature and expect the host class to provide these members.
+- **False-positive argument count errors on overloaded built-in functions.** Functions like `array_keys`, `mt_rand`, and `rand` accept multiple valid argument counts that phpstorm-stubs cannot express with a single declaration. An overload map derived from PHPStan's `functionMap.php` now provides the correct minimum argument count for 233 affected built-in functions.
 - **Type narrowing inside `return` statements.** `instanceof` checks in `&&` chains and ternary conditions now narrow the variable type when the expression is the operand of a `return` statement. Previously, `return $e instanceof QueryException && $e->errorInfo;` would flag `errorInfo` as unknown because narrowing only applied inside standalone expression statements and `if` conditions.
 - **CLI analyze performance (pathological files).** Single-file analysis of Eloquent-heavy services dropped from ~6 min to ~63 s (5.8× faster). The shared package (~2 500 files) dropped from 14 m 28 s to 1 m 25 s (10× faster, now ~30 % faster than PHPStan on the same machine). Key changes:
   - *Negative class cache.* `find_or_load_class` now caches "not found" results so repeated references to unknown types skip the four-phase lookup (fqn_index → classmap → PSR-4 → stubs). Invalidated when new classes are discovered.

docs/todo.md

@@ -102,7 +102,7 @@ unlikely to move the needle for most users.
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- |
 |     | **[Bugs](todo/bugs.md)**                                                                                                                                     |             |             |
 | B4  | [Variable reassignment loses type when parameter name is reused](todo/bugs.md#b4-variable-reassignment-loses-type-when-parameter-name-is-reused)             | Medium      | Medium      |
-| B7  | [Overloaded built-in function signatures in stubs](todo/bugs.md#b7-overloaded-built-in-function-signatures-in-stubs)                                         | Low         | Low         |
+| B8  | [Stub parser does not handle `#[PhpStormStubsElementAvailable]` attributes](todo/bugs.md#b8-stub-parser-does-not-handle-phpstormstubselementavailable-attributes) | Low         | Low         |
 |     | **[Completion](todo/completion.md)**                                                                                                                         |             |             |
 | C1  | Array functions needing new code paths                                                                                                                       | Medium     | High        |
 | C10 | [Lazy documentation via `completionItem/resolve`](todo/completion.md#c10-lazy-documentation-via-completionitemresolve)                                        | Medium     | Medium      |

docs/todo/bugs.md

@@ -38,37 +38,37 @@ within the same scope at the cursor offset.
 
 ---
 
-#### B7. Overloaded built-in function signatures not representable in stubs
+#### B8. Stub parser does not handle `#[PhpStormStubsElementAvailable]` attributes
 
 | | |
 |---|---|
 | **Impact** | Low |
 | **Effort** | Low |
 
-Some PHP built-in functions have genuinely overloaded signatures where
-the valid argument counts depend on which "form" is being called. The
-phpstorm-stubs format cannot express this: it declares a single
-signature, so one form's required parameters become false requirements
-for the other form.
-
-Around 415 cases where parameters were simply missing their default
-values have been fixed upstream in phpstorm-stubs. The remaining cases
-are true overloads that the stub format cannot represent:
-
-- `array_keys(array $array): array` vs
-  `array_keys(array $array, mixed $filter_value, bool $strict = false): array`
-- `mt_rand(): int` vs `mt_rand(int $min, int $max): int`
-
-PHPStan solves this with a separate function signature map
-(`functionMap.php`) that overrides stub signatures with corrected
-metadata including multiple accepted argument count ranges. PHPantom
-needs a similar mechanism.
-
-**Observed:** 10 diagnostics in `shared` (8 `array_keys`, 2 `mt_rand`).
-
-**Fix:** Maintain a small overload map (similar to PHPStan's
-`functionMap.php`) that declares alternative minimum argument counts
-for functions with true overloads. The argument count checker consults
-this map before flagging. The map only needs entries for functions
-where the stub's single signature cannot represent the valid call
-forms.
+The regex-based stub parser in `classmap_scanner.rs` does not strip
+`#[PhpStormStubsElementAvailable]` attributes from function signatures.
+When a stub uses this attribute to declare a parameter that only exists
+in certain PHP versions, the parser counts it as a separate required
+parameter alongside the variadic replacement, inflating the required
+argument count.
+
+For example, `array_push` is declared as:
+
+```
+function array_push(
+    array &$array,
+    #[PhpStormStubsElementAvailable(from: '5.3', to: '7.2')] $values,
+    mixed ...$values
+): int {}
+```
+
+The parser sees three parameters (`$array`, `$values`,
+`...$values`) and counts two as required, when the correct required
+count is one (`$array` only, since `...$values` is variadic).
+
+This affects roughly 230 stub functions. The argument count checker
+currently works around the issue with an overload map derived from
+PHPStan's `functionMap.php` (see `overload_min_args()` in
+`argument_count.rs`). The proper fix is to make the stub parser
+ignore parameters annotated with `#[PhpStormStubsElementAvailable]`
+when a variadic parameter of the same name follows.