diff --git a/package.json b/package.json index 752469bb2..50058a476 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,6 @@ { "private": true, + "enableProposedApi": true, "name": "volar", "displayName": "Volar", "description": "Language support for Vue 3", @@ -12,7 +13,7 @@ "url": "https://github.com/johnsoncodehk/volar.git" }, "engines": { - "vscode": "^1.58.0" + "vscode": "^1.60.0" }, "keywords": [ "volar", diff --git a/packages/client/package.json b/packages/client/package.json index 7a0f80bd4..d301416b9 100644 --- a/packages/client/package.json +++ b/packages/client/package.json @@ -25,6 +25,6 @@ "vscode-nls": "5.0.0" }, "devDependencies": { - "@types/vscode": "^1.58.1" + "@types/vscode": "^1.60.0" } } diff --git a/packages/client/src/extension.ts b/packages/client/src/extension.ts index b1c976836..25165b2b7 100644 --- a/packages/client/src/extension.ts +++ b/packages/client/src/extension.ts @@ -9,6 +9,7 @@ import * as createWorkspaceSnippets from './features/createWorkspaceSnippets'; import * as documentVersion from './features/documentVersion'; import * as documentContent from './features/documentContent'; import * as documentPrintWidth from './features/documentPrintWidth'; +import * as inlayHints from './features/inlayHints'; import * as preview from './features/preview'; import * as showReferences from './features/showReferences'; import * as splitEditors from './features/splitEditors'; @@ -85,6 +86,7 @@ export async function activate(context: vscode.ExtensionContext) { preview.activate(context); createWorkspaceSnippets.activate(context); callGraph.activate(context, apiClient); + inlayHints.activate(context, docClient ?? apiClient); verifyAll.activate(context, docClient ?? apiClient); virtualFiles.activate(context, docClient ?? apiClient); tagClosing.activate(context, htmlClient, apiClient); diff --git a/packages/client/src/features/inlayHints.ts b/packages/client/src/features/inlayHints.ts new file mode 100644 index 000000000..3a63d1e7a --- /dev/null +++ b/packages/client/src/features/inlayHints.ts @@ -0,0 +1,48 @@ +import * as vscode from 'vscode'; +import * as shared from '@volar/shared'; +import { LanguageClient } from 'vscode-languageclient/node'; + +class TypeScriptInlayHintsProvider implements vscode.InlayHintsProvider { + + constructor( + private readonly client: LanguageClient, + ) { } + + async provideInlayHints(model: vscode.TextDocument, range: vscode.Range, _token: vscode.CancellationToken): Promise { + + const inlayHints = await this.client.sendRequest(shared.GetInlayHintsRequest.type, { + textDocument: this.client.code2ProtocolConverter.asTextDocumentIdentifier(model), + range: this.client.code2ProtocolConverter.asRange(range), + }); + + if (!inlayHints) + return []; + + return inlayHints.map(hint => { + const result = new vscode.InlayHint( + hint.text, + this.client.protocol2CodeConverter.asPosition(hint.position), + hint.kind, + ); + result.whitespaceBefore = hint.whitespaceBefore; + result.whitespaceAfter = hint.whitespaceAfter; + return result; + }); + } +} + +function register( + selector: vscode.DocumentSelector, + client: LanguageClient, +) { + return vscode.languages.registerInlayHintsProvider(selector, + new TypeScriptInlayHintsProvider(client)); +} + +export async function activate( + context: vscode.ExtensionContext, + client: LanguageClient, +) { + await client.onReady(); + context.subscriptions.push(register([{ scheme: 'file', language: 'vue' }], client)) +} diff --git a/packages/client/src/vscode.proposed.d.ts b/packages/client/src/vscode.proposed.d.ts new file mode 100644 index 000000000..0af615740 --- /dev/null +++ b/packages/client/src/vscode.proposed.d.ts @@ -0,0 +1,2950 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. See License.txt in the project root for license information. + *--------------------------------------------------------------------------------------------*/ + +/** + * This is the place for API experiments and proposals. + * These API are NOT stable and subject to change. They are only available in the Insiders + * distribution and CANNOT be used in published extensions. + * + * To test these API in local environment: + * - Use Insiders release of 'VS Code'. + * - Add `"enableProposedApi": true` to your package.json. + * - Copy this file to your project. + */ + +declare module 'vscode' { + + // eslint-disable-next-line vscode-dts-region-comments + //#region @alexdima - resolvers + + export interface MessageOptions { + /** + * Do not render a native message box. + */ + useCustom?: boolean; + } + + export interface RemoteAuthorityResolverContext { + resolveAttempt: number; + } + + export class ResolvedAuthority { + readonly host: string; + readonly port: number; + readonly connectionToken: string | undefined; + + constructor(host: string, port: number, connectionToken?: string); + } + + export interface ResolvedOptions { + extensionHostEnv?: { [key: string]: string | null; }; + + isTrusted?: boolean; + } + + export interface TunnelOptions { + remoteAddress: { port: number, host: string; }; + // The desired local port. If this port can't be used, then another will be chosen. + localAddressPort?: number; + label?: string; + public?: boolean; + protocol?: string; + } + + export interface TunnelDescription { + remoteAddress: { port: number, host: string; }; + //The complete local address(ex. localhost:1234) + localAddress: { port: number, host: string; } | string; + public?: boolean; + // If protocol is not provided it is assumed to be http, regardless of the localAddress. + protocol?: string; + } + + export interface Tunnel extends TunnelDescription { + // Implementers of Tunnel should fire onDidDispose when dispose is called. + onDidDispose: Event; + dispose(): void | Thenable; + } + + /** + * Used as part of the ResolverResult if the extension has any candidate, + * published, or forwarded ports. + */ + export interface TunnelInformation { + /** + * Tunnels that are detected by the extension. The remotePort is used for display purposes. + * The localAddress should be the complete local address (ex. localhost:1234) for connecting to the port. Tunnels provided through + * detected are read-only from the forwarded ports UI. + */ + environmentTunnels?: TunnelDescription[]; + + } + + export interface TunnelCreationOptions { + /** + * True when the local operating system will require elevation to use the requested local port. + */ + elevationRequired?: boolean; + } + + export enum CandidatePortSource { + None = 0, + Process = 1, + Output = 2 + } + + export type ResolverResult = ResolvedAuthority & ResolvedOptions & TunnelInformation; + + export class RemoteAuthorityResolverError extends Error { + static NotAvailable(message?: string, handled?: boolean): RemoteAuthorityResolverError; + static TemporarilyNotAvailable(message?: string): RemoteAuthorityResolverError; + + constructor(message?: string); + } + + export interface RemoteAuthorityResolver { + /** + * Resolve the authority part of the current opened `vscode-remote://` URI. + * + * This method will be invoked once during the startup of the editor and again each time + * the editor detects a disconnection. + * + * @param authority The authority part of the current opened `vscode-remote://` URI. + * @param context A context indicating if this is the first call or a subsequent call. + */ + resolve(authority: string, context: RemoteAuthorityResolverContext): ResolverResult | Thenable; + + /** + * Get the canonical URI (if applicable) for a `vscode-remote://` URI. + * + * @returns The canonical URI or undefined if the uri is already canonical. + */ + getCanonicalURI?(uri: Uri): ProviderResult; + + /** + * Can be optionally implemented if the extension can forward ports better than the core. + * When not implemented, the core will use its default forwarding logic. + * When implemented, the core will use this to forward ports. + * + * To enable the "Change Local Port" action on forwarded ports, make sure to set the `localAddress` of + * the returned `Tunnel` to a `{ port: number, host: string; }` and not a string. + */ + tunnelFactory?: (tunnelOptions: TunnelOptions, tunnelCreationOptions: TunnelCreationOptions) => Thenable | undefined; + + /**p + * Provides filtering for candidate ports. + */ + showCandidatePort?: (host: string, port: number, detail: string) => Thenable; + + /** + * Lets the resolver declare which tunnel factory features it supports. + * UNDER DISCUSSION! MAY CHANGE SOON. + */ + tunnelFeatures?: { + elevation: boolean; + public: boolean; + }; + + candidatePortSource?: CandidatePortSource; + } + + /** + * More options to be used when getting an {@link AuthenticationSession} from an {@link AuthenticationProvider}. + */ + export interface AuthenticationGetSessionOptions { + /** + * Whether we should attempt to reauthenticate even if there is already a session available. + * + * If true, a modal dialog will be shown asking the user to sign in again. This is mostly used for scenarios + * where the token needs to be re minted because it has lost some authorization. + * + * Defaults to false. + */ + forceNewSession?: boolean | { detail: string }; + } + + export namespace authentication { + /** + * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not + * registered, or if the user does not consent to sharing authentication information with + * the extension. If there are multiple sessions with the same scopes, the user will be shown a + * quickpick to select which account they would like to use. + * + * Currently, there are only two authentication providers that are contributed from built in extensions + * to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. + * @param providerId The id of the provider to use + * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider + * @param options The {@link AuthenticationGetSessionOptions} to use + * @returns A thenable that resolves to an authentication session + */ + export function getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & { forceNewSession: true | { detail: string } }): Thenable; + } + + export namespace workspace { + /** + * Forwards a port. If the current resolver implements RemoteAuthorityResolver:forwardPort then that will be used to make the tunnel. + * By default, openTunnel only support localhost; however, RemoteAuthorityResolver:tunnelFactory can be used to support other ips. + * + * @throws When run in an environment without a remote. + * + * @param tunnelOptions The `localPort` is a suggestion only. If that port is not available another will be chosen. + */ + export function openTunnel(tunnelOptions: TunnelOptions): Thenable; + + /** + * Gets an array of the currently available tunnels. This does not include environment tunnels, only tunnels that have been created by the user. + * Note that these are of type TunnelDescription and cannot be disposed. + */ + export let tunnels: Thenable; + + /** + * Fired when the list of tunnels has changed. + */ + export const onDidChangeTunnels: Event; + } + + export interface ResourceLabelFormatter { + scheme: string; + authority?: string; + formatting: ResourceLabelFormatting; + } + + export interface ResourceLabelFormatting { + label: string; // myLabel:/${path} + // For historic reasons we use an or string here. Once we finalize this API we should start using enums instead and adopt it in extensions. + // eslint-disable-next-line vscode-dts-literal-or-types + separator: '/' | '\\' | ''; + tildify?: boolean; + normalizeDriveLetter?: boolean; + workspaceSuffix?: string; + workspaceTooltip?: string; + authorityPrefix?: string; + stripPathStartingSeparator?: boolean; + } + + export namespace workspace { + export function registerRemoteAuthorityResolver(authorityPrefix: string, resolver: RemoteAuthorityResolver): Disposable; + export function registerResourceLabelFormatter(formatter: ResourceLabelFormatter): Disposable; + } + + //#endregion + + //#region editor insets: https://github.com/microsoft/vscode/issues/85682 + + export interface WebviewEditorInset { + readonly editor: TextEditor; + readonly line: number; + readonly height: number; + readonly webview: Webview; + readonly onDidDispose: Event; + dispose(): void; + } + + export namespace window { + export function createWebviewTextEditorInset(editor: TextEditor, line: number, height: number, options?: WebviewOptions): WebviewEditorInset; + } + + //#endregion + + //#region read/write in chunks: https://github.com/microsoft/vscode/issues/84515 + + export interface FileSystemProvider { + open?(resource: Uri, options: { create: boolean; }): number | Thenable; + close?(fd: number): void | Thenable; + read?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable; + write?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable; + } + + //#endregion + + //#region TextSearchProvider: https://github.com/microsoft/vscode/issues/59921 + + /** + * The parameters of a query for text search. + */ + export interface TextSearchQuery { + /** + * The text pattern to search for. + */ + pattern: string; + + /** + * Whether or not `pattern` should match multiple lines of text. + */ + isMultiline?: boolean; + + /** + * Whether or not `pattern` should be interpreted as a regular expression. + */ + isRegExp?: boolean; + + /** + * Whether or not the search should be case-sensitive. + */ + isCaseSensitive?: boolean; + + /** + * Whether or not to search for whole word matches only. + */ + isWordMatch?: boolean; + } + + /** + * A file glob pattern to match file paths against. + * TODO@roblourens merge this with the GlobPattern docs/definition in vscode.d.ts. + * @see {@link GlobPattern} + */ + export type GlobString = string; + + /** + * Options common to file and text search + */ + export interface SearchOptions { + /** + * The root folder to search within. + */ + folder: Uri; + + /** + * Files that match an `includes` glob pattern should be included in the search. + */ + includes: GlobString[]; + + /** + * Files that match an `excludes` glob pattern should be excluded from the search. + */ + excludes: GlobString[]; + + /** + * Whether external files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useIgnoreFiles"`. + */ + useIgnoreFiles: boolean; + + /** + * Whether symlinks should be followed while searching. + * See the vscode setting `"search.followSymlinks"`. + */ + followSymlinks: boolean; + + /** + * Whether global files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useGlobalIgnoreFiles"`. + */ + useGlobalIgnoreFiles: boolean; + } + + /** + * Options to specify the size of the result text preview. + * These options don't affect the size of the match itself, just the amount of preview text. + */ + export interface TextSearchPreviewOptions { + /** + * The maximum number of lines in the preview. + * Only search providers that support multiline search will ever return more than one line in the match. + */ + matchLines: number; + + /** + * The maximum number of characters included per line. + */ + charsPerLine: number; + } + + /** + * Options that apply to text search. + */ + export interface TextSearchOptions extends SearchOptions { + /** + * The maximum number of results to be returned. + */ + maxResults: number; + + /** + * Options to specify the size of the result text preview. + */ + previewOptions?: TextSearchPreviewOptions; + + /** + * Exclude files larger than `maxFileSize` in bytes. + */ + maxFileSize?: number; + + /** + * Interpret files using this encoding. + * See the vscode setting `"files.encoding"` + */ + encoding?: string; + + /** + * Number of lines of context to include before each match. + */ + beforeContext?: number; + + /** + * Number of lines of context to include after each match. + */ + afterContext?: number; + } + + /** + * Represents the severiry of a TextSearchComplete message. + */ + export enum TextSearchCompleteMessageType { + Information = 1, + Warning = 2, + } + + /** + * A message regarding a completed search. + */ + export interface TextSearchCompleteMessage { + /** + * Markdown text of the message. + */ + text: string, + /** + * Whether the source of the message is trusted, command links are disabled for untrusted message sources. + * Messaged are untrusted by default. + */ + trusted?: boolean, + /** + * The message type, this affects how the message will be rendered. + */ + type: TextSearchCompleteMessageType, + } + + /** + * Information collected when text search is complete. + */ + export interface TextSearchComplete { + /** + * Whether the search hit the limit on the maximum number of search results. + * `maxResults` on {@linkcode TextSearchOptions} specifies the max number of results. + * - If exactly that number of matches exist, this should be false. + * - If `maxResults` matches are returned and more exist, this should be true. + * - If search hits an internal limit which is less than `maxResults`, this should be true. + */ + limitHit?: boolean; + + /** + * Additional information regarding the state of the completed search. + * + * Messages with "Information" style support links in markdown syntax: + * - Click to [run a command](command:workbench.action.OpenQuickPick) + * - Click to [open a website](https://aka.ms) + * + * Commands may optionally return { triggerSearch: true } to signal to the editor that the original search should run be again. + */ + message?: TextSearchCompleteMessage | TextSearchCompleteMessage[]; + } + + /** + * A preview of the text result. + */ + export interface TextSearchMatchPreview { + /** + * The matching lines of text, or a portion of the matching line that contains the match. + */ + text: string; + + /** + * The Range within `text` corresponding to the text of the match. + * The number of matches must match the TextSearchMatch's range property. + */ + matches: Range | Range[]; + } + + /** + * A match from a text search + */ + export interface TextSearchMatch { + /** + * The uri for the matching document. + */ + uri: Uri; + + /** + * The range of the match within the document, or multiple ranges for multiple matches. + */ + ranges: Range | Range[]; + + /** + * A preview of the text match. + */ + preview: TextSearchMatchPreview; + } + + /** + * A line of context surrounding a TextSearchMatch. + */ + export interface TextSearchContext { + /** + * The uri for the matching document. + */ + uri: Uri; + + /** + * One line of text. + * previewOptions.charsPerLine applies to this + */ + text: string; + + /** + * The line number of this line of context. + */ + lineNumber: number; + } + + export type TextSearchResult = TextSearchMatch | TextSearchContext; + + /** + * A TextSearchProvider provides search results for text results inside files in the workspace. + */ + export interface TextSearchProvider { + /** + * Provide results that match the given text pattern. + * @param query The parameters for this query. + * @param options A set of options to consider while searching. + * @param progress A progress callback that must be invoked for all results. + * @param token A cancellation token. + */ + provideTextSearchResults(query: TextSearchQuery, options: TextSearchOptions, progress: Progress, token: CancellationToken): ProviderResult; + } + + //#endregion + + //#region FileSearchProvider: https://github.com/microsoft/vscode/issues/73524 + + /** + * The parameters of a query for file search. + */ + export interface FileSearchQuery { + /** + * The search pattern to match against file paths. + */ + pattern: string; + } + + /** + * Options that apply to file search. + */ + export interface FileSearchOptions extends SearchOptions { + /** + * The maximum number of results to be returned. + */ + maxResults?: number; + + /** + * A CancellationToken that represents the session for this search query. If the provider chooses to, this object can be used as the key for a cache, + * and searches with the same session object can search the same cache. When the token is cancelled, the session is complete and the cache can be cleared. + */ + session?: CancellationToken; + } + + /** + * A FileSearchProvider provides search results for files in the given folder that match a query string. It can be invoked by quickopen or other extensions. + * + * A FileSearchProvider is the more powerful of two ways to implement file search in the editor. Use a FileSearchProvider if you wish to search within a folder for + * all files that match the user's query. + * + * The FileSearchProvider will be invoked on every keypress in quickopen. When `workspace.findFiles` is called, it will be invoked with an empty query string, + * and in that case, every file in the folder should be returned. + */ + export interface FileSearchProvider { + /** + * Provide the set of files that match a certain file path pattern. + * @param query The parameters for this query. + * @param options A set of options to consider while searching files. + * @param token A cancellation token. + */ + provideFileSearchResults(query: FileSearchQuery, options: FileSearchOptions, token: CancellationToken): ProviderResult; + } + + export namespace workspace { + /** + * Register a search provider. + * + * Only one provider can be registered per scheme. + * + * @param scheme The provider will be invoked for workspace folders that have this file scheme. + * @param provider The provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable; + + /** + * Register a text search provider. + * + * Only one provider can be registered per scheme. + * + * @param scheme The provider will be invoked for workspace folders that have this file scheme. + * @param provider The provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable; + } + + //#endregion + + //#region findTextInFiles: https://github.com/microsoft/vscode/issues/59924 + + /** + * Options that can be set on a findTextInFiles search. + */ + export interface FindTextInFilesOptions { + /** + * A {@link GlobPattern glob pattern} that defines the files to search for. The glob pattern + * will be matched against the file paths of files relative to their workspace. Use a {@link RelativePattern relative pattern} + * to restrict the search results to a {@link WorkspaceFolder workspace folder}. + */ + include?: GlobPattern; + + /** + * A {@link GlobPattern glob pattern} that defines files and folders to exclude. The glob pattern + * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default excludes will + * apply. + */ + exclude?: GlobPattern; + + /** + * Whether to use the default and user-configured excludes. Defaults to true. + */ + useDefaultExcludes?: boolean; + + /** + * The maximum number of results to search for + */ + maxResults?: number; + + /** + * Whether external files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useIgnoreFiles"`. + */ + useIgnoreFiles?: boolean; + + /** + * Whether global files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useGlobalIgnoreFiles"`. + */ + useGlobalIgnoreFiles?: boolean; + + /** + * Whether symlinks should be followed while searching. + * See the vscode setting `"search.followSymlinks"`. + */ + followSymlinks?: boolean; + + /** + * Interpret files using this encoding. + * See the vscode setting `"files.encoding"` + */ + encoding?: string; + + /** + * Options to specify the size of the result text preview. + */ + previewOptions?: TextSearchPreviewOptions; + + /** + * Number of lines of context to include before each match. + */ + beforeContext?: number; + + /** + * Number of lines of context to include after each match. + */ + afterContext?: number; + } + + export namespace workspace { + /** + * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. + * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. + * @param callback A callback, called for each result + * @param token A token that can be used to signal cancellation to the underlying search engine. + * @return A thenable that resolves when the search is complete. + */ + export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; + + /** + * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. + * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. + * @param options An optional set of query options. Include and exclude patterns, maxResults, etc. + * @param callback A callback, called for each result + * @param token A token that can be used to signal cancellation to the underlying search engine. + * @return A thenable that resolves when the search is complete. + */ + export function findTextInFiles(query: TextSearchQuery, options: FindTextInFilesOptions, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; + } + + //#endregion + + //#region diff command: https://github.com/microsoft/vscode/issues/84899 + + /** + * The contiguous set of modified lines in a diff. + */ + export interface LineChange { + readonly originalStartLineNumber: number; + readonly originalEndLineNumber: number; + readonly modifiedStartLineNumber: number; + readonly modifiedEndLineNumber: number; + } + + export namespace commands { + + /** + * Registers a diff information command that can be invoked via a keyboard shortcut, + * a menu item, an action, or directly. + * + * Diff information commands are different from ordinary {@link commands.registerCommand commands} as + * they only execute when there is an active diff editor when the command is called, and the diff + * information has been computed. Also, the command handler of an editor command has access to + * the diff information. + * + * @param command A unique identifier for the command. + * @param callback A command handler function with access to the {@link LineChange diff information}. + * @param thisArg The `this` context used when invoking the handler function. + * @return Disposable which unregisters this command on disposal. + */ + export function registerDiffInformationCommand(command: string, callback: (diff: LineChange[], ...args: any[]) => any, thisArg?: any): Disposable; + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @roblourens: new debug session option for simple UI 'managedByParent' (see https://github.com/microsoft/vscode/issues/128588) + + /** + * Options for {@link debug.startDebugging starting a debug session}. + */ + export interface DebugSessionOptions { + + debugUI?: { + /** + * When true, the debug toolbar will not be shown for this session, the window statusbar color will not be changed, and the debug viewlet will not be automatically revealed. + */ + simple?: boolean; + } + + /** + * When true, a save will not be triggered for open editors when starting a debug session, regardless of the value of the `debug.saveBeforeStart` setting. + */ + suppressSaveBeforeStart?: boolean; + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @weinand: variables view action contributions + + /** + * A DebugProtocolVariableContainer is an opaque stand-in type for the intersection of the Scope and Variable types defined in the Debug Adapter Protocol. + * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Scope and https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. + */ + export interface DebugProtocolVariableContainer { + // Properties: the intersection of DAP's Scope and Variable types. + } + + /** + * A DebugProtocolVariable is an opaque stand-in type for the Variable type defined in the Debug Adapter Protocol. + * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. + */ + export interface DebugProtocolVariable { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Variable). + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @joaomoreno: SCM validation + + /** + * Represents the validation type of the Source Control input. + */ + export enum SourceControlInputBoxValidationType { + + /** + * Something not allowed by the rules of a language or other means. + */ + Error = 0, + + /** + * Something suspicious but allowed. + */ + Warning = 1, + + /** + * Something to inform about but not a problem. + */ + Information = 2 + } + + export interface SourceControlInputBoxValidation { + + /** + * The validation message to display. + */ + readonly message: string | MarkdownString; + + /** + * The validation type. + */ + readonly type: SourceControlInputBoxValidationType; + } + + /** + * Represents the input box in the Source Control viewlet. + */ + export interface SourceControlInputBox { + + /** + * Shows a transient contextual message on the input. + */ + showValidationMessage(message: string | MarkdownString, type: SourceControlInputBoxValidationType): void; + + /** + * A validation function for the input box. It's possible to change + * the validation provider simply by setting this property to a different function. + */ + validateInput?(value: string, cursorPosition: number): ProviderResult; + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @joaomoreno: SCM selected provider + + export interface SourceControl { + + /** + * Whether the source control is selected. + */ + readonly selected: boolean; + + /** + * An event signaling when the selection state changes. + */ + readonly onDidChangeSelection: Event; + } + + //#endregion + + //#region Terminal data write event https://github.com/microsoft/vscode/issues/78502 + + export interface TerminalDataWriteEvent { + /** + * The {@link Terminal} for which the data was written. + */ + readonly terminal: Terminal; + /** + * The data being written. + */ + readonly data: string; + } + + namespace window { + /** + * An event which fires when the terminal's child pseudo-device is written to (the shell). + * In other words, this provides access to the raw data stream from the process running + * within the terminal, including VT sequences. + */ + export const onDidWriteTerminalData: Event; + } + + //#endregion + + //#region Terminal dimensions property and change event https://github.com/microsoft/vscode/issues/55718 + + /** + * An {@link Event} which fires when a {@link Terminal}'s dimensions change. + */ + export interface TerminalDimensionsChangeEvent { + /** + * The {@link Terminal} for which the dimensions have changed. + */ + readonly terminal: Terminal; + /** + * The new value for the {@link Terminal.dimensions terminal's dimensions}. + */ + readonly dimensions: TerminalDimensions; + } + + export namespace window { + /** + * An event which fires when the {@link Terminal.dimensions dimensions} of the terminal change. + */ + export const onDidChangeTerminalDimensions: Event; + } + + export interface Terminal { + /** + * The current dimensions of the terminal. This will be `undefined` immediately after the + * terminal is created as the dimensions are not known until shortly after the terminal is + * created. + */ + readonly dimensions: TerminalDimensions | undefined; + } + + //#endregion + + //#region Terminal state event https://github.com/microsoft/vscode/issues/127717 + + /** + * Represents the state of a {@link Terminal}. + */ + export interface TerminalState { + /** + * Whether the {@link Terminal} has been interacted with. Interaction means that the + * terminal has sent data to the process which depending on the terminal's _mode_. By + * default input is sent when a key is pressed or when a command or extension sends text, + * but based on the terminal's mode it can also happen on: + * + * - a pointer click event + * - a pointer scroll event + * - a pointer move event + * - terminal focus in/out + * + * For more information on events that can send data see "DEC Private Mode Set (DECSET)" on + * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html + */ + readonly interactedWith: boolean; + } + + export interface Terminal { + /** + * The current state of the {@link Terminal}. + */ + readonly state: TerminalState; + } + + export namespace window { + /** + * An {@link Event} which fires when a {@link Terminal.state terminal's state} has changed. + */ + export const onDidChangeTerminalState: Event; + } + + //#endregion + + //#region Terminal location https://github.com/microsoft/vscode/issues/45407 + + export interface TerminalOptions { + location?: TerminalLocation | TerminalEditorLocationOptions | TerminalSplitLocationOptions; + } + + export interface ExtensionTerminalOptions { + location?: TerminalLocation | TerminalEditorLocationOptions | TerminalSplitLocationOptions; + } + + export enum TerminalLocation { + Panel = 1, + Editor = 2, + } + + export interface TerminalEditorLocationOptions { + /** + * A view column in which the {@link Terminal terminal} should be shown in the editor area. + * Use {@link ViewColumn.Active active} to open in the active editor group, other values are + * adjusted to be `Min(column, columnCount + 1)`, the + * {@link ViewColumn.Active active}-column is not adjusted. Use + * {@linkcode ViewColumn.Beside} to open the editor to the side of the currently active one. + */ + viewColumn: ViewColumn; + /** + * An optional flag that when `true` will stop the {@link Terminal} from taking focus. + */ + preserveFocus?: boolean; + } + + export interface TerminalSplitLocationOptions { + /** + * The parent terminal to split this terminal beside. This works whether the parent terminal + * is in the panel or the editor area. + */ + parentTerminal: Terminal; + } + + //#endregion + + //#region Terminal name change event https://github.com/microsoft/vscode/issues/114898 + + export interface Pseudoterminal { + /** + * An event that when fired allows changing the name of the terminal. + * + * **Example:** Change the terminal name to "My new terminal". + * ```typescript + * const writeEmitter = new vscode.EventEmitter(); + * const changeNameEmitter = new vscode.EventEmitter(); + * const pty: vscode.Pseudoterminal = { + * onDidWrite: writeEmitter.event, + * onDidChangeName: changeNameEmitter.event, + * open: () => changeNameEmitter.fire('My new terminal'), + * close: () => {} + * }; + * vscode.window.createTerminal({ name: 'My terminal', pty }); + * ``` + */ + onDidChangeName?: Event; + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @jrieken -> exclusive document filters + + export interface DocumentFilter { + readonly exclusive?: boolean; + } + + //#endregion + + //#region Tree View: https://github.com/microsoft/vscode/issues/61313 @alexr00 + export interface TreeView extends Disposable { + reveal(element: T | undefined, options?: { select?: boolean, focus?: boolean, expand?: boolean | number; }): Thenable; + } + //#endregion + + //#region Custom Tree View Drag and Drop https://github.com/microsoft/vscode/issues/32592 + /** + * A data provider that provides tree data + */ + export interface TreeDataProvider { + /** + * An optional event to signal that an element or root has changed. + * This will trigger the view to update the changed element/root and its children recursively (if shown). + * To signal that root has changed, do not pass any argument or pass `undefined` or `null`. + */ + onDidChangeTreeData2?: Event; + } + + export interface TreeViewOptions { + /** + * An optional interface to implement drag and drop in the tree view. + */ + dragAndDropController?: DragAndDropController; + } + + export interface TreeDataTransferItem { + asString(): Thenable; + } + + export interface TreeDataTransfer { + /** + * A map containing a mapping of the mime type of the corresponding data. + * The type for tree elements is text/treeitem. + * For example, you can reconstruct the your tree elements: + * ```ts + * JSON.parse(await (items.get('text/treeitem')!.asString())) + * ``` + */ + items: { get: (mimeType: string) => TreeDataTransferItem | undefined }; + } + + export interface DragAndDropController extends Disposable { + readonly supportedTypes: string[]; + + /** + * todo@API maybe + * + * When the user drops an item from this DragAndDropController on **another tree item** in **the same tree**, + * `onWillDrop` will be called with the dropped tree item. This is the DragAndDropController's opportunity to + * package the data from the dropped tree item into whatever format they want the target tree item to receive. + * + * The returned `TreeDataTransfer` will be merged with the original`TreeDataTransfer` for the operation. + * + * Note for implementation later: This means that the `text/treeItem` mime type will go away. + * + * @param source + */ + // onWillDrop?(source: T): Thenable; + + /** + * Extensions should fire `TreeDataProvider.onDidChangeTreeData` for any elements that need to be refreshed. + * + * @param source + * @param target + */ + onDrop(source: TreeDataTransfer, target: T): Thenable; + } + //#endregion + + //#region Task presentation group: https://github.com/microsoft/vscode/issues/47265 + export interface TaskPresentationOptions { + /** + * Controls whether the task is executed in a specific terminal group using split panes. + */ + group?: string; + + /** + * Controls whether the terminal is closed after executing the task. + */ + close?: boolean; + } + //#endregion + + //#region Custom editor move https://github.com/microsoft/vscode/issues/86146 + + // TODO: Also for custom editor + + export interface CustomTextEditorProvider { + + /** + * Handle when the underlying resource for a custom editor is renamed. + * + * This allows the webview for the editor be preserved throughout the rename. If this method is not implemented, + * the editor will destroy the previous custom editor and create a replacement one. + * + * @param newDocument New text document to use for the custom editor. + * @param existingWebviewPanel Webview panel for the custom editor. + * @param token A cancellation token that indicates the result is no longer needed. + * + * @return Thenable indicating that the webview editor has been moved. + */ + // eslint-disable-next-line vscode-dts-provider-naming + moveCustomTextEditor?(newDocument: TextDocument, existingWebviewPanel: WebviewPanel, token: CancellationToken): Thenable; + } + + //#endregion + + //#region allow QuickPicks to skip sorting: https://github.com/microsoft/vscode/issues/73904 + + export interface QuickPick extends QuickInput { + /** + * An optional flag to sort the final results by index of first query match in label. Defaults to true. + */ + sortByLabel: boolean; + + /* + * An optional flag that can be set to true to maintain the scroll position of the quick pick when the quick pick items are updated. Defaults to false. + */ + keepScrollPosition?: boolean; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/124970, Cell Execution State + + /** + * The execution state of a notebook cell. + */ + export enum NotebookCellExecutionState { + /** + * The cell is idle. + */ + Idle = 1, + /** + * Execution for the cell is pending. + */ + Pending = 2, + /** + * The cell is currently executing. + */ + Executing = 3, + } + + /** + * An event describing a cell execution state change. + */ + export interface NotebookCellExecutionStateChangeEvent { + /** + * The {@link NotebookCell cell} for which the execution state has changed. + */ + readonly cell: NotebookCell; + + /** + * The new execution state of the cell. + */ + readonly state: NotebookCellExecutionState; + } + + export namespace notebooks { + + /** + * An {@link Event} which fires when the execution state of a cell has changed. + */ + // todo@API this is an event that is fired for a property that cells don't have and that makes me wonder + // how a correct consumer works, e.g the consumer could have been late and missed an event? + export const onDidChangeNotebookCellExecutionState: Event; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, Notebook, deprecated & misc + + export interface NotebookCellOutput { + id: string; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditor + + /** + * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}. + */ + export enum NotebookEditorRevealType { + /** + * The range will be revealed with as little scrolling as possible. + */ + Default = 0, + + /** + * The range will always be revealed in the center of the viewport. + */ + InCenter = 1, + + /** + * If the range is outside the viewport, it will be revealed in the center of the viewport. + * Otherwise, it will be revealed with as little scrolling as possible. + */ + InCenterIfOutsideViewport = 2, + + /** + * The range will always be revealed at the top of the viewport. + */ + AtTop = 3 + } + + /** + * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}. + */ + export interface NotebookEditor { + /** + * The document associated with this notebook editor. + */ + //todo@api rename to notebook? + readonly document: NotebookDocument; + + /** + * The selections on this notebook editor. + * + * The primary selection (or focused range) is `selections[0]`. When the document has no cells, the primary selection is empty `{ start: 0, end: 0 }`; + */ + selections: NotebookRange[]; + + /** + * The current visible ranges in the editor (vertically). + */ + readonly visibleRanges: NotebookRange[]; + + /** + * Scroll as indicated by `revealType` in order to reveal the given range. + * + * @param range A range. + * @param revealType The scrolling strategy for revealing `range`. + */ + revealRange(range: NotebookRange, revealType?: NotebookEditorRevealType): void; + + /** + * The column in which this editor shows. + */ + readonly viewColumn?: ViewColumn; + } + + export interface NotebookDocumentMetadataChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the document metadata have changed. + */ + //todo@API rename to notebook? + readonly document: NotebookDocument; + } + + export interface NotebookCellsChangeData { + readonly start: number; + // todo@API end? Use NotebookCellRange instead? + readonly deletedCount: number; + // todo@API removedCells, deletedCells? + readonly deletedItems: NotebookCell[]; + // todo@API addedCells, insertedCells, newCells? + readonly items: NotebookCell[]; + } + + export interface NotebookCellsChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cells have changed. + */ + //todo@API rename to notebook? + readonly document: NotebookDocument; + readonly changes: ReadonlyArray; + } + + export interface NotebookCellOutputsChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cell outputs have changed. + */ + //todo@API remove? use cell.notebook instead? + readonly document: NotebookDocument; + // NotebookCellOutputsChangeEvent.cells vs NotebookCellMetadataChangeEvent.cell + readonly cells: NotebookCell[]; + } + + export interface NotebookCellMetadataChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cell metadata have changed. + */ + //todo@API remove? use cell.notebook instead? + readonly document: NotebookDocument; + // NotebookCellOutputsChangeEvent.cells vs NotebookCellMetadataChangeEvent.cell + readonly cell: NotebookCell; + } + + export interface NotebookEditorSelectionChangeEvent { + /** + * The {@link NotebookEditor notebook editor} for which the selections have changed. + */ + readonly notebookEditor: NotebookEditor; + readonly selections: ReadonlyArray + } + + export interface NotebookEditorVisibleRangesChangeEvent { + /** + * The {@link NotebookEditor notebook editor} for which the visible ranges have changed. + */ + readonly notebookEditor: NotebookEditor; + readonly visibleRanges: ReadonlyArray; + } + + + export interface NotebookDocumentShowOptions { + viewColumn?: ViewColumn; + preserveFocus?: boolean; + preview?: boolean; + selections?: NotebookRange[]; + } + + export namespace notebooks { + + + + export const onDidSaveNotebookDocument: Event; + + export const onDidChangeNotebookDocumentMetadata: Event; + export const onDidChangeNotebookCells: Event; + + // todo@API add onDidChangeNotebookCellOutputs + export const onDidChangeCellOutputs: Event; + + // todo@API add onDidChangeNotebookCellMetadata + export const onDidChangeCellMetadata: Event; + } + + export namespace window { + export const visibleNotebookEditors: NotebookEditor[]; + export const onDidChangeVisibleNotebookEditors: Event; + export const activeNotebookEditor: NotebookEditor | undefined; + export const onDidChangeActiveNotebookEditor: Event; + export const onDidChangeNotebookEditorSelection: Event; + export const onDidChangeNotebookEditorVisibleRanges: Event; + + export function showNotebookDocument(uri: Uri, options?: NotebookDocumentShowOptions): Thenable; + export function showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorEdit + + // todo@API add NotebookEdit-type which handles all these cases? + // export class NotebookEdit { + // range: NotebookRange; + // newCells: NotebookCellData[]; + // newMetadata?: NotebookDocumentMetadata; + // constructor(range: NotebookRange, newCells: NotebookCellData) + // } + + // export class NotebookCellEdit { + // newMetadata?: NotebookCellMetadata; + // } + + // export interface WorkspaceEdit { + // set(uri: Uri, edits: TextEdit[] | NotebookEdit[]): void + // } + + export interface WorkspaceEdit { + // todo@API add NotebookEdit-type which handles all these cases? + replaceNotebookMetadata(uri: Uri, value: { [key: string]: any }): void; + replaceNotebookCells(uri: Uri, range: NotebookRange, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void; + replaceNotebookCellMetadata(uri: Uri, index: number, cellMetadata: { [key: string]: any }, metadata?: WorkspaceEditEntryMetadata): void; + } + + export interface NotebookEditorEdit { + replaceMetadata(value: { [key: string]: any }): void; + replaceCells(start: number, end: number, cells: NotebookCellData[]): void; + replaceCellMetadata(index: number, metadata: { [key: string]: any }): void; + } + + export interface NotebookEditor { + /** + * Perform an edit on the notebook associated with this notebook editor. + * + * The given callback-function is invoked with an {@link NotebookEditorEdit edit-builder} which must + * be used to make edits. Note that the edit-builder is only valid while the + * callback executes. + * + * @param callback A function which can create edits using an {@link NotebookEditorEdit edit-builder}. + * @return A promise that resolves with a value indicating if the edits could be applied. + */ + // @jrieken REMOVE maybe + edit(callback: (editBuilder: NotebookEditorEdit) => void): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorDecorationType + + export interface NotebookEditor { + setDecorations(decorationType: NotebookEditorDecorationType, range: NotebookRange): void; + } + + export interface NotebookDecorationRenderOptions { + backgroundColor?: string | ThemeColor; + borderColor?: string | ThemeColor; + top: ThemableDecorationAttachmentRenderOptions; + } + + export interface NotebookEditorDecorationType { + readonly key: string; + dispose(): void; + } + + export namespace notebooks { + export function createNotebookEditorDecorationType(options: NotebookDecorationRenderOptions): NotebookEditorDecorationType; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookConcatTextDocument + + export namespace notebooks { + /** + * Create a document that is the concatenation of all notebook cells. By default all code-cells are included + * but a selector can be provided to narrow to down the set of cells. + * + * @param notebook + * @param selector + */ + // todo@API really needed? we didn't find a user here + export function createConcatTextDocument(notebook: NotebookDocument, selector?: DocumentSelector): NotebookConcatTextDocument; + } + + export interface NotebookConcatTextDocument { + readonly uri: Uri; + readonly isClosed: boolean; + dispose(): void; + readonly onDidChange: Event; + readonly version: number; + getText(): string; + getText(range: Range): string; + + offsetAt(position: Position): number; + positionAt(offset: number): Position; + validateRange(range: Range): Range; + validatePosition(position: Position): Position; + + locationAt(positionOrRange: Position | Range): Location; + positionAt(location: Location): Position; + contains(uri: Uri): boolean; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookContentProvider + + + interface NotebookDocumentBackup { + /** + * Unique identifier for the backup. + * + * This id is passed back to your extension in `openNotebook` when opening a notebook editor from a backup. + */ + readonly id: string; + + /** + * Delete the current backup. + * + * This is called by the editor when it is clear the current backup is no longer needed, such as when a new backup + * is made or when the file is saved. + */ + delete(): void; + } + + interface NotebookDocumentBackupContext { + readonly destination: Uri; + } + + interface NotebookDocumentOpenContext { + readonly backupId?: string; + readonly untitledDocumentData?: Uint8Array; + } + + // todo@API use openNotebookDOCUMENT to align with openCustomDocument etc? + // todo@API rename to NotebookDocumentContentProvider + export interface NotebookContentProvider { + + readonly options?: NotebookDocumentContentOptions; + readonly onDidChangeNotebookContentOptions?: Event; + + /** + * Content providers should always use {@link FileSystemProvider file system providers} to + * resolve the raw content for `uri` as the resouce is not necessarily a file on disk. + */ + openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext, token: CancellationToken): NotebookData | Thenable; + + // todo@API use NotebookData instead + saveNotebook(document: NotebookDocument, token: CancellationToken): Thenable; + + // todo@API use NotebookData instead + saveNotebookAs(targetResource: Uri, document: NotebookDocument, token: CancellationToken): Thenable; + + // todo@API use NotebookData instead + backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, token: CancellationToken): Thenable; + } + + export namespace workspace { + + // TODO@api use NotebookDocumentFilter instead of just notebookType:string? + // TODO@API options duplicates the more powerful variant on NotebookContentProvider + export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions): Disposable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, LiveShare + + export interface NotebookRegistrationData { + displayName: string; + filenamePattern: (GlobPattern | { include: GlobPattern; exclude: GlobPattern; })[]; + exclusive?: boolean; + } + + export namespace workspace { + // SPECIAL overload with NotebookRegistrationData + export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions, registrationData?: NotebookRegistrationData): Disposable; + // SPECIAL overload with NotebookRegistrationData + export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions, registration?: NotebookRegistrationData): Disposable; + } + + //#endregion + + //#region @https://github.com/microsoft/vscode/issues/123601, notebook messaging + + /** + * Represents a script that is loaded into the notebook renderer before rendering output. This allows + * to provide and share functionality for notebook markup and notebook output renderers. + */ + export class NotebookRendererScript { + + /** + * APIs that the preload provides to the renderer. These are matched + * against the `dependencies` and `optionalDependencies` arrays in the + * notebook renderer contribution point. + */ + provides: string[]; + + /** + * URI for the file to preload + */ + uri: Uri; + + /** + * @param uri URI for the file to preload + * @param provides Value for the `provides` property + */ + constructor(uri: Uri, provides?: string | string[]); + } + + export interface NotebookController { + + // todo@API allow add, not remove + readonly rendererScripts: NotebookRendererScript[]; + + /** + * An event that fires when a {@link NotebookController.rendererScripts renderer script} has send a message to + * the controller. + */ + readonly onDidReceiveMessage: Event<{ editor: NotebookEditor, message: any }>; + + /** + * Send a message to the renderer of notebook editors. + * + * Note that only editors showing documents that are bound to this controller + * are receiving the message. + * + * @param message The message to send. + * @param editor A specific editor to send the message to. When `undefined` all applicable editors are receiving the message. + * @returns A promise that resolves to a boolean indicating if the message has been send or not. + */ + postMessage(message: any, editor?: NotebookEditor): Thenable; + + //todo@API validate this works + asWebviewUri(localResource: Uri): Uri; + } + + export namespace notebooks { + + export function createNotebookController(id: string, viewType: string, label: string, handler?: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable, rendererScripts?: NotebookRendererScript[]): NotebookController; + } + + //#endregion + + //#region @eamodio - timeline: https://github.com/microsoft/vscode/issues/84297 + + export class TimelineItem { + /** + * A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred. + */ + timestamp: number; + + /** + * A human-readable string describing the timeline item. + */ + label: string; + + /** + * Optional id for the timeline item. It must be unique across all the timeline items provided by this source. + * + * If not provided, an id is generated using the timeline item's timestamp. + */ + id?: string; + + /** + * The icon path or {@link ThemeIcon} for the timeline item. + */ + iconPath?: Uri | { light: Uri; dark: Uri; } | ThemeIcon; + + /** + * A human readable string describing less prominent details of the timeline item. + */ + description?: string; + + /** + * The tooltip text when you hover over the timeline item. + */ + detail?: string; + + /** + * The {@link Command} that should be executed when the timeline item is selected. + */ + command?: Command; + + /** + * Context value of the timeline item. This can be used to contribute specific actions to the item. + * For example, a timeline item is given a context value as `commit`. When contributing actions to `timeline/item/context` + * using `menus` extension point, you can specify context value for key `timelineItem` in `when` expression like `timelineItem == commit`. + * ``` + * "contributes": { + * "menus": { + * "timeline/item/context": [ + * { + * "command": "extension.copyCommitId", + * "when": "timelineItem == commit" + * } + * ] + * } + * } + * ``` + * This will show the `extension.copyCommitId` action only for items where `contextValue` is `commit`. + */ + contextValue?: string; + + /** + * Accessibility information used when screen reader interacts with this timeline item. + */ + accessibilityInformation?: AccessibilityInformation; + + /** + * @param label A human-readable string describing the timeline item + * @param timestamp A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred + */ + constructor(label: string, timestamp: number); + } + + export interface TimelineChangeEvent { + /** + * The {@link Uri} of the resource for which the timeline changed. + */ + uri: Uri; + + /** + * A flag which indicates whether the entire timeline should be reset. + */ + reset?: boolean; + } + + export interface Timeline { + readonly paging?: { + /** + * A provider-defined cursor specifying the starting point of timeline items which are after the ones returned. + * Use `undefined` to signal that there are no more items to be returned. + */ + readonly cursor: string | undefined; + }; + + /** + * An array of {@link TimelineItem timeline items}. + */ + readonly items: readonly TimelineItem[]; + } + + export interface TimelineOptions { + /** + * A provider-defined cursor specifying the starting point of the timeline items that should be returned. + */ + cursor?: string; + + /** + * An optional maximum number timeline items or the all timeline items newer (inclusive) than the timestamp or id that should be returned. + * If `undefined` all timeline items should be returned. + */ + limit?: number | { timestamp: number; id?: string; }; + } + + export interface TimelineProvider { + /** + * An optional event to signal that the timeline for a source has changed. + * To signal that the timeline for all resources (uris) has changed, do not pass any argument or pass `undefined`. + */ + onDidChange?: Event; + + /** + * An identifier of the source of the timeline items. This can be used to filter sources. + */ + readonly id: string; + + /** + * A human-readable string describing the source of the timeline items. This can be used as the display label when filtering sources. + */ + readonly label: string; + + /** + * Provide {@link TimelineItem timeline items} for a {@link Uri}. + * + * @param uri The {@link Uri} of the file to provide the timeline for. + * @param options A set of options to determine how results should be returned. + * @param token A cancellation token. + * @return The {@link TimelineResult timeline result} or a thenable that resolves to such. The lack of a result + * can be signaled by returning `undefined`, `null`, or an empty array. + */ + provideTimeline(uri: Uri, options: TimelineOptions, token: CancellationToken): ProviderResult; + } + + export namespace workspace { + /** + * Register a timeline provider. + * + * Multiple providers can be registered. In that case, providers are asked in + * parallel and the results are merged. A failing provider (rejected promise or exception) will + * not cause a failure of the whole operation. + * + * @param scheme A scheme or schemes that defines which documents this provider is applicable to. Can be `*` to target all documents. + * @param provider A timeline provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerTimelineProvider(scheme: string | string[], provider: TimelineProvider): Disposable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/91555 + + export enum StandardTokenType { + Other = 0, + Comment = 1, + String = 2, + RegEx = 4 + } + + export interface TokenInformation { + type: StandardTokenType; + range: Range; + } + + export namespace languages { + export function getTokenInformationAtPosition(document: TextDocument, position: Position): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/16221 + + // todo@API Split between Inlay- and OverlayHints (InlayHint are for a position, OverlayHints for a non-empty range) + // todo@API add "mini-markdown" for links and styles + // (done) remove description + // (done) rename to InlayHint + // (done) add InlayHintKind with type, argument, etc + + export namespace languages { + /** + * Register a inlay hints provider. + * + * Multiple providers can be registered for a language. In that case providers are asked in + * parallel and the results are merged. A failing provider (rejected promise or exception) will + * not cause a failure of the whole operation. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider An inlay hints provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider): Disposable; + } + + export enum InlayHintKind { + Other = 0, + Type = 1, + Parameter = 2, + } + + /** + * Inlay hint information. + */ + export class InlayHint { + /** + * The text of the hint. + */ + text: string; + /** + * The position of this hint. + */ + position: Position; + /** + * The kind of this hint. + */ + kind?: InlayHintKind; + /** + * Whitespace before the hint. + */ + whitespaceBefore?: boolean; + /** + * Whitespace after the hint. + */ + whitespaceAfter?: boolean; + + // todo@API make range first argument + constructor(text: string, position: Position, kind?: InlayHintKind); + } + + /** + * The inlay hints provider interface defines the contract between extensions and + * the inlay hints feature. + */ + export interface InlayHintsProvider { + + /** + * An optional event to signal that inlay hints have changed. + * @see {@link EventEmitter} + */ + onDidChangeInlayHints?: Event; + + /** + * + * @param model The document in which the command was invoked. + * @param range The range for which inlay hints should be computed. + * @param token A cancellation token. + * @return A list of inlay hints or a thenable that resolves to such. + */ + provideInlayHints(model: TextDocument, range: Range, token: CancellationToken): ProviderResult; + } + //#endregion + + //#region https://github.com/microsoft/vscode/issues/104436 + + export enum ExtensionRuntime { + /** + * The extension is running in a NodeJS extension host. Runtime access to NodeJS APIs is available. + */ + Node = 1, + /** + * The extension is running in a Webworker extension host. Runtime access is limited to Webworker APIs. + */ + Webworker = 2 + } + + export interface ExtensionContext { + readonly extensionRuntime: ExtensionRuntime; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/102091 + + export interface TextDocument { + + /** + * The {@link NotebookDocument notebook} that contains this document as a notebook cell or `undefined` when + * the document is not contained by a notebook (this should be the more frequent case). + */ + notebook: NotebookDocument | undefined; + } + //#endregion + + //#region non-error test output https://github.com/microsoft/vscode/issues/129201 + interface TestRun { + /** + * Appends raw output from the test runner. On the user's request, the + * output will be displayed in a terminal. ANSI escape sequences, + * such as colors and text styles, are supported. + * + * @param output Output text to append. + * @param location Indicate that the output was logged at the given + * location. + * @param test Test item to associate the output with. + */ + appendOutput(output: string, location?: Location, test?: TestItem): void; + } + //#endregion + + //#region test tags https://github.com/microsoft/vscode/issues/129456 + /** + * Tags can be associated with {@link TestItem TestItems} and + * {@link TestRunProfile TestRunProfiles}. A profile with a tag can only + * execute tests that include that tag in their {@link TestItem.tags} array. + */ + export class TestTag { + /** + * ID of the test tag. `TestTag` instances with the same ID are considered + * to be identical. + */ + readonly id: string; + + /** + * Creates a new TestTag instance. + * @param id ID of the test tag. + */ + constructor(id: string); + } + + export interface TestRunProfile { + /** + * Associated tag for the profile. If this is set, only {@link TestItem} + * instances with the same tag will be eligible to execute in this profile. + */ + tag?: TestTag; + } + + export interface TestItem { + /** + * Tags associated with this test item. May be used in combination with + * {@link TestRunProfile.tags}, or simply as an organizational feature. + */ + tags: readonly TestTag[]; + } + + export interface TestController { + createRunProfile(label: string, kind: TestRunProfileKind, runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable | void, isDefault?: boolean, tag?: TestTag): TestRunProfile; + } + + //#endregion + + //#region proposed test APIs https://github.com/microsoft/vscode/issues/107467 + export namespace tests { + /** + * Requests that tests be run by their controller. + * @param run Run options to use. + * @param token Cancellation token for the test run + */ + export function runTests(run: TestRunRequest, token?: CancellationToken): Thenable; + + /** + * Returns an observer that watches and can request tests. + */ + export function createTestObserver(): TestObserver; + /** + * List of test results stored by the editor, sorted in descending + * order by their `completedAt` time. + */ + export const testResults: ReadonlyArray; + + /** + * Event that fires when the {@link testResults} array is updated. + */ + export const onDidChangeTestResults: Event; + } + + export interface TestObserver { + /** + * List of tests returned by test provider for files in the workspace. + */ + readonly tests: ReadonlyArray; + + /** + * An event that fires when an existing test in the collection changes, or + * null if a top-level test was added or removed. When fired, the consumer + * should check the test item and all its children for changes. + */ + readonly onDidChangeTest: Event; + + /** + * Dispose of the observer, allowing the editor to eventually tell test + * providers that they no longer need to update tests. + */ + dispose(): void; + } + + export interface TestsChangeEvent { + /** + * List of all tests that are newly added. + */ + readonly added: ReadonlyArray; + + /** + * List of existing tests that have updated. + */ + readonly updated: ReadonlyArray; + + /** + * List of existing tests that have been removed. + */ + readonly removed: ReadonlyArray; + } + + /** + * A test item is an item shown in the "test explorer" view. It encompasses + * both a suite and a test, since they have almost or identical capabilities. + */ + export interface TestItem { + /** + * Marks the test as outdated. This can happen as a result of file changes, + * for example. In "auto run" mode, tests that are outdated will be + * automatically rerun after a short delay. Invoking this on a + * test with children will mark the entire subtree as outdated. + * + * Extensions should generally not override this method. + */ + // todo@api still unsure about this + invalidateResults(): void; + } + + + /** + * TestResults can be provided to the editor in {@link tests.publishTestResult}, + * or read from it in {@link tests.testResults}. + * + * The results contain a 'snapshot' of the tests at the point when the test + * run is complete. Therefore, information such as its {@link Range} may be + * out of date. If the test still exists in the workspace, consumers can use + * its `id` to correlate the result instance with the living test. + */ + export interface TestRunResult { + /** + * Unix milliseconds timestamp at which the test run was completed. + */ + readonly completedAt: number; + + /** + * Optional raw output from the test run. + */ + readonly output?: string; + + /** + * List of test results. The items in this array are the items that + * were passed in the {@link tests.runTests} method. + */ + readonly results: ReadonlyArray>; + } + + /** + * A {@link TestItem}-like interface with an associated result, which appear + * or can be provided in {@link TestResult} interfaces. + */ + export interface TestResultSnapshot { + /** + * Unique identifier that matches that of the associated TestItem. + * This is used to correlate test results and tests in the document with + * those in the workspace (test explorer). + */ + readonly id: string; + + /** + * Parent of this item. + */ + readonly parent?: TestResultSnapshot; + + /** + * URI this TestItem is associated with. May be a file or file. + */ + readonly uri?: Uri; + + /** + * Display name describing the test case. + */ + readonly label: string; + + /** + * Optional description that appears next to the label. + */ + readonly description?: string; + + /** + * Location of the test item in its `uri`. This is only meaningful if the + * `uri` points to a file. + */ + readonly range?: Range; + + /** + * State of the test in each task. In the common case, a test will only + * be executed in a single task and the length of this array will be 1. + */ + readonly taskStates: ReadonlyArray; + + /** + * Optional list of nested tests for this item. + */ + readonly children: Readonly[]; + } + + export interface TestSnapshotTaskState { + /** + * Current result of the test. + */ + readonly state: TestResultState; + + /** + * The number of milliseconds the test took to run. This is set once the + * `state` is `Passed`, `Failed`, or `Errored`. + */ + readonly duration?: number; + + /** + * Associated test run message. Can, for example, contain assertion + * failure information if the test fails. + */ + readonly messages: ReadonlyArray; + } + + /** + * Possible states of tests in a test run. + */ + export enum TestResultState { + // Test will be run, but is not currently running. + Queued = 1, + // Test is currently running + Running = 2, + // Test run has passed + Passed = 3, + // Test run has failed (on an assertion) + Failed = 4, + // Test run has been skipped + Skipped = 5, + // Test run failed for some other reason (compilation error, timeout, etc) + Errored = 6 + } + + //#endregion + + //#region Opener service (https://github.com/microsoft/vscode/issues/109277) + + /** + * Details if an `ExternalUriOpener` can open a uri. + * + * The priority is also used to rank multiple openers against each other and determine + * if an opener should be selected automatically or if the user should be prompted to + * select an opener. + * + * The editor will try to use the best available opener, as sorted by `ExternalUriOpenerPriority`. + * If there are multiple potential "best" openers for a URI, then the user will be prompted + * to select an opener. + */ + export enum ExternalUriOpenerPriority { + /** + * The opener is disabled and will never be shown to users. + * + * Note that the opener can still be used if the user specifically + * configures it in their settings. + */ + None = 0, + + /** + * The opener can open the uri but will not cause a prompt on its own + * since the editor always contributes a built-in `Default` opener. + */ + Option = 1, + + /** + * The opener can open the uri. + * + * The editor's built-in opener has `Default` priority. This means that any additional `Default` + * openers will cause the user to be prompted to select from a list of all potential openers. + */ + Default = 2, + + /** + * The opener can open the uri and should be automatically selected over any + * default openers, include the built-in one from the editor. + * + * A preferred opener will be automatically selected if no other preferred openers + * are available. If multiple preferred openers are available, then the user + * is shown a prompt with all potential openers (not just preferred openers). + */ + Preferred = 3, + } + + /** + * Handles opening uris to external resources, such as http(s) links. + * + * Extensions can implement an `ExternalUriOpener` to open `http` links to a webserver + * inside of the editor instead of having the link be opened by the web browser. + * + * Currently openers may only be registered for `http` and `https` uris. + */ + export interface ExternalUriOpener { + + /** + * Check if the opener can open a uri. + * + * @param uri The uri being opened. This is the uri that the user clicked on. It has + * not yet gone through port forwarding. + * @param token Cancellation token indicating that the result is no longer needed. + * + * @return Priority indicating if the opener can open the external uri. + */ + canOpenExternalUri(uri: Uri, token: CancellationToken): ExternalUriOpenerPriority | Thenable; + + /** + * Open a uri. + * + * This is invoked when: + * + * - The user clicks a link which does not have an assigned opener. In this case, first `canOpenExternalUri` + * is called and if the user selects this opener, then `openExternalUri` is called. + * - The user sets the default opener for a link in their settings and then visits a link. + * + * @param resolvedUri The uri to open. This uri may have been transformed by port forwarding, so it + * may not match the original uri passed to `canOpenExternalUri`. Use `ctx.originalUri` to check the + * original uri. + * @param ctx Additional information about the uri being opened. + * @param token Cancellation token indicating that opening has been canceled. + * + * @return Thenable indicating that the opening has completed. + */ + openExternalUri(resolvedUri: Uri, ctx: OpenExternalUriContext, token: CancellationToken): Thenable | void; + } + + /** + * Additional information about the uri being opened. + */ + interface OpenExternalUriContext { + /** + * The uri that triggered the open. + * + * This is the original uri that the user clicked on or that was passed to `openExternal.` + * Due to port forwarding, this may not match the `resolvedUri` passed to `openExternalUri`. + */ + readonly sourceUri: Uri; + } + + /** + * Additional metadata about a registered `ExternalUriOpener`. + */ + interface ExternalUriOpenerMetadata { + + /** + * List of uri schemes the opener is triggered for. + * + * Currently only `http` and `https` are supported. + */ + readonly schemes: readonly string[] + + /** + * Text displayed to the user that explains what the opener does. + * + * For example, 'Open in browser preview' + */ + readonly label: string; + } + + namespace window { + /** + * Register a new `ExternalUriOpener`. + * + * When a uri is about to be opened, an `onOpenExternalUri:SCHEME` activation event is fired. + * + * @param id Unique id of the opener, such as `myExtension.browserPreview`. This is used in settings + * and commands to identify the opener. + * @param opener Opener to register. + * @param metadata Additional information about the opener. + * + * @returns Disposable that unregisters the opener. + */ + export function registerExternalUriOpener(id: string, opener: ExternalUriOpener, metadata: ExternalUriOpenerMetadata): Disposable; + } + + interface OpenExternalOptions { + /** + * Allows using openers contributed by extensions through `registerExternalUriOpener` + * when opening the resource. + * + * If `true`, the editor will check if any contributed openers can handle the + * uri, and fallback to the default opener behavior. + * + * If it is string, this specifies the id of the `ExternalUriOpener` + * that should be used if it is available. Use `'default'` to force the editor's + * standard external opener to be used. + */ + readonly allowContributedOpeners?: boolean | string; + } + + namespace env { + export function openExternal(target: Uri, options?: OpenExternalOptions): Thenable; + } + + //#endregion + + //#region https://github.com/Microsoft/vscode/issues/15178 + + /** + * Represents a tab within the window + */ + export interface Tab { + /** + * The text displayed on the tab + */ + readonly label: string; + + /** + * The position of the tab + */ + readonly viewColumn: ViewColumn; + + /** + * The resource represented by the tab if availble. + * If the tab contains more than one resource then primary will represent the left resource, and secondary the right one. + * Note: Not all editor types have a resource associated with them + */ + readonly resource?: Uri | { primary?: Uri, secondary?: Uri }; + + /** + * The identifier of the editor which the tab should contain, because + * not all tabs represent editors this may be undefined. + * This is equivalent to `viewType` for custom editors and notebooks. + * The built-in text editor has an id of 'default' for all configurations. + * Note: Tabs are not guaranteed to contain editors but this id represents what editor the tab will resolve if available + */ + readonly editorId?: string; + + /** + * Whether or not the tab is currently active + * Dictated by being the selected tab in the active group + */ + readonly isActive: boolean; + } + + export namespace window { + /** + * A list of all opened tabs + * Ordered from left to right + */ + export const tabs: readonly Tab[]; + + /** + * The currently active tab + * Undefined if no tabs are currently opened + */ + export const activeTab: Tab | undefined; + + /** + * An {@link Event} which fires when the array of {@link window.tabs tabs} + * has changed. + */ + export const onDidChangeTabs: Event; + + /** + * An {@link Event} which fires when the {@link window.activeTab activeTab} + * has changed. + */ + export const onDidChangeActiveTab: Event; + + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/120173 + /** + * The object describing the properties of the workspace trust request + */ + export interface WorkspaceTrustRequestOptions { + /** + * Custom message describing the user action that requires workspace + * trust. If omitted, a generic message will be displayed in the workspace + * trust request dialog. + */ + readonly message?: string; + } + + export namespace workspace { + /** + * Prompt the user to chose whether to trust the current workspace + * @param options Optional object describing the properties of the + * workspace trust request. + */ + export function requestWorkspaceTrust(options?: WorkspaceTrustRequestOptions): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/115616 @alexr00 + export enum PortAutoForwardAction { + Notify = 1, + OpenBrowser = 2, + OpenPreview = 3, + Silent = 4, + Ignore = 5, + OpenBrowserOnce = 6 + } + + export class PortAttributes { + /** + * The port number associated with this this set of attributes. + */ + port: number; + + /** + * The action to be taken when this port is detected for auto forwarding. + */ + autoForwardAction: PortAutoForwardAction; + + /** + * Creates a new PortAttributes object + * @param port the port number + * @param autoForwardAction the action to take when this port is detected + */ + constructor(port: number, autoForwardAction: PortAutoForwardAction); + } + + export interface PortAttributesProvider { + /** + * Provides attributes for the given port. For ports that your extension doesn't know about, simply + * return undefined. For example, if `providePortAttributes` is called with ports 3000 but your + * extension doesn't know anything about 3000 you should return undefined. + */ + providePortAttributes(port: number, pid: number | undefined, commandLine: string | undefined, token: CancellationToken): ProviderResult; + } + + export namespace workspace { + /** + * If your extension listens on ports, consider registering a PortAttributesProvider to provide information + * about the ports. For example, a debug extension may know about debug ports in it's debuggee. By providing + * this information with a PortAttributesProvider the extension can tell the editor that these ports should be + * ignored, since they don't need to be user facing. + * + * @param portSelector If registerPortAttributesProvider is called after you start your process then you may already + * know the range of ports or the pid of your process. All properties of a the portSelector must be true for your + * provider to get called. + * The `portRange` is start inclusive and end exclusive. + * @param provider The PortAttributesProvider + */ + export function registerPortAttributesProvider(portSelector: { pid?: number, portRange?: [number, number], commandMatcher?: RegExp }, provider: PortAttributesProvider): Disposable; + } + //#endregion + + //#region https://github.com/microsoft/vscode/issues/119904 @eamodio + + export interface SourceControlInputBox { + + /** + * Sets focus to the input. + */ + focus(): void; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/124024 @hediet @alexdima + + export namespace languages { + /** + * Registers an inline completion provider. + */ + export function registerInlineCompletionItemProvider(selector: DocumentSelector, provider: InlineCompletionItemProvider): Disposable; + } + + export interface InlineCompletionItemProvider { + /** + * Provides inline completion items for the given position and document. + * If inline completions are enabled, this method will be called whenever the user stopped typing. + * It will also be called when the user explicitly triggers inline completions or asks for the next or previous inline completion. + * Use `context.triggerKind` to distinguish between these scenarios. + */ + provideInlineCompletionItems(document: TextDocument, position: Position, context: InlineCompletionContext, token: CancellationToken): ProviderResult | T[]>; + } + + export interface InlineCompletionContext { + /** + * How the completion was triggered. + */ + readonly triggerKind: InlineCompletionTriggerKind; + + /** + * Provides information about the currently selected item in the autocomplete widget if it is visible. + * + * If set, provided inline completions must extend the text of the selected item + * and use the same range, otherwise they are not shown as preview. + * As an example, if the document text is `console.` and the selected item is `.log` replacing the `.` in the document, + * the inline completion must also replace `.` and start with `.log`, for example `.log()`. + * + * Inline completion providers are requested again whenever the selected item changes. + * + * The user must configure `"editor.suggest.preview": true` for this feature. + */ + readonly selectedCompletionInfo: SelectedCompletionInfo | undefined; + } + + export interface SelectedCompletionInfo { + range: Range; + text: string; + } + + /** + * How an {@link InlineCompletionItemProvider inline completion provider} was triggered. + */ + export enum InlineCompletionTriggerKind { + /** + * Completion was triggered automatically while editing. + * It is sufficient to return a single completion item in this case. + */ + Automatic = 0, + + /** + * Completion was triggered explicitly by a user gesture. + * Return multiple completion items to enable cycling through them. + */ + Explicit = 1, + } + + export class InlineCompletionList { + items: T[]; + + constructor(items: T[]); + } + + export class InlineCompletionItem { + /** + * The text to replace the range with. + * + * The text the range refers to should be a prefix of this value and must be a subword (`AB` and `BEF` are subwords of `ABCDEF`, but `Ab` is not). + */ + text: string; + + /** + * The range to replace. + * Must begin and end on the same line. + * + * Prefer replacements over insertions to avoid cache invalidation: + * Instead of reporting a completion that inserts an extension at the end of a word, + * the whole word should be replaced with the extended word. + */ + range?: Range; + + /** + * An optional {@link Command} that is executed *after* inserting this completion. + */ + command?: Command; + + constructor(text: string, range?: Range, command?: Command); + } + + + /** + * Be aware that this API will not ever be finalized. + */ + export namespace window { + export function getInlineCompletionItemController(provider: InlineCompletionItemProvider): InlineCompletionController; + } + + /** + * Be aware that this API will not ever be finalized. + */ + export interface InlineCompletionController { + /** + * Is fired when an inline completion item is shown to the user. + */ + // eslint-disable-next-line vscode-dts-event-naming + readonly onDidShowCompletionItem: Event>; + } + + /** + * Be aware that this API will not ever be finalized. + */ + export interface InlineCompletionItemDidShowEvent { + completionItem: T; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/126280 @mjbvz + + export interface NotebookCellData { + /** + * Mime type determines how the cell's `value` is interpreted. + * + * The mime selects which notebook renders is used to render the cell. + * + * If not set, internally the cell is treated as having a mime type of `text/plain`. + * Cells that set `language` to `markdown` instead are treated as `text/markdown`. + */ + mime?: string; + } + + export interface NotebookCell { + /** + * Mime type determines how the markup cell's `value` is interpreted. + * + * The mime selects which notebook renders is used to render the cell. + * + * If not set, internally the cell is treated as having a mime type of `text/plain`. + * Cells that set `language` to `markdown` instead are treated as `text/markdown`. + */ + mime: string | undefined; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/123713 @connor4312 + export interface TestRun { + /** + * Test coverage provider for this result. An extension can defer setting + * this until after a run is complete and coverage is available. + */ + coverageProvider?: TestCoverageProvider + // ... + } + + /** + * Provides information about test coverage for a test result. + * Methods on the provider will not be called until the test run is complete + */ + export interface TestCoverageProvider { + /** + * Returns coverage information for all files involved in the test run. + * @param token A cancellation token. + * @return Coverage metadata for all files involved in the test. + */ + provideFileCoverage(token: CancellationToken): ProviderResult; + + /** + * Give a FileCoverage to fill in more data, namely {@link FileCoverage.detailedCoverage}. + * The editor will only resolve a FileCoverage once, and onyl if detailedCoverage + * is undefined. + * + * @param coverage A coverage object obtained from {@link provideFileCoverage} + * @param token A cancellation token. + * @return The resolved file coverage, or a thenable that resolves to one. It + * is OK to return the given `coverage`. When no result is returned, the + * given `coverage` will be used. + */ + resolveFileCoverage?(coverage: T, token: CancellationToken): ProviderResult; + } + + /** + * A class that contains information about a covered resource. A count can + * be give for lines, branches, and functions in a file. + */ + export class CoveredCount { + /** + * Number of items covered in the file. + */ + covered: number; + /** + * Total number of covered items in the file. + */ + total: number; + + /** + * @param covered Value for {@link CovereredCount.covered} + * @param total Value for {@link CovereredCount.total} + */ + constructor(covered: number, total: number); + } + + /** + * Contains coverage metadata for a file. + */ + export class FileCoverage { + /** + * File URI. + */ + readonly uri: Uri; + + /** + * Statement coverage information. If the reporter does not provide statement + * coverage information, this can instead be used to represent line coverage. + */ + statementCoverage: CoveredCount; + + /** + * Branch coverage information. + */ + branchCoverage?: CoveredCount; + + /** + * Function coverage information. + */ + functionCoverage?: CoveredCount; + + /** + * Detailed, per-statement coverage. If this is undefined, the editor will + * call {@link TestCoverageProvider.resolveFileCoverage} when necessary. + */ + detailedCoverage?: DetailedCoverage[]; + + /** + * Creates a {@link FileCoverage} instance with counts filled in from + * the coverage details. + * @param uri Covered file URI + * @param detailed Detailed coverage information + */ + static fromDetails(uri: Uri, details: readonly DetailedCoverage[]): FileCoverage; + + /** + * @param uri Covered file URI + * @param statementCoverage Statement coverage information. If the reporter + * does not provide statement coverage information, this can instead be + * used to represent line coverage. + * @param branchCoverage Branch coverage information + * @param functionCoverage Function coverage information + */ + constructor( + uri: Uri, + statementCoverage: CoveredCount, + branchCoverage?: CoveredCount, + functionCoverage?: CoveredCount, + ); + } + + /** + * Contains coverage information for a single statement or line. + */ + export class StatementCoverage { + /** + * The number of times this statement was executed. If zero, the + * statement will be marked as un-covered. + */ + executionCount: number; + + /** + * Statement location. + */ + location: Position | Range; + + /** + * Coverage from branches of this line or statement. If it's not a + * conditional, this will be empty. + */ + branches: BranchCoverage[]; + + /** + * @param location The statement position. + * @param executionCount The number of times this statement was + * executed. If zero, the statement will be marked as un-covered. + * @param branches Coverage from branches of this line. If it's not a + * conditional, this should be omitted. + */ + constructor(executionCount: number, location: Position | Range, branches?: BranchCoverage[]); + } + + /** + * Contains coverage information for a branch of a {@link StatementCoverage}. + */ + export class BranchCoverage { + /** + * The number of times this branch was executed. If zero, the + * branch will be marked as un-covered. + */ + executionCount: number; + + /** + * Branch location. + */ + location?: Position | Range; + + /** + * @param executionCount The number of times this branch was executed. + * @param location The branch position. + */ + constructor(executionCount: number, location?: Position | Range); + } + + /** + * Contains coverage information for a function or method. + */ + export class FunctionCoverage { + /** + * The number of times this function was executed. If zero, the + * function will be marked as un-covered. + */ + executionCount: number; + + /** + * Function location. + */ + location: Position | Range; + + /** + * @param executionCount The number of times this function was executed. + * @param location The function position. + */ + constructor(executionCount: number, location: Position | Range); + } + + export type DetailedCoverage = StatementCoverage | FunctionCoverage; + + //#endregion + + + //#region https://github.com/microsoft/vscode/issues/15533 --- Type hierarchy --- @eskibear + + /** + * Represents an item of a type hierarchy, like a class or an interface. + */ + export class TypeHierarchyItem { + /** + * The name of this item. + */ + name: string; + + /** + * The kind of this item. + */ + kind: SymbolKind; + + /** + * Tags for this item. + */ + tags?: ReadonlyArray; + + /** + * More detail for this item, e.g. the signature of a function. + */ + detail?: string; + + /** + * The resource identifier of this item. + */ + uri: Uri; + + /** + * 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 class. Must be contained by the {@link TypeHierarchyItem.range range}-property. + */ + selectionRange: Range; + + /** + * Creates a new type hierarchy item. + * + * @param kind The kind of the item. + * @param name The name of the item. + * @param detail The details of the item. + * @param uri The Uri of the item. + * @param range The whole range of the item. + * @param selectionRange The selection range of the item. + */ + constructor(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range); + } + + /** + * The type hierarchy provider interface describes the contract between extensions + * and the type hierarchy feature. + */ + export interface TypeHierarchyProvider { + + /** + * Bootstraps type hierarchy by returning the item that is denoted by the given document + * and position. This item will be used as entry into the type graph. Providers should + * return `undefined` or `null` when there is no item at the given location. + * + * @param document The document in which the command was invoked. + * @param position The position at which the command was invoked. + * @param token A cancellation token. + * @returns One or multiple type hierarchy items or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined`, `null`, or an empty array. + */ + prepareTypeHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; + + /** + * Provide all supertypes for an item, e.g all types from which a type is derived/inherited. In graph terms this describes directed + * and annotated edges inside the type graph, e.g the given item is the starting node and the result is the nodes + * that can be reached. + * + * @param item The hierarchy item for which super types should be computed. + * @param token A cancellation token. + * @returns A set of supertypes or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined` or `null`. + */ + provideTypeHierarchySupertypes(item: TypeHierarchyItem, token: CancellationToken): ProviderResult; + + /** + * Provide all subtypes for an item, e.g all types which are derived/inherited from the given item. In + * graph terms this describes directed and annotated edges inside the type graph, e.g the given item is the starting + * node and the result is the nodes that can be reached. + * + * @param item The hierarchy item for which subtypes should be computed. + * @param token A cancellation token. + * @returns A set of subtypes or a thenable that resolves to such. The lack of a result can be + * signaled by returning `undefined` or `null`. + */ + provideTypeHierarchySubtypes(item: TypeHierarchyItem, token: CancellationToken): ProviderResult; + } + + export namespace languages { + /** + * Register a type hierarchy provider. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider A type hierarchy provider. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + */ + export function registerTypeHierarchyProvider(selector: DocumentSelector, provider: TypeHierarchyProvider): Disposable; + } + //#endregion + + //#region https://github.com/microsoft/vscode/issues/129037 + + enum LanguageStatusSeverity { + Information = 0, + Warning = 1, + Error = 2 + } + + interface LanguageStatusItem { + readonly id: string; + selector: DocumentSelector; + // todo@jrieken replace with boolean ala needsAttention + severity: LanguageStatusSeverity; + name: string | undefined; + text: string; + detail?: string; + command: Command | undefined; + accessibilityInformation?: AccessibilityInformation; + dispose(): void; + } + + namespace languages { + export function createLanguageStatusItem(id: string, selector: DocumentSelector): LanguageStatusItem; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/88716 + export interface QuickPickItem { + buttons?: QuickInputButton[]; + } + export interface QuickPick extends QuickInput { + readonly onDidTriggerItemButton: Event>; + } + export interface QuickPickItemButtonEvent { + button: QuickInputButton; + item: T; + } + + //#endregion +} diff --git a/packages/server/src/features/languageFeatures.ts b/packages/server/src/features/languageFeatures.ts index d5b690c83..219765565 100644 --- a/packages/server/src/features/languageFeatures.ts +++ b/packages/server/src/features/languageFeatures.ts @@ -288,6 +288,18 @@ export function register( return null; } }); + connection.onRequest(shared.GetInlayHintsRequest.type, async handler => { + + if (!isVueFile(handler.textDocument)) + return; + + return await getProjects() + ?.get(handler.textDocument.uri)?.service + .getInlayHints( + handler.textDocument.uri, + handler.range, + ); + }); } function isVueFile(textDocument: vscode.TextDocumentIdentifier) { diff --git a/packages/server/src/tsConfigs.ts b/packages/server/src/tsConfigs.ts index a880b3836..d24553e56 100644 --- a/packages/server/src/tsConfigs.ts +++ b/packages/server/src/tsConfigs.ts @@ -2,6 +2,20 @@ import * as vscode from 'vscode-languageserver'; import { TextDocument } from 'vscode-languageserver-textdocument'; import type * as ts from 'typescript/lib/tsserverlibrary'; +namespace ExperimentalProto { + export interface UserPreferences extends ts.UserPreferences { + displayPartsForJSDoc: true + + includeInlayParameterNameHints?: 'none' | 'literals' | 'all'; + includeInlayParameterNameHintsWhenArgumentMatchesName?: boolean; + includeInlayFunctionParameterTypeHints?: boolean; + includeInlayVariableTypeHints?: boolean; + includeInlayPropertyDeclarationTypeHints?: boolean; + includeInlayFunctionLikeReturnTypeHints?: boolean; + includeInlayEnumMemberValueHints?: boolean; + } +} + export async function getFormatOptions( connection: vscode.Connection, document: TextDocument, @@ -52,13 +66,13 @@ export async function getPreferences( { section: isTypeScriptDocument(document) ? 'typescript.preferences' : 'javascript.preferences', scopeUri: document.uri - } + }, ]); config = config ?? {}; preferencesConfig = preferencesConfig ?? {}; - const preferences: ts.UserPreferences & { displayPartsForJSDoc: true } = { + const preferences: ExperimentalProto.UserPreferences = { quotePreference: getQuoteStylePreference(preferencesConfig), importModuleSpecifierPreference: getImportModuleSpecifierPreference(preferencesConfig), importModuleSpecifierEnding: getImportModuleSpecifierEndingPreference(preferencesConfig), @@ -71,6 +85,7 @@ export async function getPreferences( includeCompletionsForImportStatements: config['suggest.includeCompletionsForImportStatements'] ?? true, includeCompletionsWithSnippetText: config['suggest.includeCompletionsWithSnippetText'] ?? true, displayPartsForJSDoc: true, + ...getInlayHintsPreferences(config), }; return preferences; @@ -84,6 +99,27 @@ function getQuoteStylePreference(config: any) { } } +function getInlayHintsPreferences(config: any) { + return { + includeInlayParameterNameHints: getInlayParameterNameHintsPreference(config), + includeInlayParameterNameHintsWhenArgumentMatchesName: !(config.inlayHints?.parameterNames?.suppressWhenArgumentMatchesName ?? true), + includeInlayFunctionParameterTypeHints: config.inlayHints?.parameterTypes?.enabled ?? false, + includeInlayVariableTypeHints: config.inlayHints?.variableTypes?.enabled ?? false, + includeInlayPropertyDeclarationTypeHints: config.inlayHints?.propertyDeclarationTypes?.enabled ?? false, + includeInlayFunctionLikeReturnTypeHints: config.inlayHints?.functionLikeReturnTypes?.enabled ?? false, + includeInlayEnumMemberValueHints: config.inlayHints?.enumMemberValues?.enabled ?? false, + } as const; +} + +function getInlayParameterNameHintsPreference(config: any) { + switch (config.inlayHints?.parameterNames?.enabled as string) { + case 'none': return 'none'; + case 'literals': return 'literals'; + case 'all': return 'all'; + default: return undefined; + } +} + function getImportModuleSpecifierPreference(config: any) { switch (config['importModuleSpecifier'] as string) { case 'project-relative': return 'project-relative'; diff --git a/packages/shared/src/requests.ts b/packages/shared/src/requests.ts index 750e04b54..841e7ea79 100644 --- a/packages/shared/src/requests.ts +++ b/packages/shared/src/requests.ts @@ -102,3 +102,27 @@ export namespace DetectDocumentNameCasesRequest { export type ErrorType = never; export const type = new rpc.RequestType('volar/getTagNameCaseServer'); } + +export enum InlayHintKind { + Other = 0, + Type = 1, + Parameter = 2, +} + +export interface InlayHint { + text: string; + position: vscode.Position; + kind?: InlayHintKind; + whitespaceBefore?: boolean; + whitespaceAfter?: boolean; +} + +export namespace GetInlayHintsRequest { + export type ParamsType = { + textDocument: vscode.TextDocumentIdentifier; + range: vscode.Range; + }; + export type ResponseType = InlayHint[] | undefined | null; + export type ErrorType = never; + export const type = new rpc.RequestType('volar/getInlayHints'); +} diff --git a/packages/vscode-typescript-languageservice/src/index.ts b/packages/vscode-typescript-languageservice/src/index.ts index e40e25178..a802f26db 100644 --- a/packages/vscode-typescript-languageservice/src/index.ts +++ b/packages/vscode-typescript-languageservice/src/index.ts @@ -11,6 +11,7 @@ import * as fileRename from './services/fileRename'; import * as codeActions from './services/codeAction'; import * as codeActionResolve from './services/codeActionResolve'; import * as hover from './services/hover'; +import * as inlayHints from './services/inlayHints'; import * as signatureHelp from './services/signatureHelp'; import * as selectionRanges from './services/selectionRanges'; import * as diagnostics from './services/diagnostics'; @@ -53,6 +54,7 @@ export function createLanguageService(ts: typeof import('typescript/lib/tsserver doComplete: completions2.register(languageService, getValidTextDocument, host), doCompletionResolve: completionResolve.register(languageService, getValidTextDocument, getTextDocument, host), doHover: hover.register(languageService, getValidTextDocument, getTextDocument, ts), + getInlayHints: inlayHints.register(languageService, getValidTextDocument, host, ts), doFormatting: formatting.register(languageService, getValidTextDocument, host), getSignatureHelp: signatureHelp.register(languageService, getValidTextDocument, ts), getSelectionRanges: selectionRanges.register(languageService, getValidTextDocument), diff --git a/packages/vscode-typescript-languageservice/src/services/inlayHints.ts b/packages/vscode-typescript-languageservice/src/services/inlayHints.ts new file mode 100644 index 000000000..24a850d0b --- /dev/null +++ b/packages/vscode-typescript-languageservice/src/services/inlayHints.ts @@ -0,0 +1,38 @@ +import * as shared from '@volar/shared'; +import type * as ts from 'typescript/lib/tsserverlibrary'; +import * as vscode from 'vscode-languageserver'; +import type { TextDocument } from 'vscode-languageserver-textdocument'; +import type { LanguageServiceHost } from '..'; + +export function register( + languageService: ts.LanguageService, + getTextDocument: (uri: string) => TextDocument | undefined, + host: LanguageServiceHost, + ts: typeof import('typescript/lib/tsserverlibrary'), +) { + return async (uri: string, range: vscode.Range) => { + + const document = getTextDocument(uri); + if (!document) return; + + const preferences = await host.getPreferences?.(document) ?? {}; + const fileName = shared.uriToFsPath(document.uri); + const start = document.offsetAt(range.start); + const end = document.offsetAt(range.end); + const inlayHints = languageService.provideInlayHints(fileName, { start, length: end - start }, preferences); + + return inlayHints.map(inlayHint => { + const result: shared.InlayHint = { + text: inlayHint.text, + kind: inlayHint.kind === ts.InlayHintKind.Type ? shared.InlayHintKind.Type + : inlayHint.kind === ts.InlayHintKind.Parameter ? shared.InlayHintKind.Parameter + : inlayHint.kind === ts.InlayHintKind.Enum ? shared.InlayHintKind.Other + : undefined, + whitespaceAfter: inlayHint.whitespaceAfter, + whitespaceBefore: inlayHint.whitespaceBefore, + position: document.positionAt(inlayHint.position), + } + return result; + }); + }; +} diff --git a/packages/vscode-typescript-languageservice/src/utils/transforms.ts b/packages/vscode-typescript-languageservice/src/utils/transforms.ts index cf7b29849..2c5bebc0b 100644 --- a/packages/vscode-typescript-languageservice/src/utils/transforms.ts +++ b/packages/vscode-typescript-languageservice/src/utils/transforms.ts @@ -19,6 +19,7 @@ export function entriesToLocations(entries: { fileName: string, textSpan: ts.Tex } return locations; } + export function entriesToLocationLinks(entries: ts.DefinitionInfo[], getTextDocument: (uri: string) => TextDocument | undefined): vscode.LocationLink[] { const locations: vscode.LocationLink[] = []; for (const entry of entries) { @@ -43,6 +44,7 @@ export function entriesToLocationLinks(entries: ts.DefinitionInfo[], getTextDocu } return locations; } + export function boundSpanToLocationLinks(info: ts.DefinitionInfoAndBoundSpan, originalDoc: TextDocument, getTextDocument: (uri: string) => TextDocument | undefined): vscode.LocationLink[] { const locations: vscode.LocationLink[] = []; if (!info.definitions) return locations; diff --git a/packages/vscode-vue-languageservice/src/languageService.ts b/packages/vscode-vue-languageservice/src/languageService.ts index 7c17954a2..9ceec806b 100644 --- a/packages/vscode-vue-languageservice/src/languageService.ts +++ b/packages/vscode-vue-languageservice/src/languageService.ts @@ -1,4 +1,4 @@ -import type * as vscode from 'vscode-languageserver'; +import * as vscode from 'vscode-languageserver'; import { TextDocument } from 'vscode-languageserver-textdocument'; import * as shared from '@volar/shared'; import { createSourceFile, SourceFile } from './sourceFile'; @@ -14,6 +14,7 @@ import * as completionResolve from './services/completionResolve'; import * as autoClose from './services/autoClose'; import * as refAutoClose from './services/refAutoClose'; import * as hover from './services/hover'; +import * as inlayHints from './services/inlayHints'; import * as diagnostics from './services/diagnostics'; import * as formatting from './services/formatting'; import * as definitions from './services/definition'; @@ -282,6 +283,7 @@ export function createLanguageService( getSemanticTokens: publicApiHook(semanticTokens.register(context, () => update(true)), false), doHover: publicApiHook(hover.register(context), isTemplateScriptPosition), + getInlayHints: publicApiHook(inlayHints.register(context), isTemplateScriptPosition), doComplete: publicApiHook(completions.register(context, () => scriptContentVersion), isTemplateScriptPosition), getCodeActions: publicApiHook(codeActions.register(context), false), @@ -318,7 +320,7 @@ export function createLanguageService( }, }; - function isTemplateScriptPosition(uri: string, pos: vscode.Position) { + function isTemplateScriptPosition(uri: string, posOrRange: vscode.Position | vscode.Range) { const sourceFile = sourceFiles.get(uri); if (!sourceFile) { @@ -328,16 +330,32 @@ export function createLanguageService( for (const sourceMap of sourceFile.getTsSourceMaps()) { if (sourceMap.lsType === 'script') continue; - for (const tsRange of sourceMap.getMappedRanges(pos)) { - if (tsRange.data.vueTag === 'template') { - return true; + if (vscode.Position.is(posOrRange)) { + for (const tsRange of sourceMap.getMappedRanges(posOrRange)) { + if (tsRange.data.vueTag === 'template') { + return true; + } + } + } + else { + for (const tsRange of sourceMap.getMappedRanges(posOrRange.start, posOrRange.end)) { + if (tsRange.data.vueTag === 'template') { + return true; + } } } } for (const sourceMap of sourceFile.getHtmlSourceMaps()) { - for (const _ of sourceMap.getMappedRanges(pos)) { - return true; + if (vscode.Position.is(posOrRange)) { + for (const _ of sourceMap.getMappedRanges(posOrRange)) { + return true; + } + } + else { + for (const _ of sourceMap.getMappedRanges(posOrRange.start, posOrRange.end)) { + return true; + } } } diff --git a/packages/vscode-vue-languageservice/src/services/inlayHints.ts b/packages/vscode-vue-languageservice/src/services/inlayHints.ts new file mode 100644 index 000000000..cbc431a39 --- /dev/null +++ b/packages/vscode-vue-languageservice/src/services/inlayHints.ts @@ -0,0 +1,59 @@ +import type * as vscode from 'vscode-languageserver'; +import type { ApiLanguageServiceContext } from '../types'; +import * as shared from '@volar/shared'; +import type { SourceFile } from '..'; + +export function register({ sourceFiles, getTsLs }: ApiLanguageServiceContext) { + return async (uri: string, range: vscode.Range) => { + + const sourceFile = sourceFiles.get(uri); + if (!sourceFile) return; + + const document = sourceFile.getTextDocument(); + const offsetRange = { + start: document.offsetAt(range.start), + end: document.offsetAt(range.end), + }; + + const tsResult = await getTsResult(sourceFile); + if (tsResult) return tsResult; + + async function getTsResult(sourceFile: SourceFile) { + + const result: shared.InlayHint[] = []; + + for (const sourceMap of sourceFile.getTsSourceMaps()) { + for (const mapping of sourceMap) { + + if (!mapping.data.capabilities.completion) + continue; + + if (mapping.sourceRange.start > offsetRange.end || mapping.sourceRange.end < offsetRange.start) + continue; + + const offset = mapping.mappedRange.start - mapping.sourceRange.start; + const start = Math.max(mapping.sourceRange.start, offsetRange.start) + offset; + const end = Math.min(mapping.sourceRange.end, offsetRange.end) + offset; + const tsHints = await getTsLs(sourceMap.lsType).getInlayHints(sourceMap.mappedDocument.uri, { + start: sourceMap.mappedDocument.positionAt(start), + end: sourceMap.mappedDocument.positionAt(end), + }); + + if (tsHints) { + for (const tsHint of tsHints) { + const vueLoc = sourceMap.getSourceRange(tsHint.position); + if (vueLoc) { + result.push({ + ...tsHint, + position: vueLoc.start, + }); + } + } + } + } + } + + return result; + } + } +} diff --git a/yarn.lock b/yarn.lock index 771c1a21c..bd0b81c58 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1667,7 +1667,7 @@ "@types/unist" "*" "@types/vfile-message" "*" -"@types/vscode@^1.58.1": +"@types/vscode@^1.60.0": version "1.60.0" resolved "https://registry.yarnpkg.com/@types/vscode/-/vscode-1.60.0.tgz#9330c317691b4f53441a18b598768faeeb71618a" integrity sha512-wZt3VTmzYrgZ0l/3QmEbCq4KAJ71K3/hmMQ/nfpv84oH8e81KKwPEoQ5v8dNCxfHFVJ1JabHKmCvqdYOoVm1Ow==