Spread Operator Type Tracking

Author: AJenbo

example.php

@@ -478,6 +478,44 @@ function unionDemo(string|int $value, ?User $maybe): User|null { return $maybe;
 $fromClosure->getEmail();                 // $result = $fn() resolves return type
 
 
+// ── Spread Operator Type Tracking ───────────────────────────────────────────
+// When array literals contain spread expressions (`...$var`), element types
+// are resolved from the spread variable's iterable annotation and merged.
+
+/** @var list<User> $users */
+$users = [];
+/** @var list<AdminUser> $admins */
+$admins = [];
+
+// Single spread — preserves element type:
+$allUsers = [...$users];
+$allUsers[0]->getEmail();                 // resolves User from list<User>
+
+// Multiple spreads — union of element types:
+$everyone = [...$users, ...$admins];
+$everyone[0]->getEmail();                 // resolves User|AdminUser
+
+// Works with array<K,V> and Type[] annotations too:
+/** @var array<int, User> $indexed */
+$indexed = [];
+$copy = [...$indexed];
+$copy[0]->getName();                      // resolves User from array<int, User>
+
+/** @var User[] $typed */
+$typed = [];
+$merged = [...$typed];
+$merged[0]->getEmail();                   // resolves User from User[]
+
+// Spread combined with push-style assignments:
+$mixed = [...$users];
+$mixed[] = new AdminUser('root', 'root@example.com');
+$mixed[0]->getName();                     // resolves User|AdminUser
+
+// Works with array() syntax too:
+$legacy = array(...$users, ...$admins);
+$legacy[0]->getEmail();                   // resolves User|AdminUser
+
+
 // ── Multi-line @return & Broken Docblock Recovery ───────────────────────────
 
 $collection = collect([]);

src/completion/array_shape.rs

@@ -581,13 +581,41 @@ impl Backend {
         // and push-style `$var[] = expr;` assignments.
         let base_entries = parse_array_literal_entries(rhs_text);
 
+        // Extract spread element types from the array literal (e.g.
+        // `[...$users, ...$admins]` → resolve each spread variable's
+        // iterable element type).
+        let spread_types = extract_spread_expressions(rhs_text)
+            .unwrap_or_default()
+            .iter()
+            .filter_map(|expr| {
+                // Only resolve bare variable expressions for now.
+                if !expr.starts_with('$') {
+                    return None;
+                }
+                let raw = self.resolve_variable_raw_type(
+                    expr,
+                    content,
+                    cursor_offset,
+                    classes,
+                    file_use_map,
+                    file_namespace,
+                )?;
+                docblock::extract_iterable_element_type(&raw)
+            })
+            .collect::<Vec<_>>();
+
         // Scan for incremental `$var['key'] = expr;` assignments.
         let after_assign = assign_pos + assign_pattern.len() + semi_pos + 1; // past the `;`
         let incremental =
             collect_incremental_key_assignments(var_name, content, after_assign, cursor_offset);
 
         // Scan for push-style `$var[] = expr;` assignments.
-        let push_types = collect_push_assignments(var_name, content, after_assign, cursor_offset);
+        let mut push_types =
+            collect_push_assignments(var_name, content, after_assign, cursor_offset);
+
+        // Merge spread element types into push types so they participate
+        // in the `list<…>` inference.
+        push_types.extend(spread_types);
 
         if base_entries.is_some() || !incremental.is_empty() || !push_types.is_empty() {
             let mut entries: Vec<(String, String)> = base_entries.unwrap_or_default();
@@ -1027,6 +1055,52 @@ pub(super) fn parse_array_literal_entries(rhs: &str) -> Option<Vec<(String, Stri
     Some(entries)
 }
 
+/// Extract spread expressions from an array literal.
+///
+/// Given an array literal like `[...$users, 'key' => 'val', ...$admins]`,
+/// this returns `Some(vec!["$users", "$admins"])`.
+///
+/// Only elements that start with `...` are collected.  Keyed entries and
+/// non-spread positional entries are ignored.
+///
+/// Returns `None` if `rhs` is not an array literal, or `Some(vec![])` if
+/// it is an array literal but contains no spread elements.
+pub fn extract_spread_expressions(rhs: &str) -> Option<Vec<String>> {
+    let inner = if rhs.starts_with('[') && rhs.ends_with(']') {
+        &rhs[1..rhs.len() - 1]
+    } else {
+        let lower = rhs.to_ascii_lowercase();
+        if lower.starts_with("array(") && rhs.ends_with(')') {
+            &rhs[6..rhs.len() - 1]
+        } else {
+            return None;
+        }
+    };
+
+    let inner = inner.trim();
+    if inner.is_empty() {
+        return Some(vec![]);
+    }
+
+    let parts = split_array_literal_elements(inner);
+    let mut spreads = Vec::new();
+
+    for part in &parts {
+        let part = part.trim();
+        if part.is_empty() {
+            continue;
+        }
+        if let Some(expr) = part.strip_prefix("...") {
+            let expr = expr.trim();
+            if !expr.is_empty() {
+                spreads.push(expr.to_string());
+            }
+        }
+    }
+
+    Some(spreads)
+}
+
 /// Split array literal elements on commas at depth 0, respecting
 /// `(…)`, `[…]`, `{…}`, `<…>` nesting and quoted strings.
 fn split_array_literal_elements(s: &str) -> Vec<&str> {

src/completion/mod.rs

@@ -22,7 +22,7 @@
 /// Class inheritance merging (traits, mixins, parent chain) lives in the
 /// top-level [`crate::inheritance`] module since it is shared infrastructure
 /// used by completion, definition, and future features (hover, references).
-pub(crate) mod array_shape;
+pub mod array_shape;
 pub mod builder;
 pub(crate) mod catch_completion;
 pub mod class_completion;

src/completion/resolver.rs

@@ -431,6 +431,34 @@ impl Backend {
         // and push-style `$var[] = expr;` assignments.
         let base_entries = super::array_shape::parse_array_literal_entries(rhs_text);
 
+        // Extract spread element types from the array literal (e.g.
+        // `[...$users, ...$admins]` → resolve each spread variable's
+        // iterable element type via docblock annotation).
+        let spread_types = super::array_shape::extract_spread_expressions(rhs_text)
+            .unwrap_or_default()
+            .iter()
+            .filter_map(|expr| {
+                if !expr.starts_with('$') {
+                    return None;
+                }
+                // Try docblock annotation first (@var / @param).
+                let raw =
+                    crate::docblock::find_iterable_raw_type_in_source(content, cursor_offset, expr)
+                        .or_else(|| {
+                            // Fall back to resolving through assignment.
+                            Self::extract_raw_type_from_assignment_text(
+                                expr,
+                                content,
+                                cursor_offset,
+                                current_class,
+                                all_classes,
+                                class_loader,
+                            )
+                        })?;
+                crate::docblock::extract_iterable_element_type(&raw)
+            })
+            .collect::<Vec<_>>();
+
         let after_assign = rhs_start + semi_pos + 1; // past the `;`
         let incremental = super::array_shape::collect_incremental_key_assignments(
             base_var,
@@ -440,13 +468,17 @@ impl Backend {
         );
 
         // Scan for push-style `$var[] = expr;` assignments.
-        let push_types = super::array_shape::collect_push_assignments(
+        let mut push_types = super::array_shape::collect_push_assignments(
             base_var,
             content,
             after_assign,
             cursor_offset,
         );
 
+        // Merge spread element types into push types so they participate
+        // in the `list<…>` inference.
+        push_types.extend(spread_types);
+
         if base_entries.is_some() || !incremental.is_empty() || !push_types.is_empty() {
             let mut entries: Vec<(String, String)> = base_entries.unwrap_or_default();
             // Merge incremental assignments — later assignments for the

src/docblock/mod.rs

@@ -50,6 +50,7 @@ pub use conditional::extract_conditional_return_type;
 // Type utilities
 pub use types::{
     base_class_name, clean_type, extract_array_shape_value_type, extract_callable_return_type,
-    extract_generic_key_type, extract_generic_value_type, extract_object_shape_property_type,
-    is_object_shape, parse_array_shape, parse_object_shape, split_intersection_depth0,
+    extract_generic_key_type, extract_generic_value_type, extract_iterable_element_type,
+    extract_object_shape_property_type, is_object_shape, parse_array_shape, parse_object_shape,
+    split_intersection_depth0,
 };

src/docblock/types.rs

@@ -486,6 +486,55 @@ pub fn extract_generic_value_type(raw_type: &str) -> Option<String> {
     Some(cleaned)
 }
 
+/// Extract the element (value) type from an iterable type annotation,
+/// including scalar element types.
+///
+/// Unlike [`extract_generic_value_type`], which skips scalar element types
+/// (because it is used for class-based completion), this function returns
+/// the raw element type string regardless of whether it is a class or a
+/// scalar.  This is needed for spread operator tracking where we merge
+/// element types into a union and the final `list<…>` type is resolved
+/// later.
+///
+/// # Supported patterns
+///
+/// - `User[]`                → `Some("User")`
+/// - `int[]`                 → `Some("int")`
+/// - `list<User>`            → `Some("User")`
+/// - `array<int, User>`      → `Some("User")`
+/// - `iterable<string>`      → `Some("string")`
+/// - `Collection<int, User>` → `Some("User")`
+/// - `?list<User>`           → `Some("User")`
+/// - `\list<User>`           → `Some("User")`
+/// - `string`                → `None` (not iterable)
+/// - `Closure(): User`       → `None` (not iterable)
+pub fn extract_iterable_element_type(raw_type: &str) -> Option<String> {
+    let s = raw_type.strip_prefix('\\').unwrap_or(raw_type);
+    let s = s.strip_prefix('?').unwrap_or(s);
+
+    // Handle `Type[]` shorthand → element type is everything before `[]`.
+    if let Some(base) = s.strip_suffix("[]") {
+        let trimmed = base.trim();
+        if !trimmed.is_empty() {
+            return Some(trimmed.to_string());
+        }
+        return None;
+    }
+
+    // Handle `GenericType<…>` — extract the last generic parameter.
+    let angle_pos = s.find('<')?;
+    let inner = s.get(angle_pos + 1..)?.strip_suffix('>')?.trim();
+    if inner.is_empty() {
+        return None;
+    }
+
+    let last = split_last_generic_param(inner).trim();
+    if last.is_empty() {
+        return None;
+    }
+    Some(last.to_string())
+}
+
 /// Extract the key type from a generic iterable type annotation.
 ///
 /// Handles the most common PHPDoc generic iterable patterns: