Implement Go To Type

Author: AJenbo

docs/ARCHITECTURE.md

@@ -193,6 +193,31 @@ Variable go-to-definition (`$var` → jump to definition) uses two layers:
 1. **Symbol map** (`var_defs`): the primary path. Finds the most recent `VarDefSite` before the cursor within the enclosing scope. When the cursor is physically on a definition token (parameter, foreach binding, catch variable), it returns `None` so the caller can fall through to type-hint resolution.
 2. **AST-based search** (`resolve_variable_definition_ast`): parses the file and walks the enclosing scope to find the definition site. Handles destructuring (`[$a, $b] = ...`, `list($a, $b) = ...`) and nested scopes correctly. Used as a fallback when the symbol map doesn't have a match. Returns `None` when the AST parse fails.
 
+## Go-to-Type-Definition Architecture
+
+"Go to Type Definition" (`textDocument/typeDefinition`) jumps from a symbol to the class declaration of its **resolved type**, rather than to the definition site. For example, if `$user` is typed as `User`, go-to-definition jumps to the `$user = ...` assignment, while go-to-type-definition jumps to `class User { … }`.
+
+The handler (`definition/type_definition.rs`) reuses the same symbol-map lookup as go-to-definition and the same type-resolution pipelines as hover and completion:
+
+1. **Symbol map lookup.** Convert the cursor position to a byte offset and binary-search the symbol map (same as go-to-definition, including the offset-1 retry for end-of-token cursors).
+
+2. **Type resolution by symbol kind:**
+
+   | `SymbolKind` | Resolution path |
+   |---|---|
+   | `Variable` | `resolve_variable_type_string` (type-string path) with fallback to `resolve_variable_types` (ClassInfo path). `$this` resolves to the enclosing class. |
+   | `MemberAccess` | `resolve_target_classes` finds the subject's class, then the method's `return_type` or the property's `type_hint` is extracted. `self`/`static`/`$this` in return types are replaced with the owning class name. |
+   | `SelfStaticParent` | `self`/`static` resolve to the enclosing class; `parent` resolves to the parent class. |
+   | `ClassReference` | The type is the class itself. |
+   | `FunctionCall` | The function's `return_type` is extracted. |
+   | `ClassDeclaration`, `MemberDeclaration`, `ConstantReference` | No type definition target; returns `None`. |
+
+3. **Type string to class names.** `extract_class_names_from_type_string` splits union types at depth-0 `|` separators, strips `?` (nullable), generic parameters (`<…>`), array shapes (`{…}`), and trailing `[]`. Scalar types (`int`, `string`, `array`, `void`, `mixed`, `bool`, `float`, `null`, `false`, `true`, `never`, `callable`, `iterable`, `resource`, `object`) are excluded since they have no user-navigable declaration.
+
+4. **Class name to location.** Each surviving class name is resolved via `resolve_class_reference` (the same function go-to-definition uses for class references), which tries same-file AST lookup, cross-file `class_index` + `ast_map`, Composer classmap, PSR-4, and template parameter fallback. Duplicate locations are deduplicated.
+
+For union types, the handler returns multiple locations (one per non-scalar class in the union), which editors display as a peek list.
+
 ## Signature Help Architecture
 
 Signature help shows parameter hints when the cursor is inside the parentheses

docs/CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Interface template inheritance.** When a class implements an interface whose methods use `@template`, `@param class-string<T>`, or `@return T`, the implementing class's overridden methods now inherit the template parameters, bindings, conditional return types, and type assertions.
 - **Generic `@phpstan-assert` with `class-string<T>`.** `@phpstan-assert T $value` combined with a `@template T` bound via `class-string<T>` now resolves the narrowed type from the call-site argument. Also works on static method calls like `Assert::instanceOf($value, Foo::class)`.
 - **Property-level narrowing.** `if ($this->prop instanceof Foo)` now narrows the type of `$this->prop` inside the then-body, else-body, and after guard clauses. `assert($this->prop instanceof Foo)` also works. Previously only plain variables participated in instanceof narrowing.
+- **Go to Type Definition.** `textDocument/typeDefinition` jumps from a variable, property access, method call, or function call to the class declaration of its resolved type. For example, if `$user` is typed as `User`, go-to-definition jumps to the assignment while go-to-type-definition jumps to `class User`. Union types produce multiple locations (one per class). Scalar types are filtered out. Works across files via PSR-4 resolution.
 - **Inline `&&` short-circuit narrowing.** In `if ($x instanceof Foo && $x->bar())`, the right-hand side of `&&` now sees the narrowed type from the left-hand side. Previously narrowing only applied inside the if body, so method calls within the condition itself were checked against the original (broader) type.
 - **Compound negated guard clause narrowing.** After `if (!$x instanceof A && !$x instanceof B) { return; }`, the surviving code narrows `$x` to `A|B`. Previously only single negated instanceof guard clauses were recognized.
 - **Invoked closure and arrow function return types.** `(fn(): Foo => new Foo())()` and `(function(): Bar { return new Bar(); })()` now resolve to the return type of the closure or arrow function.

