Implement "Remove unused return type" code action for PHPStan, and

update general docs

Author: AJenbo

docs/CHANGELOG.md

@@ -14,16 +14,15 @@ editor, so results are consistent.
 | `phpantom_lsp init`      | Generate a default `.phpantom.toml` config file      |
 
 Running with no subcommand starts the language server. Editors launch
-this automatically; you never need to run it by hand.
+this automatically.
 
 ---
 
-## `analyze` — Batch diagnostics
+## `analyze`
 
-Scans PHP files and reports PHPantom's own diagnostics (no PHPStan, no
-external tools) in a PHPStan-style table format. Use it to find spots
-where the LSP cannot resolve a symbol, so you can achieve full
-completion coverage.
+Scans PHP files and reports PHPantom diagnostics in a PHPStan-style
+table format. Use it to find spots where the LSP cannot resolve a
+symbol, so you can achieve full completion coverage.
 
 ```sh
 phpantom_lsp analyze                             # scan entire project
@@ -83,11 +82,10 @@ Each has a rule identifier shown below the message.
 
 ---
 
-## `fix` — Automated code fixes
+## `fix`
 
-Applies code fixes across the project, modeled after
-[php-cs-fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer). Specify
-which rules to run, or omit `--rule` to run all preferred native fixers.
+Applies code fixes across the project. Specify which rules to run, or
+omit `--rule` to run all preferred native fixers.
 
 ```sh
 phpantom_lsp fix                                  # apply all preferred fixers
@@ -106,7 +104,7 @@ phpantom_lsp fix --project-root /path/to/app      # explicit project root
 | `[PATH]`                   | File or directory to fix. Defaults to the entire project.            |
 | `--rule <RULE>`            | Rule to apply (repeatable). Omit to run all preferred native rules.  |
 | `--dry-run`                | Report what would change without writing files.                      |
-| `--with-phpstan`           | Enable PHPStan-based fixers (runs PHPStan to collect diagnostics).   |
+| `--with-phpstan`           | Enable PHPStan-based fixers (future feature).                        |
 | `--project-root <DIR>`     | Project root directory. Defaults to the current working directory.    |
 | `--no-colour`              | Disable ANSI colour output.                                         |
 
@@ -120,28 +118,11 @@ phpantom_lsp fix --project-root /path/to/app      # explicit project root
 
 ### Available rules
 
-Rules correspond to diagnostic identifiers. Native rules run without
-external tools. PHPStan rules require `--with-phpstan` and are prefixed
-with `phpstan.`.
+Rules correspond to diagnostic identifiers.
 
-**Native rules (shipped):**
-
-| Rule               | Description                                               |
-| ------------------ | --------------------------------------------------------- |
-| `unused_import`    | Remove unused `use` statements. Handles simple imports, group imports (removes individual members), and collapses leftover blank lines. |
-
-**PHPStan rules (planned, requires `--with-phpstan`):**
-
-These are not yet implemented. See the [fix CLI roadmap](todo/fix-cli.md)
-for details.
-
-| Rule                                         | Description                                         |
-| -------------------------------------------- | --------------------------------------------------- |
-| `phpstan.return.unusedType`                   | Remove unused type from a return union              |
-| `phpstan.missingType.iterableValue`           | Add `@return array<mixed>` for untyped iterables    |
-| `phpstan.property.unused`                     | Remove unused property declarations                 |
-| `phpstan.method.unused`                       | Remove unused method declarations                   |
-| `phpstan.generics.callSiteVarianceRedundant`  | Remove redundant variance annotations in docblocks  |
+| Rule               | Description                    |
+| ------------------ | ------------------------------ |
+| `unused_import`    | Remove unused `use` statements |
 
 ### Example output
 
@@ -179,7 +160,7 @@ Use `--dry-run` in CI to enforce that imports stay clean:
 
 ```sh
 phpantom_lsp fix --dry-run --rule unused_import --project-root .
-# Exit code 2 means fixable issues exist → fail the build.
+# Exit code 2 means fixable issues exist. Fail the build.
 ```
 
 ### Idempotency
@@ -190,7 +171,7 @@ writes nothing.
 
 ---
 
-## `init` — Generate config file
+## `init`
 
 Creates a default `.phpantom.toml` in the current directory with all
 options documented and commented out. Safe to run if the file already

docs/CLI.md

