Migrate to the new Mago packages

Author: AJenbo

Cargo.lock

@@ -21,10 +21,9 @@ tokio = { version = "1.39", features = ["full"] }
 mago-syntax = "=1.45.0"
 mago-allocator = "=1.45.0"
 mago-database = "=1.45.0"
-mago-docblock = "=1.42.0"
 mago-names = "=1.45.0"
+mago-phpdoc-syntax = "=1.45.0"
 mago-span = "=1.45.0"
-mago-type-syntax = "=1.42.0"
 mago-formatter = { version = "=1.45.0", features = ["serde"] }
 mago-php-version = "=1.45.0"
 mago-composer = "=1.45.0"

Cargo.toml

@@ -142,18 +142,25 @@ every consumer benefits.
 
 ## External Crates
 
-PHPantom uses three crates from the [Mago](https://github.com/carthage-software/mago)
+PHPantom uses several crates from the [Mago](https://github.com/carthage-software/mago)
 project for PHP parsing and type representation:
 
-| Crate              | Purpose                                                |
-| ------------------ | ------------------------------------------------------ |
-| `mago-docblock`    | Structured PHPDoc parsing (replaces manual scanning)   |
-| `mago-names`       | Use-statement and namespace resolution                 |
-| `mago-type-syntax` | PHPStan/Psalm type expression parsing into `PhpType`   |
+| Crate                 | Purpose                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `mago-names`          | Use-statement and namespace resolution                     |
+| `mago-phpdoc-syntax`  | PHPDoc parsing, including the PHPStan/Psalm type mini-language |
+| `mago-syntax`         | PHP source to CST                                          |
+
+`mago-phpdoc-syntax` parses a docblock comment and the type expressions
+embedded in its tags in one pass. `src/docblock/parser.rs` adapts its CST
+to the owned `DocblockInfo` / `TagInfo` pair the rest of the codebase
+works with, reducing each tag to a vendor-agnostic `TagKind`
+(`src/docblock/tag_kind.rs`), the vendor prefix it was written with, and
+the raw source text of its value.
 
 `PhpType` (`src/php_type/`) is a pointer-sized handle to an interned
 `TypeKind` node, itself built from the borrowed
-`mago_type_syntax::cst::Type` AST. Every type-carrying field in the
+`mago_phpdoc_syntax::cst::type::Type` AST. Every type-carrying field in the
 data model (`type_hint`, `return_type`, `native_type_hint`,
 `native_return_type`, `asserted_type`, `template_param_bounds` values,
 generics type arguments, `ResolvedType::type_string`) uses `PhpType`.

docs/ARCHITECTURE.md

@@ -31,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Laravel `Macroable::mixin()` registrations are recognized.** A `Str::mixin(new StrMixin())` or `Collection::mixin(CollectionMixin::class)` call in a service provider now contributes one macro per public/protected method of the mixin class, taking the signature of the closure that method returns, so those methods autocomplete, hover, resolve, and type-check on the target class just like a `Target::macro(...)` registration. Mixins registered through a facade also attach to the facade's concrete container-bound class, and go-to-definition on a mixed-in method jumps to the mixin method's own declaration. Editing the mixin class (for example adding a helper method) refreshes the recognized macros. Contributed by @shuvroroy (#256).
 - **Carbon trait-based `mixin()` registrations are recognized.** Carbon's `mixin()` supports traits in addition to classes (since Carbon 2.23.0), where the trait's public methods become methods on the target directly rather than acting as closure factories. `CarbonImmutable::mixin(MyTrait::class)` now synthesizes one macro per qualifying trait method using only the trait method's own signature, and Carbon `macro()` calls (e.g. `CarbonImmutable::macro('name', fn () => ...)`) also resolve through the same pipeline as Laravel's `Macroable`. Contributed by @calebdw.
 - **`@phpstan-require-implements` contributes to trait `$this` resolution.** Traits annotated with `@phpstan-require-implements InterfaceName` now resolve `$this` against the required interface inside trait methods, matching the existing `@phpstan-require-extends` behavior for required base classes. This makes required interface methods available in completion, hover, and member resolution while editing the trait itself. Contributed by @calebdw.
-- **Larastan `model-property<Model>` type validation and completion.** The `model-property<Model>` pseudo-type is now resolved against the model's known properties during argument type checking. String literals that do not match a declared or virtual property are flagged as type mismatches, while non-literal strings are accepted conservatively. Typing inside a string argument whose parameter is typed as `model-property<Model>` now offers completion of the model's property names. The type parser now also handles hyphenated generic pseudo-types that `mago_type_syntax` does not recognise natively. Contributed by @calebdw.
+- **Larastan `model-property<Model>` type validation and completion.** The `model-property<Model>` pseudo-type is now resolved against the model's known properties during argument type checking. String literals that do not match a declared or virtual property are flagged as type mismatches, while non-literal strings are accepted conservatively. Typing inside a string argument whose parameter is typed as `model-property<Model>` now offers completion of the model's property names. The type parser now also handles hyphenated generic pseudo-types that the PHPDoc type grammar does not recognise natively. Contributed by @calebdw.
 - **Workspace-wide diagnostics.** PHPantom now surfaces problems across the whole project, not just the files you have open. After startup and the full background index finish, diagnostics run in the background over every file and stream into the editor's problems panel as they're found, so issues in files you haven't opened yet are already visible when you navigate to them. Configured tools (PHPStan, PHPCS, Mago) also run once over the whole project afterwards, when the project has its own configuration file for that tool. Both passes are deliberately deferred until after startup so they never slow down the time it takes for the editor to become usable. Disable with `[diagnostics] workspace = false` (native pass) or `workspace-external = false` (external tools) in `.phpantom.toml`.
 
 ### Changed
@@ -44,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Continuous progress reporting.** The indexing progress bar now advances file by file with live counts (e.g. "Scanning vendor packages (3201/8544 files)") instead of jumping between a few fixed milestones. This covers single-project, monorepo, and non-Composer workspaces. Go to Implementation, Find References, and Type Hierarchy show the same live progress while they scan, including when one of them triggers the first full workspace index.
 - **Property hover now shows effective types as a `var` detail line.** Property hovers now mirror method hovers by displaying the resolved/effective property type above the PHP snippet as `**var**`, while the snippet itself shows only the native PHP property declaration. This keeps docblock-inferred, virtual, and schema-derived property types out of the generated signature block. Contributed by @calebdw.
 - **Updated the bundled mago toolchain to 1.43.0.** The parser, docblock parser, formatter, and supporting crates are refreshed to the latest upstream release. Contributed by @enwi in https://github.com/PHPantom-dev/phpantom_lsp/pull/234.
+- **PHPDoc comments and the types inside them are now parsed by one unified parser.** Docblock parsing moves to `mago-phpdoc-syntax`, replacing the two frozen crates PHPantom used before. Tags written with a `@psalm-` or `@phpstan-` prefix are now recognized as the same tag as their unprefixed form throughout, so a vendor-prefixed variant reliably takes precedence over the plain one, and spellings such as `@phpstan-extends`, `@phpstan-sealed` and `@template-extends` are understood in every place the plain spelling was. Variance annotations (`covariant`, `contravariant`) in generic arguments are parsed directly rather than stripped beforehand, which makes docblock go-to-definition and rename land on the right text in types that use them. A tag indented with more than one space after the `*` is no longer dropped, and a docblock you are still typing (a bare `@`, a half-written type, no closing `*/`) now yields the tags above the cursor instead of nothing, so `@param`, `@return` and `@throws` completion keeps working mid-edit.
 - **Lower memory use in the cross-file reference index.** The index backing Find References and the reference-count inlay hints now keeps only the distinct files and counts each symbol actually needs, instead of one entry per matching location plus never-read position data. On large projects this removes millions of short-lived allocations and shrinks the index to a fraction of its previous size, with no change to Find References or inlay hint results.
 - **Lower memory use for method lookups.** Each resolved class's method name index is now a sorted list searched with binary search instead of a hash map, using about a third of the memory for the same lookup speed. On large Laravel projects, where the resolved-class cache holds thousands of these indexes, this measurably shrinks total memory use.
 - **Lower memory use for member access spans.** The subject text recorded for every `->`/`::` access (e.g. `$this` in `$this->save()`) no longer allocates a string when it is a plain slice of the source, which covers the vast majority of accesses in typical PHP code. It now reuses the file's own bytes instead, with an allocation only for the rarer cases (chained calls, `new` expressions) where the recorded text differs from the source.

docs/CHANGELOG.md

@@ -107,7 +107,8 @@ unlikely to move the needle for most users.
 | D3  | [Deprecated rendering — chain subject resolution](todo/diagnostics.md#d3-deprecated-rendering-chain-subject-resolution)                                                    | Low-Medium  | Medium      |
 | D5  | [External tool diagnostic suppression actions](todo/diagnostics.md#d5-external-tool-diagnostic-suppression-actions)                                                         | Low         | Low         |
 | D15 | [Unused parameter diagnostic](todo/diagnostics.md#d15-unused-parameter-diagnostic)                                                                                          | Low         | Low         |
-|     | **[Bug Fixes](todo/bugs.md)** (no outstanding items)                                                                                                                        |             |             |
+|     | **[Bug Fixes](todo/bugs.md)**                                                                                                                                               |             |             |
+| B1  | [`static`/`$this` return types rejected where a `Stringable` object is accepted](todo/bugs.md#b1-staticthis-return-types-are-rejected-where-a-stringable-object-is-accepted) | Medium      | Low         |
 |     | **[Code Actions](todo/actions.md)**                                                                                                                                         |             |             |
 | A40 | [Generate method from call](todo/actions.md#a40-generate-method-from-call)                                                                                                  | Medium-High | Medium      |
 | A41 | [Create class from non-existing name](todo/actions.md#a41-create-class-from-non-existing-name)                                                                              | Medium      | Medium      |
@@ -195,8 +196,8 @@ unlikely to move the needle for most users.
 | E6  | Stub install prompt for non-Composer projects                                                                                                                               | Low         | Low         |
 | E7  | [Stub-based framework patches](todo/external-stubs.md#e7-stub-based-framework-patches)                                                                                      | Medium      | Medium      |
 |     | **[Performance](todo/performance.md)**                                                                                       |             |             |
-| P29 | [Migrate to `mago-phpdoc-syntax`](todo/performance.md#p29-migrate-to-mago-phpdoc-syntax) (drop deprecated `mago-docblock` / `mago-type-syntax`; sequenced behind P30)         | Medium      | High        |
-| P30 | [Evaluate migrating parse/resolve/docblock pipeline to `mago-hir`](todo/performance.md#p30-evaluate-migrating-parseresolvedocblock-pipeline-to-mago-hir) (blocked on upstream API stabilizing — see triggers) | Medium-High | High        |
+| P44 | [Consume the PHPDoc CST directly instead of re-parsing tag text](todo/performance.md#p44-consume-the-phpdoc-cst-directly-instead-of-re-parsing-tag-text)                     | Medium      | High        |
+| P30 | [Evaluate migrating parse/resolve/docblock pipeline to `mago-hir`](todo/performance.md#p30-evaluate-migrating-parseresolvedocblock-pipeline-to-mago-hir) (parked — re-evaluated at mago 1.45.0, still no `mago-hir` consumers upstream) | Medium-High | High        |
 | P43 | [`init_single_project` is the longest single-threaded stretch of a run](todo/performance.md#p43-init_single_project-is-the-longest-single-threaded-stretch-of-a-run)        | Medium-High | Medium      |
 | P16 | [Pre-parsed stub format (eliminate raw PHP embedding)](todo/performance.md#p16-pre-parsed-stub-format-eliminate-raw-php-embedding)                                          | High        | Medium-High |
 | P25 | [`type_mismatch_argument` / `argument_count_mismatch` slow on large single files](todo/performance.md#p25-type_mismatch_argument-argument_count_mismatch-slow-on-large-single-files) | Medium      | Medium      |

docs/todo.md

@@ -7,4 +7,37 @@ pipeline so it produces correct data. Downstream consumers
 (diagnostics, hover, completion, definition) should never need
 to second-guess upstream output.
 
-No outstanding items.
+## B1. `static`/`$this` return types are rejected where a `Stringable` object is accepted
+
+**Impact: Medium · Effort: Low**
+
+`type_mismatch_argument` flags passing a `static(Foo)` or `$this(Foo)`
+typed value to a `string` parameter even when `Foo` implements
+`Stringable`, which PHP accepts (it calls `__toString()`). Minimal
+reproduction:
+
+```php
+class Node implements Stringable {
+    private function __get($name): static {}
+    public function __toString(): string { return ''; }
+}
+$n = new Node();
+throw new \Exception($n->Body->Msg);
+// Argument 1 ($message) expects string, got static(Node)
+```
+
+The cause is `PhpType::is_object_like` in `src/php_type/mod.rs`: it
+answers `true` for `Named`, `Generic`, `ObjectShape` and `Nullable`, but
+`false` for `TypeKind::StaticType` and `TypeKind::ThisType`. The
+`Stringable` branch in
+`src/diagnostics/type_errors/compatibility.rs::is_type_compatible` is
+gated on `is_object_like()`, so it never runs for those two kinds and the
+check falls through to a mismatch. `base_name()` right next to it *does*
+handle both kinds, which is what makes the diagnostic message name the
+bound class correctly while the compatibility check ignores it.
+
+Every other consumer of `is_object_like` is affected the same way, so fix
+it there rather than in the diagnostic. Real-world hit: any use of
+`SimpleXMLElement`, whose stubbed `__get` returns `static`, so
+`(string) $xml->Body->Message` style code reports a false positive on
+every argument passed to a `string` parameter.