docs/todo.md

@@ -62,7 +62,6 @@ feature surface grows.
 | 20 | Workspace Symbols (`workspace/symbol`) | Low-Medium | LSP Features | [lsp-features.md §5](todo/lsp-features.md#5-workspace-symbols-workspacesymbol) |
 | 21 | Folding Ranges (`textDocument/foldingRange`) | Low | LSP Features | [lsp-features.md §12](todo/lsp-features.md#12-folding-ranges-textdocumentfoldingrange) |
 | 22 | Selection Ranges (`textDocument/selectionRange`) | Low | LSP Features | [lsp-features.md §13](todo/lsp-features.md#13-selection-ranges-textdocumentselectionrange) |
-| 23 | Type Definition (`textDocument/typeDefinition`) | Low | LSP Features | [lsp-features.md §14](todo/lsp-features.md#14-type-definition-textdocumenttypedefinition) |
 | 81 | Work-done progress for GTI and Find References | Low | LSP Features | [lsp-features.md §18](todo/lsp-features.md#18-work-done-progress-for-gti-and-find-references) |
 | 101 | Argument count diagnostic | Low | Diagnostics | [diagnostics.md §7](todo/diagnostics.md#7-argument-count-diagnostic) |
 | 105 | Merged classmap + self-scan | Low | Indexing | [indexing.md §1.5](todo/indexing.md#phase-15-merged-classmap--self-scan) |

docs/todo/lsp-features.md

@@ -412,39 +412,6 @@ then the full `if` block, then the enclosing method).
 
 ---
 
-## 14. Type Definition (`textDocument/typeDefinition`)
-**Impact: Medium · Effort: Low**
-
-"Go to Type Definition" jumps from a variable or expression to the
-class of its resolved type, rather than to the definition site. For
-example, if `$user` is typed as `User`, go-to-definition jumps to the
-`$user = ...` assignment, while go-to-type-definition jumps to the
-`User` class declaration.
-
-The variable type resolution infrastructure already exists. The handler
-resolves the variable's type (or the expression type for property
-accesses and method calls), strips nullability and generic parameters,
-and looks up the class definition location.
-
-**Implementation:**
-
-1. **Register the capability** — set `type_definition_provider:
-   Some(TypeDefinitionProviderCapability::Simple(true))` in
-   `ServerCapabilities`.
-
-2. **Handler:** Given a position:
-   - If the symbol under the cursor is a variable, resolve its type via
-     the existing variable resolution pipeline.
-   - If it's a property access or method call, resolve the subject type.
-   - Strip `?`, `|null`, and generic parameters from the resolved type
-     string to get the base class name.
-   - Look up the class via `find_or_load_class` and return its
-     definition location.
-   - For union types, return multiple locations (one per class in the
-     union).
-
----
-
 ## 15. Document Links (`textDocument/documentLink`)
 **Impact: Low-Medium · Effort: Low**
 

example.php

@@ -3,8 +3,10 @@
 /**
  * PHP Showcase
  *
- * A single-file playground for every completion and go-to-definition feature.
- * Trigger completion after -> / :: / $, or Ctrl+Click for go-to-definition.
+ * A single-file playground for every completion, go-to-definition, and
+ * go-to-type-definition feature. Trigger completion after -> / :: / $,
+ * Ctrl+Click for go-to-definition, or use "Go to Type Definition" to
+ * jump to the class declaration of a variable's resolved type.
  *
  * Layout:
  *   1. DEMOS       — open any demo() method and try completion inside it
@@ -1685,6 +1687,39 @@ class GtdNotFoundException extends \RuntimeException {}
 class GtdAccessException extends \RuntimeException {}
 
 
+// ── Go-to-Type-Definition ───────────────────────────────────────────────────
+// "Go to Type Definition" jumps to the *type's* class declaration, not the
+// variable's definition site. Compare with regular Go-to-Definition:
+//   • Go-to-Definition on $user   → jumps to the $user = ... assignment
+//   • Go-to-Type-Definition on $user → jumps to class User { ... }
+//
+// Try: place the cursor on $target, $result, or $pet below and invoke
+// "Go to Type Definition" (often bound to a secondary shortcut or
+// right-click menu). Union types produce a peek list with all classes.
+
+class GoToTypeDefinitionDemo
+{
+    public function demo(): void
+    {
+        $target = new GtdTarget();
+        $target;                                  // Type Definition → GtdTarget
+
+        $result = $this->getResult();
+        $result;                                  // Type Definition → GtdResult
+
+        $pet = $this->getPet();
+        $pet;                                     // Type Definition → GtdAlpha | GtdBeta (two locations)
+
+        $this;                                    // Type Definition → GoToTypeDefinitionDemo
+    }
+
+    public function getResult(): GtdResult { return new GtdResult(); }
+
+    /** @return GtdAlpha|GtdBeta */
+    public function getPet(): GtdAlpha|GtdBeta { return new GtdAlpha(); }
+}
+
+
 // ── Go-to-Implementation ────────────────────────────────────────────────────
 // All implementors are defined right after the demo so "Go to Implementations"
 // lands within a few lines.

src/completion/source/helpers.rs

@@ -348,6 +348,19 @@ fn walk_array_segments_and_resolve(
 ) -> Option<Vec<ClassInfo>> {
     let mut current_type = raw_type.to_string();
 
+    // Expand type aliases before walking segments.  The raw type may
+    // be an alias name like `UserData` that resolves to
+    // `array{name: string, pen: Pen}`.  Without expansion the
+    // segment walk would fail to extract shape values.
+    if let Some(expanded) = crate::completion::type_resolution::resolve_type_alias(
+        &current_type,
+        current_class_name,
+        all_classes,
+        class_loader,
+    ) {
+        current_type = expanded;
+    }
+
     for seg in segments {
         match seg {
             BracketSegment::StringKey(key) => {
@@ -357,6 +370,19 @@ fn walk_array_segments_and_resolve(
                 current_type = docblock::types::extract_generic_value_type(&current_type)?;
             }
         }
+
+        // After each segment, the resulting type might itself be an
+        // alias (e.g. a shape value defined as another alias).
+        // Expand again so the next segment (or the final resolution)
+        // sees the concrete type.
+        if let Some(expanded) = crate::completion::type_resolution::resolve_type_alias(
+            &current_type,
+            current_class_name,
+            all_classes,
+            class_loader,
+        ) {
+            current_type = expanded;
+        }
     }
 
     let cleaned = docblock::clean_type(&current_type);

src/definition/mod.rs

@@ -1,8 +1,9 @@
-/// Goto definition and go-to-implementation support.
+/// Goto definition, go-to-implementation, and go-to-type-definition support.
 ///
-/// This module contains the logic for resolving "go to definition" and
-/// "go to implementation" requests, allowing users to jump from a symbol
-/// reference to its definition or concrete implementations.
+/// This module contains the logic for resolving "go to definition",
+/// "go to implementation", and "go to type definition" requests, allowing
+/// users to jump from a symbol reference to its definition, concrete
+/// implementations, or the declaration of its resolved type.
 ///
 /// The [`point_location`] helper constructs a zero-width `Location`
 /// (start == end), which is the standard shape for "go to definition"
@@ -23,6 +24,14 @@
 ///   - **Method calls on interfaces/abstract classes**: jumps to the concrete
 ///     method implementations in all implementing/extending classes
 ///
+/// Supported symbols (type definition):
+///   - **Variables**: `$var` jumps to the class declaration of the resolved type
+///   - **Member access**: `$var->method()` jumps to the return type's class
+///   - **Properties**: `$var->prop` jumps to the property type's class
+///   - **`self`/`static`/`parent`/`$this`**: jumps to the enclosing or parent class
+///   - **Function calls**: `foo()` jumps to the return type's class
+///   - For union types, multiple locations are returned (one per class)
+///
 /// - [`resolve`]: Core entry points — word extraction, name resolution,
 ///   same-file / PSR-4 definition lookup, `self`/`static`/`parent` handling,
 ///   and standalone function definition resolution.
@@ -35,11 +44,15 @@
 /// - [`implementation`]: Go-to-implementation — finding concrete classes that
 ///   implement an interface or extend an abstract class, and locating the
 ///   concrete method definitions within those classes.
+/// - [`type_definition`]: Go-to-type-definition — resolving the type of a
+///   variable, expression, or member access, then jumping to the class
+///   declaration of that type.
 use tower_lsp::lsp_types::{Location, Position, Range, Url};
 
 mod implementation;
 pub(crate) mod member;
 mod resolve;
+mod type_definition;
 mod variable;
 
 /// Build an LSP `Location` with a zero-width range (start == end).

src/definition/resolve.rs

@@ -285,7 +285,7 @@ impl Backend {
     /// When `is_fqn` is `true`, the name is already fully-qualified
     /// (the original PHP source used a leading `\`) and should be used
     /// as-is without namespace resolution.
-    fn resolve_class_reference(
+    pub(super) fn resolve_class_reference(
         &self,
         uri: &str,
         content: &str,