@@ -150,7 +150,7 @@ PHPantom supports an optional per-project configuration file for settings like P
 To generate a default config file with all options documented and commented out:
 
 ```bash
-phpantom_lsp --init
+phpantom_lsp init
 ```
 
 This creates a `.phpantom.toml` in the current directory. Currently supported settings:

docs/SETUP.md

@@ -23,8 +23,6 @@ within the same impact tier.
 
 | #   | 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

docs/todo.md

@@ -13,74 +13,6 @@ No outstanding items.
 
 ## Tier 1 — Simple message parsing
 
-### H6. `return.type` — Update return type to match actual returns
-
-**Identifier:** `return.type`
-**Messages:**
-- `Method Foo::bar() should return {expected} but returns {actual}.`
-- `Function foo() should return {expected} but returns {actual}.`
-- `Anonymous function should return {expected} but returns {actual}.`
-
-Parse `{actual}` from the message with regex:
-`should return (.+) but returns (.+)\.$`
-
-Offer two quickfixes:
-
-1. **Update native return type** — find the `: Type` after the parameter list
-   and replace `Type` with the actual type. Only offer this when the actual
-   type is a valid native PHP type (scalars, class names, `null`, simple
-   unions on PHP 8.0+, intersection types on PHP 8.1+).
-2. **Update `@return` tag** — if a docblock with `@return` exists, replace the
-   type. If no docblock exists, create one with `@return {actual}`.
-
-Mark neither as `is_preferred` since the right fix might be to change the code
-rather than the signature.
-
-**Inheritance guard:** Before offering the native return type quickfix, check
-whether the method overrides a parent class or interface method. Changing the
-return type could violate LSP (Liskov Substitution Principle) if the parent
-declares a wider type. Rector's `ClassMethodReturnTypeOverrideGuard` enforces
-this same constraint. When the method overrides a parent, only offer the
-docblock quickfix (docblock types don't affect runtime covariance checks).
-
-**All-paths completeness:** When the `{actual}` type is inferred from return
-statements, verify that all return paths yield a consistent type. If some
-paths return a value and others fall through without returning, the actual
-type should include `void` or `null`. Rector's return type rules universally
-bail out when return paths are ambiguous rather than risk an incorrect
-declaration.
-
-**Stale detection:** difficult to do precisely because PHPStan's type syntax
-differs from source syntax. As a heuristic, check whether the return type
-declaration or `@return` tag was modified since the diagnostic was issued
-(i.e. the text on the relevant line no longer matches the `{expected}` type).
-Or skip stale detection for this one — the `@phpstan-ignore` stale check
-already covers the suppress-with-comment path.
-
----
-
-### H10. `return.unusedType` — Remove unused type from return union
-
-**Identifier:** `return.unusedType`
-**Messages:**
-- `Method Foo::bar() never returns {type} so it can be removed from the return type.`
-- `Function foo() never returns {type} so it can be removed from the return type.`
-
-Parse `{type}` from the message. Find the return type (native or `@return`),
-parse the union/intersection, remove the unused member, and rewrite.
-
-For native types: `string|null` with unused `null` becomes `string`.
-For docblock types: same logic on the `@return` tag.
-Handle intersection types too: `Foo&Bar` with unused `Bar` becomes `Foo`.
-
-If removing the type would leave a single-member union, simplify
-(e.g. `string|null` minus `null` becomes `string`).
-
-**Stale detection:** the return type no longer contains `{type}` as a union
-or intersection member.
-
----
-
 ### H4. `assign.byRefForeachExpr` — Unset by-reference foreach variable
 
 **Identifier:** `assign.byRefForeachExpr`

docs/todo/phpstan-actions.md

@@ -281,7 +281,14 @@ impl Backend {
             "phpstan.fixReturnType.stripExpr"
             | "phpstan.fixReturnType.changeTypeToActual"
             | "phpstan.fixReturnType.changeType"
-            | "phpstan.fixReturnType.addType" => self.resolve_fix_return_type(&data, &content),
+            | "phpstan.fixReturnType.addType"
+            | "phpstan.fixReturnType.updateReturnType" => {
+                self.resolve_fix_return_type(&data, &content)
+            }
+            // ── Remove unused return type ────────────────────────────
+            "phpstan.removeUnusedReturnType" => {
+                self.resolve_remove_unused_return_type(&data, &content)
+            }
             // ── Add iterable return type ────────────────────────────
             "phpstan.addIterableType" => self.resolve_add_iterable_type(&data, &content),
             // ── Remove unreachable statement ────────────────────────