Add iterable return type code action for PHPStan

Author: AJenbo

docs/CHANGELOG.md

@@ -40,13 +40,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Fix prefixed class name code action.** When PHPStan reports `class.prefixed` (a class name with a vendor prefix like `_PHPStan_`, `RectorPrefix`, or `_PhpScoper`), a quickfix replaces the prefixed name with the corrected one. The diagnostic is eagerly cleared after applying the fix.
 - **Remove always-true `assert()` code action.** When PHPStan reports `function.alreadyNarrowedType` for a call to `assert()` that will always evaluate to true, a quickfix offers to delete the no-op statement. Only `assert()` calls are matched — other functions sharing the same identifier (e.g. `is_string()` inside conditions) are excluded because removal would change control flow. The diagnostic is eagerly cleared once `assert(` no longer appears on the line.
 - **Fix void return mismatch code actions.** When PHPStan reports `return.void` (a void function returns an expression), a quickfix strips the expression to produce a bare `return;`. When PHPStan reports `return.empty` (a non-void function has a bare `return;`), a quickfix changes the native return type to `void` and removes any `@return` docblock tag. The two actions chain naturally: fixing `return.void` may trigger `return.empty`, which then fixes the signature.
+- **Add iterable return type code action.** When PHPStan reports `missingType.iterableValue` for a return type (e.g. "return type has no value type specified in iterable type array"), a quickfix adds a `@return` docblock tag with the element type inferred from the function body. For example, a function returning `$array = ['hello']` produces `@return array<string>` rather than `array<mixed>`. Falls back to `<mixed>` only when the element type cannot be determined. Existing docblocks are updated in place; single-line docblocks are expanded to multi-line. The diagnostic is eagerly cleared once the `@return` tag contains a generic type.
 - **Remove unreachable statement code action.** When PHPStan reports `deadCode.unreachable`, a quickfix deletes the dead statement. The statement-removal helper is shared infrastructure that a future native dead-code diagnostic (D6) can reuse.
 - **Eloquent `$appends` array.** Entries in a model's `$appends` property now produce virtual properties, matching the existing treatment of `$fillable`, `$guarded`, `$hidden`, and `$visible`.
 
 ### Changed
 
 - **`@phpstan-ignore` is never the preferred quickfix.** The "Ignore PHPStan error" code action now explicitly sets `is_preferred: false`. Previously it used `None`, which some editors treated as absent, causing the suppress-with-comment action to be applied on the keyboard shortcut (e.g. Ctrl+. then Enter) when no other quickfix set `is_preferred`.
 
+- **Generate PHPDoc infers `@return` from the function body.** Typing `/**` above a function that returns `array` now produces `@return list<string>` (or whatever the body actually returns) instead of the previous `@return array<mixed>`. The same return-statement scanning used by the `missingType.return` and `missingType.iterableValue` code actions is now shared with docblock generation.
+
 - **Faster startup.** Stub loading during initialization is significantly faster.
 - **More accurate type operations.** Type substitution during generic resolution (e.g. `Collection<int, User>` inheriting from `Collection<TKey, TValue>`) now operates on the structured type tree instead of string manipulation, improving correctness for complex nested types.
 - **Faster type resolution.** The central type resolution pipeline now operates on structured types directly instead of converting to strings and re-parsing at each step. Union and intersection members, array shape lookups, and generic argument extraction all avoid redundant parsing.

docs/todo.md

@@ -21,12 +21,11 @@ within the same impact tier.
 
 ## Sprint 4 — Refactoring toolkit & type inference
 
