diff --git a/_specifications/specification-3-17.md b/_specifications/specification-3-17.md index 733b94f3c..6083637cb 100644 --- a/_specifications/specification-3-17.md +++ b/_specifications/specification-3-17.md @@ -1927,6 +1927,13 @@ export interface TextDocumentClientCapabilities { * @since 3.16.0 */ moniker?: MonikerClientCapabilities; + + /** + * Capabilities specific to the various type hierarchy requests. + * + * @since 3.17.0 + */ + typeHierarchy?: TypeHierarchyClientCapabilities; } ``` @@ -2419,6 +2426,14 @@ interface ServerCapabilities { } } + /** + * The server provides type hierarchy support. + * + * @since 3.17.0 + */ + typeHierarchyProvider?: boolean | TypeHierarchyOptions + | TypeHierarchyRegistrationOptions; + /** * Experimental server capabilities. */ @@ -8173,6 +8188,164 @@ export interface Moniker { } ``` +#### Prepare Type Hierarchy Request (:leftwards_arrow_with_hook:) + +> *Since version 3.17.0* + +The type hierarchy request is sent from the client to the server to return a type hierarchy for the language element of given text document positions. Will return `null` if the server couldn't infer a valid type from the position. The type hierarchy requests are executed in two steps: + + 1. first a type hierarchy item is prepared for the given text document position. + 1. for a type hierarchy item the supertype or subtype type hierarchy items are resolved. + +_Client Capability_: + +* property name (optional): `textDocument.typeHierarchy` +* property type: `TypeHierarchyClientCapabilities` defined as follows: + +```typescript +interface TypeHierarchyClientCapabilities { + /** + * Whether implementation supports dynamic registration. If this is set to + * `true` the client supports the new `(TextDocumentRegistrationOptions & + * StaticRegistrationOptions)` return value for the corresponding server + * capability as well. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: + +* property name (optional): `typeHierarchyProvider` +* property type: `boolean | TypeHierarchyOptions | TypeHierarchyRegistrationOptions` where `TypeHierarchyOptions` is defined as follows: + +```typescript +export interface TypeHierarchyOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `TypeHierarchyRegistrationOptions` defined as follows: + +```typescript +export interface TypeHierarchyRegistrationOptions extends + TextDocumentRegistrationOptions, TypeHierarchyOptions, + StaticRegistrationOptions { +} +``` + +_Request_: + +* method: 'textDocument/prepareTypeHierarchy' +* params: `TypeHierarchyPrepareParams` defined as follows: + +```typescript +export interface TypeHierarchyPrepareParams extends TextDocumentPositionParams, + WorkDoneProgressParams { +} +``` + +_Response_: + +* result: `TypeHierarchyItem[] | null` defined as follows: + +```typescript +export interface TypeHierarchyItem { + /** + * The name of this item. + */ + name: string; + + /** + * The kind of this item. + */ + kind: SymbolKind; + + /** + * Tags for this item. + */ + tags?: SymbolTag[]; + + /** + * More detail for this item, e.g. the signature of a function. + */ + detail?: string; + + /** + * The resource identifier of this item. + */ + uri: DocumentUri; + + /** + * The range enclosing this symbol not including leading/trailing whitespace + * but everything else, e.g. comments and code. + */ + range: Range; + + /** + * The range that should be selected and revealed when this symbol is being + * picked, e.g. the name of a function. Must be contained by the + * [`range`](#TypeHierarchyItem.range). + */ + selectionRange: Range; + + /** + * A data entry field that is preserved between a type hierarchy prepare and + * supertypes or subtypes requests. It could also be used to identify the + * type hierarchy in the server, helping improve the performance on + * resolving supertypes and subtypes. + */ + data?: unknown; +} +``` + +* error: code and message set in case an exception happens during the 'textDocument/prepareTypeHierarchy' request + +#### Type Hierarchy Supertypes(:leftwards_arrow_with_hook:) + +> *Since version 3.17.0* + +The request is sent from the client to the server to resolve the supertypes for a given type hierarchy item. Will return `null` if the server couldn't infer a valid type from `item` in the params. The request doesn't define its own client and server capabilities. It is only issued if a server registers for the [`textDocument/prepareTypeHierarchy` request](#textDocument_prepareTypeHierarchy). + +_Request_: + +* method: 'typeHierarchy/supertypes' +* params: `TypeHierarchySupertypesParams` defined as follows: + +```typescript +export interface TypeHierarchySupertypesParams extends + WorkDoneProgressParams, PartialResultParams { + item: TypeHierarchyItem; +} +``` +_Response_: + +* result: `TypeHierarchyItem[] | null` +* partial result: `TypeHierarchyItem[]` +* error: code and message set in case an exception happens during the 'typeHierarchy/supertypes' request + +#### Type Hierarchy Subtypes(:leftwards_arrow_with_hook:) + +> *Since version 3.17.0* + +The request is sent from the client to the server to resolve the subtypes for a given type hierarchy item. Will return `null` if the server couldn't infer a valid type from `item` in the params. The request doesn't define its own client and server capabilities. It is only issued if a server registers for the [`textDocument/prepareTypeHierarchy` request](#textDocument_prepareTypeHierarchy). + +_Request_: + +* method: 'typeHierarchy/subtypes' +* params: `TypeHierarchySubtypesParams` defined as follows: + +```typescript +export interface TypeHierarchySubtypesParams extends + WorkDoneProgressParams, PartialResultParams { + item: TypeHierarchyItem; +} +``` +_Response_: + +* result: `TypeHierarchyItem[] | null` +* partial result: `TypeHierarchyItem[]` +* error: code and message set in case an exception happens during the 'typeHierarchy/subtypes' request + ##### Notes Server implementations of this method should ensure that the moniker calculation matches to those used in the corresponding LSIF implementation to ensure symbols can be associated correctly across IDE sessions and LSIF indexes.