-| #   | Item                                                                                                                                                                       | Impact | Effort |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ |
-| H17 | [`missingType.iterableValue` — add `@return` with inferred element type](todo/phpstan-actions.md#h17-missingtype-iterablevalue-return-type--add-return-with-iterable-type) | Medium | High   |
-| 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**                                                                                                                                                          |        |        |
+| #   | Item                                                                                                                                             | Impact | Effort |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------ |
+| 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**                                                                                                                                |        |        |
 
 ## Sprint 5 — Polish for office adoption
 
@@ -122,7 +121,6 @@ unlikely to move the needle for most users.
 | H13  | `property.notFound` — declare missing property (same-class)                                                                                                                 | Medium      | Medium         |
 | H15  | Template bound from tip — add `@template T of X`                                                                                                                            | Medium      | Medium         |
 | H16  | `match.unhandled` — add missing match arms                                                                                                                                  | Medium      | Medium         |
-| H17  | `missingType.iterableValue` — add `@return` with inferred element type                                                                                                      | Medium      | High           |
 | H19  | `property.unused` / `method.unused` — remove unused member                                                                                                                  | Low         | Low            |
 | H20  | `generics.callSiteVarianceRedundant` — remove redundant variance annotation                                                                                                 | Low         | Low            |
 | H23  | `instanceof.alwaysTrue` — remove redundant instanceof check                                                                                                                 | Low         | Low            |

docs/todo/phpstan-actions.md

@@ -11,13 +11,7 @@ No outstanding items.
 
 ---
 
-## Tier 1 — Trivial (no message parsing or simple static message)
-
-No outstanding items.
-
----
-
-## Tier 2 — Simple message parsing
+## Tier 1 — Simple message parsing
 
 ### H6. `return.type` — Update return type to match actual returns
 
@@ -117,7 +111,7 @@ and the diagnostic line.
 
 ---
 
-## Tier 3 — Requires locating related code
+## Tier 2 — Requires locating related code
 
 ### H13. `property.notFound` (same-class) — Declare missing property
 
@@ -186,41 +180,7 @@ a `TODO` comment — configurable later.
 
 ---
 
-## Tier 4 — Requires body analysis
-
-### H17. `missingType.iterableValue` (return type) — Add `@return` with iterable type
-
-**Identifier:** `missingType.iterableValue`
-**Messages:**
-- `Method Foo::bar() return type has no value type specified in iterable type array.`
-- `Function foo() return type has no value type specified in iterable type array.`
-
-Only handle the "return type" variant (not parameter/property). Parse the
-iterable type name (`array`, `iterable`, `Traversable`, etc.) from the message.
-
-**Simplest approach (start here):**
-
-Offer to add `@return array<mixed>` (or `list<mixed>`, `iterable<mixed>`, etc.
-matching the native type). This silences the PHPStan error while being explicit.
-PHPStan's documentation recommends this as the quick fix:
-> "If you just want to make this error go away, replace array with mixed[]
-> or array<mixed>."
-
-**Enhanced approach (later):**
-
-Walk the function body for `return` statements and infer element types from
-array literals using the existing `infer_element_type` /
-`infer_array_literal_raw_type` logic. If all return expressions are array
-literals with consistent value types, offer `@return array<ValueType>`.
-
-**Stale detection:** a `@return` tag exists with a generic array type
-(contains `<` or `[]`).
-
-**Reference:** https://phpstan.org/blog/solving-phpstan-no-value-type-specified-in-iterable-type
-
----
-
-## Tier 5 — Unique to PHPantom
+## Tier 3 — Unique to PHPantom
 
 ### H20. `generics.callSiteVarianceRedundant` — Remove redundant variance annotation
 
@@ -350,4 +310,4 @@ have class hierarchy information available through `inheritance.rs`.
 **Comment preservation.** When a code action inserts or removes lines near
 existing comments or docblocks, take care not to orphan or lose them. Rector's
 control-flow simplification rules merge comments from removed nodes onto the
-first statement of the replacement.
+first statement of the replacement.

src/code_actions/extract_function.rs

@@ -1554,14 +1554,14 @@ fn build_call_site(info: &ExtractionInfo, call_indent: &str) -> String {
             // Extracted function returns null on fall-through, or the
             // actual value on early exit.
             // Call site:
-            //   $__early = extracted(…);
-            //   if ($__early !== null) return $__early;
+            //   $result = extracted(…);
+            //   if ($result !== null) return $result;
             out.push_str(call_indent);
-            out.push_str("$__early = ");
+            out.push_str("$result = ");
             out.push_str(&call_expr);
             out.push_str(";\n");
             out.push_str(call_indent);
-            out.push_str("if ($__early !== null) return $__early;\n");
+            out.push_str("if ($result !== null) return $result;\n");
         }
         ReturnStrategy::NullGuardWithValue(void_guards) => {
             // Guards return null (or were void), the function also
@@ -1804,8 +1804,8 @@ enum ReturnStrategy {
     /// sentinel for "no early exit."  The extracted function returns
     /// `?<type>` and the call site is:
     /// ```php
-    /// $__early = extracted(…);
-    /// if ($__early !== null) return $__early;
+    /// $result = extracted(…);
+    /// if ($result !== null) return $result;
     /// ```
     SentinelNull,
     /// All guard returns are `null` (or bare `return;`) and the
@@ -3811,7 +3811,7 @@ mod tests {
         let result = build_call_site(&info, "        ");
         assert_eq!(
             result,
-            "        $__early = $this->extracted($x);\n        if ($__early !== null) return $__early;\n"
+            "        $result = $this->extracted($x);\n        if ($result !== null) return $result;\n"
         );
     }
 

src/code_actions/mod.rs

@@ -282,6 +282,8 @@ impl Backend {
             | "phpstan.fixReturnType.changeTypeToActual"
             | "phpstan.fixReturnType.changeType"
             | "phpstan.fixReturnType.addType" => self.resolve_fix_return_type(&data, &content),
+            // ── Add iterable return type ────────────────────────────
+            "phpstan.addIterableType" => self.resolve_add_iterable_type(&data, &content),
             // ── Remove unreachable statement ────────────────────────
             "phpstan.removeUnreachable" => self.resolve_remove_unreachable(&data, &content),
             // ── Change visibility (parent-aware) ────────────────────